1.\" $NetBSD: fhopen.2,v 1.17 2009/08/05 23:15:52 wiz 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 Simulation 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 August 5, 2009 35.Dt FHOPEN 2 36.Os 37.Sh NAME 38.Nm fhopen , 39.Nm fhstat , 40.Nm fhstatvfs 41.Nd access file via file handle 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In sys/types.h 46.In sys/mount.h 47.Ft int 48.Fn fhopen "const void *fhp" "size_t fh_size" "int flags" 49.In sys/stat.h 50.Ft int 51.Fn fhstat "const void *fhp" "size_t fh_size" "struct stat *sb" 52.In sys/statvfs.h 53.Ft int 54.Fn fhstatvfs "const void *fhp" "size_t fh_size" "struct statvfs *buf" 55.Ft int 56.Fn fhstatvfs1 "const void *fhp" "size_t fh_size" "struct statvfs *buf" "int flags" 57.Sh DESCRIPTION 58These functions provide a means to access a file given the opaque file handle 59.Fa fhp 60and the size 61.Fa fh_size 62of the opaque object as returned by 63.Xr getfh 2 . 64As this method bypasses directory access restrictions, these calls are 65restricted to the superuser. 66.Pp 67.Fn fhopen 68opens the file referenced by 69.Fa fhp 70for reading and/or writing as specified by the argument 71.Fa flags 72and returns the file descriptor to the calling process. 73The 74.Fa flags 75are specified by 76.Em or Ns 'ing 77together the flags used for the 78.Xr open 2 79call. 80All said flags are valid except for 81.Dv O_CREAT . 82.Pp 83.Fn fhstat , 84.Fn fhstatvfs , 85and 86.Fn fhstatvfs1 87provide the functionality of the 88.Xr fstat 2 , 89.Xr fstatvfs 2 , 90and 91.Xr fstatvfs1 2 92calls except that they return information for the file referred to by 93.Fa fhp 94rather than an open file. 95.Sh RETURN VALUES 96Upon successful completion, 97.Fn fhopen 98returns the file descriptor for the opened file, while 99.Fn fhstat , 100.Fn fhstatvfs , 101and 102.Fn fhstatvfs1 103return 0. 104Otherwise, \-1 is returned and 105.Va errno 106is set to indicate the error. 107.Sh ERRORS 108In addition to the errors returned by 109.Xr open 2 , 110.Xr fstat 2 , 111.Xr fstatvfs 2 , 112and 113.Xr fstatvfs1 2 , 114respectively, 115.Fn fhopen , 116.Fn fhstat , 117.Fn fhstatvfs , 118and 119.Fn fhstatvfs1 120will return 121.Bl -tag -width Er 122.It Bq Er EINVAL 123Calling 124.Fn fhopen 125with 126.Dv O_CREAT 127set or invalid 128.Fa fh_size . 129.It Bq Er ESTALE 130The file handle 131.Fa fhp 132is no longer valid. 133.El 134.Sh SEE ALSO 135.Xr fstat 2 , 136.Xr fstatvfs 2 , 137.Xr fstatvfs1 2 , 138.Xr getfh 2 , 139.Xr open 2 140.Sh HISTORY 141The 142.Fn fhopen , 143and 144.Fn fhstat 145functions first appeared in 146.Nx 1.5 . 147The 148.Fn fhstatvfs 149function replaced 150.Fn fhstatfs 151in 152.Nx 3.0 . 153