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