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