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