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 February 23, 2021 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. 80For 81.Fn getfhat 82and relative 83.Fa path , 84the status is retrieved from a file relative to 85the directory associated with the file descriptor 86.Fa fd 87instead of the current working directory. 88.Pp 89The values for the 90.Fa flag 91are constructed by a bitwise-inclusive OR of flags from this list, 92defined in 93.In fcntl.h : 94.Bl -tag -width indent 95.It Dv AT_SYMLINK_NOFOLLOW 96If 97.Fa path 98names a symbolic link, the status of the symbolic link is returned. 99.It Dv AT_RESOLVE_BENEATH 100Only walk paths below the directory specified by the 101.Ar fd 102descriptor. 103See the description of the 104.Dv O_RESOLVE_BENEATH 105flag in the 106.Xr open 2 107manual page. 108.El 109.Pp 110If 111.Fn getfhat 112is passed the special value 113.Dv AT_FDCWD 114in the 115.Fa fd 116parameter, the current working directory is used and the behavior is 117identical to a call to 118.Fn getfth 119or 120.Fn lgetfh 121respectively, depending on whether or not the 122.Dv AT_SYMLINK_NOFOLLOW 123bit is set in 124.Fa flag . 125.Pp 126When 127.Fn getfhat 128is called with an absolute 129.Fa path , 130it ignores the 131.Fa fd 132argument. 133These system calls are restricted to the superuser. 134.Sh RETURN VALUES 135.Rv -std 136.Sh ERRORS 137The 138.Fn getfh 139and 140.Fn lgetfh 141system calls 142fail if one or more of the following are true: 143.Bl -tag -width Er 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 . 224