1.\" Copyright (c) 1989, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" Copyright (c) 2018 Gandi 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. Neither the name of the University nor the names of its contributors 14.\" may be used to endorse or promote products derived from this software 15.\" without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" @(#)getfh.2 8.1 (Berkeley) 6/9/93 30.\" $FreeBSD$ 31.\" 32.Dd December 11, 2018 33.Dt GETFH 2 34.Os 35.Sh NAME 36.Nm getfh , 37.Nm lgetfh , 38.Nm getfhat 39.Nd get file handle 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/param.h 44.In sys/mount.h 45.Ft int 46.Fn getfh "const char *path" "fhandle_t *fhp" 47.Ft int 48.Fn lgetfh "const char *path" "fhandle_t *fhp" 49.Ft int 50.Fn getfhat "int fd" "const char *path" "fhandle_t *fhp" "int flag" 51.Sh DESCRIPTION 52The 53.Fn getfh 54system call 55returns a file handle for the specified file or directory 56in the file handle pointed to by 57.Fa fhp . 58.Pp 59The 60.Fn lgetfh 61system call is like 62.Fn getfh 63except in the case where the named file is a symbolic link, 64in which case 65.Fn lgetfh 66returns information about the link, 67while 68.Fn getfh 69returns information about the file the link references. 70.Pp 71The 72.Fn getfhat 73system call is equivalent to 74.Fn getfh 75and 76.Fn lgetfh 77except when the 78.Fa path 79specifies a relative path, or the 80.Dv AT_BENEATH 81flag is provided. 82For 83.Fn getfhat 84and relative 85.Fa path , 86the status is retrieved from a file relative to 87the directory associated with the file descriptor 88.Fa fd 89instead of the current working directory. 90For 91.Dv AT_BENEATH 92and absolute 93.Fa path , 94the status is retrieved from a file specified by the 95.Fa path , 96but additional permission checks are performed, see below. 97.Pp 98The values for the 99.Fa flag 100are constructed by a bitwise-inclusive OR of flags from this list, 101defined in 102.In fcntl.h : 103.Bl -tag -width indent 104.It Dv AT_SYMLINK_NOFOLLOW 105If 106.Fa path 107names a symbolic link, the status of the symbolic link is returned. 108.It Dv AT_BENEATH 109Only stat files and directories below the topping directory. 110See the description of the 111.Dv O_BENEATH 112flag in the 113.Xr open 2 114manual page. 115.El 116.Pp 117If 118.Fn getfhat 119is passed the special value 120.Dv AT_FDCWD 121in the 122.Fa fd 123parameter, the current working directory is used and the behavior is 124identical to a call to 125.Fn getfth 126or 127.Fn lgetfh 128respectively, depending on whether or not the 129.Dv AT_SYMLINK_NOFOLLOW 130bit is set in 131.Fa flag . 132.Pp 133When 134.Fn getfhat 135is called with an absolute 136.Fa path 137without the 138.Dv AT_BENEATH 139flag, it ignores the 140.Fa fd 141argument. 142When 143.Dv AT_BENEATH 144is specified with an absolute 145.Fa path , 146a directory passed by the 147.Fa fd 148argument is used as the topping point for the resolution. 149These system calls are restricted to the superuser. 150.Sh RETURN VALUES 151.Rv -std 152.Sh ERRORS 153The 154.Fn getfh 155and 156.Fn lgetfh 157system calls 158fail if one or more of the following are true: 159.Bl -tag -width Er 160.It Bq Er ENOTDIR 161A component of the path prefix of 162.Fa path 163is not a directory. 164.It Bq Er ENAMETOOLONG 165The length of a component of 166.Fa path 167exceeds 255 characters, 168or the length of 169.Fa path 170exceeds 1023 characters. 171.It Bq Er ENOENT 172The file referred to by 173.Fa path 174does not exist. 175.It Bq Er EACCES 176Search permission is denied for a component of the path prefix of 177.Fa path . 178.It Bq Er ELOOP 179Too many symbolic links were encountered in translating 180.Fa path . 181.It Bq Er EFAULT 182The 183.Fa fhp 184argument 185points to an invalid address. 186.It Bq Er EFAULT 187The 188.Fa path 189argument 190points to an invalid address. 191.It Bq Er EIO 192An 193.Tn I/O 194error occurred while reading from or writing to the file system. 195.It Bq Er ESTALE 196The file handle 197.Fa fhp 198is no longer valid. 199.El 200.Pp 201In addition to the errors returned by 202.Fn getfh , 203and 204.Fn lgetfh , 205the 206.Fn getfhat 207system call may fail if: 208.Bl -tag -width Er 209.It Bq Er EBADF 210The 211.Fa path 212argument does not specify an absolute path and the 213.Fa fd 214argument, is neither 215.Dv AT_FDCWD 216nor a valid file descriptor open for searching. 217.It Bq Er EINVAL 218The value of the 219.Fa flag 220argument is not valid. 221.It Bq Er ENOTDIR 222The 223.Fa path 224argument is not an absolute path and 225.Fa fd 226is neither 227.Dv AT_FDCWD 228nor a file descriptor associated with a directory. 229.Sh SEE ALSO 230.Xr fhopen 2 , 231.Xr open 2 , 232.Xr stat 2 233.Sh HISTORY 234The 235.Fn getfh 236system call first appeared in 237.Bx 4.4 . 238