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.Dd November 30, 2022 30.Dt GETFH 2 31.Os 32.Sh NAME 33.Nm getfh , 34.Nm lgetfh , 35.Nm getfhat 36.Nd get file handle 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In sys/param.h 41.In sys/mount.h 42.Ft int 43.Fn getfh "const char *path" "fhandle_t *fhp" 44.Ft int 45.Fn lgetfh "const char *path" "fhandle_t *fhp" 46.Ft int 47.Fn getfhat "int fd" "const char *path" "fhandle_t *fhp" "int flag" 48.Sh DESCRIPTION 49The 50.Fn getfh 51system call 52returns a file handle for the specified file or directory 53in the file handle pointed to by 54.Fa fhp . 55.Pp 56The 57.Fn lgetfh 58system call is like 59.Fn getfh 60except in the case where the named file is a symbolic link, 61in which case 62.Fn lgetfh 63returns information about the link, 64while 65.Fn getfh 66returns information about the file the link references. 67.Pp 68The 69.Fn getfhat 70system call is equivalent to 71.Fn getfh 72and 73.Fn lgetfh 74except when the 75.Fa path 76specifies a relative path. 77For 78.Fn getfhat 79and relative 80.Fa path , 81the status is retrieved from a file relative to 82the directory associated with the file descriptor 83.Fa fd 84instead of the current working directory. 85.Pp 86The values for the 87.Fa flag 88are constructed by a bitwise-inclusive OR of flags from this list, 89defined in 90.In fcntl.h : 91.Bl -tag -width indent 92.It Dv AT_SYMLINK_NOFOLLOW 93If 94.Fa path 95names a symbolic link, the status of the symbolic link is returned. 96.It Dv AT_RESOLVE_BENEATH 97Only walk paths below the directory specified by the 98.Ar fd 99descriptor. 100See the description of the 101.Dv O_RESOLVE_BENEATH 102flag in the 103.Xr open 2 104manual page. 105.El 106.Pp 107If 108.Fn getfhat 109is passed the special value 110.Dv AT_FDCWD 111in the 112.Fa fd 113parameter, the current working directory is used and the behavior is 114identical to a call to 115.Fn getfth 116or 117.Fn lgetfh 118respectively, depending on whether or not the 119.Dv AT_SYMLINK_NOFOLLOW 120bit is set in 121.Fa flag . 122.Pp 123When 124.Fn getfhat 125is called with an absolute 126.Fa path , 127it ignores the 128.Fa fd 129argument. 130.Pp 131These system calls are restricted to the superuser. 132.Sh RETURN VALUES 133.Rv -std 134.Sh ERRORS 135The 136.Fn getfh 137and 138.Fn lgetfh 139system calls 140fail if one or more of the following are true: 141.Bl -tag -width Er 142.It Bq Er EPERM 143The caller does not have appropriate privilege to perform the operation. 144.It Bq Er ENOTDIR 145A component of the path prefix of 146.Fa path 147is not a directory. 148.It Bq Er ENAMETOOLONG 149The length of a component of 150.Fa path 151exceeds 255 characters, 152or the length of 153.Fa path 154exceeds 1023 characters. 155.It Bq Er ENOENT 156The file referred to by 157.Fa path 158does not exist. 159.It Bq Er EACCES 160Search permission is denied for a component of the path prefix of 161.Fa path . 162.It Bq Er ELOOP 163Too many symbolic links were encountered in translating 164.Fa path . 165.It Bq Er EFAULT 166The 167.Fa fhp 168argument 169points to an invalid address. 170.It Bq Er EFAULT 171The 172.Fa path 173argument 174points to an invalid address. 175.It Bq Er EIO 176An 177.Tn I/O 178error occurred while reading from or writing to the file system. 179.It Bq Er EINTEGRITY 180Corrupted data was detected while reading from the file system. 181.It Bq Er ESTALE 182The file handle 183.Fa fhp 184is no longer valid. 185.El 186.Pp 187In addition to the errors returned by 188.Fn getfh , 189and 190.Fn lgetfh , 191the 192.Fn getfhat 193system call may fail if: 194.Bl -tag -width Er 195.It Bq Er EBADF 196The 197.Fa path 198argument does not specify an absolute path and the 199.Fa fd 200argument, is neither 201.Dv AT_FDCWD 202nor a valid file descriptor open for searching. 203.It Bq Er EINVAL 204The value of the 205.Fa flag 206argument is not valid. 207.It Bq Er ENOTDIR 208The 209.Fa path 210argument is not an absolute path and 211.Fa fd 212is neither 213.Dv AT_FDCWD 214nor a file descriptor associated with a directory. 215.Sh SEE ALSO 216.Xr fhopen 2 , 217.Xr open 2 , 218.Xr stat 2 219.Sh HISTORY 220The 221.Fn getfh 222system call first appeared in 223.Bx 4.4 . 224The 225.Fn lgetfh 226system call first appeared in 227.Fx 5.3 . 228The 229.Fn getfhat 230system call first appeared in 231.Fx 12.1 . 232