1.\" $NetBSD: fhopen.2,v 1.5 2002/02/08 01:28:17 ross Exp $ 2.\" 3.\" Copyright (c) 1999 National Aeronautics & Space Administration 4.\" All rights reserved. 5.\" 6.\" This software was written by William Studenmund of the 7.\" Numerical Aerospace Similation Facility, NASA Ames Research Center. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of the National Aeronautics & Space Administration 18.\" nor the names of its contributors may be used to endorse or promote 19.\" products derived from this software without specific prior written 20.\" permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE NATIONAL AERONAUTICS & SPACE ADMINISTRATION 23.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 24.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 25.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE ADMINISTRATION OR CONTRIB- 26.\" UTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 27.\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 28.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 29.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 30.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 31.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 32.\" POSSIBILITY OF SUCH DAMAGE. 33.\"/ 34.Dd June 29, 1999 35.Dt FHOPEN 2 36.Os 37.Sh NAME 38.Nm fhopen , 39.Nm fhstat , 40.Nm fhstatfs 41.Nd access file via file handle 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.Fd #include \*[Lt]sys/types.h\*[Gt] 46.Fd #include \*[Lt]sys/stat.h\*[Gt] 47.Ft int 48.Fn fhopen "const fhandle_t *fhp" "int flags" 49.Ft int 50.Fn fhstat "const fhandle_t *fhp" "struct stat *sb" 51.Ft int 52.Fn fhstatfs "const fhandle_t *fhp" "struct statfs *buf" 53.Sh DESCRIPTION 54These functions provide a means to access a file given the file handle 55.Fa fhp . 56As this method bypasses directory access restrictions, these calls are 57restricted to the superuser. 58.Pp 59.Fn fhopen 60opens the file referenced by 61.Fa fhp 62for reading and/or writing as specified by the argument 63.Fa flags 64and returns the file descriptor to the calling process. The 65.Fa flags 66are specified by 67.Em or Ns 'ing 68together the flags used for the 69.Xr open 2 70call. All said flags are valid except for 71.Dv O_CREAT . 72.Pp 73.Fn fhstat 74and 75.Fn fhstatfs 76provide the functionality of the 77.Xr fstat 2 78and 79.Xr fstatfs 2 80calls except that they return information for the file refered to by 81.Fa fhp 82rather than an open file. 83.Sh RETURN VALUES 84Upon successful completion, 85.Fn fhopen 86returns the file descriptor for the opened file, while 87.Fn fhstat 88and 89.Fn fhstatfs 90return 0. 91Otherwise, -1 is returned and 92.Va errno 93is set to indicate the error. 94.Sh ERRORS 95In addition to the errors returned by 96.Xr open 2 , 97.Xr fstat 2 , 98and 99.Xr fstatfs 2 100respectivly, 101.Fn fhopen , 102.Fn fhstat , 103and 104.Fn fhstatfs 105will return 106.Bl -tag -width Er 107.It Bq Er EINVAL 108Calling 109.Fn fhopen 110with 111.Dv O_CREAT 112set. 113.It Bq Er ESTALE 114The file handle 115.Fa fhp 116is no longer valid. 117.El 118.Sh SEE ALSO 119.Xr fstat 2 , 120.Xr fstatfs 2 , 121.Xr getfh 2 , 122.Xr open 2 123.Sh HISTORY 124The 125.Fn fhopen , 126.Fn fhstat , 127and 128.Fn fhstatfs 129functions first appeared in 130.Nx 1.5 . 131