1.\" $NetBSD: fhopen.2,v 1.1 1999/06/30 01:32:15 wrstuden 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 April 6, 2025 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.In sys/param.h 46.In sys/mount.h 47.In sys/stat.h 48.Ft int 49.Fn fhopen "const fhandle_t *fhp" "int flags" 50.Ft int 51.Fn fhstat "const fhandle_t *fhp" "struct stat *sb" 52.Ft int 53.Fn fhstatfs "const fhandle_t *fhp" "struct statfs *buf" 54.Sh DESCRIPTION 55These system calls provide a means to access a file given the file handle 56.Fa fhp . 57As this method bypasses directory access restrictions, these calls are 58restricted to the superuser. 59.Pp 60The 61.Fn fhopen 62system call 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 70argument 71is specified by 72.Em or Ns 'ing 73together the flags used for the 74.Xr open 2 75system call. 76All said flags are valid except for 77.Dv O_CREAT . 78If the file handle refers to a named attribute or named attribute 79directory, the 80.Dv O_NAMEDATTR 81flag must be specified. 82.Pp 83The 84.Fn fhstat 85and 86.Fn fhstatfs 87system calls 88provide the functionality of the 89.Xr fstat 2 90and 91.Xr fstatfs 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; 99otherwise the value \-1 is returned and the global variable 100.Va errno 101is set to indicate the error. 102.Pp 103.Rv -std fhstat fhstatfs 104.Sh ERRORS 105In addition to the errors returned by 106.Xr open 2 , 107.Xr fstat 2 , 108and 109.Xr fstatfs 2 110respectively, 111.Fn fhopen , 112.Fn fhstat , 113and 114.Fn fhstatfs 115will return 116.Bl -tag -width Er 117.It Bq Er EINVAL 118Calling 119.Fn fhopen 120with 121.Dv O_CREAT 122set. 123.It Bq Er ENOATTR 124The file handle does not refer to a named attribute or named attribute 125directory although the 126.Dv O_NAMEDATTR 127flag was specified. 128.It Bq Er ENOATTR 129The file handle refers to a named attribute or named attribute directory 130although the 131.Dv O_NAMEDATTR 132flag was not specified. 133.It Bq Er ESTALE 134The file handle 135.Fa fhp 136is no longer valid. 137.El 138.Sh SEE ALSO 139.Xr fstat 2 , 140.Xr fstatfs 2 , 141.Xr getfh 2 , 142.Xr open 2 , 143.Xr named_attribute 9 144.Sh HISTORY 145The 146.Fn fhopen , 147.Fn fhstat , 148and 149.Fn fhstatfs 150system calls first appeared in 151.Nx 1.5 152and were adapted to 153.Fx 4.0 154by 155.An Alfred Perlstein . 156.Sh AUTHORS 157This manual page was written by 158.An William Studenmund 159for 160.Nx . 161