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 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. 133.Pp 134These system calls are restricted to the superuser. 135.Sh RETURN VALUES 136.Rv -std 137.Sh ERRORS 138The 139.Fn getfh 140and 141.Fn lgetfh 142system calls 143fail if one or more of the following are true: 144.Bl -tag -width Er 145.It Bq Er EPERM 146The caller does not have appropriate privilege to perform the operation. 147.It Bq Er ENOTDIR 148A component of the path prefix of 149.Fa path 150is not a directory. 151.It Bq Er ENAMETOOLONG 152The length of a component of 153.Fa path 154exceeds 255 characters, 155or the length of 156.Fa path 157exceeds 1023 characters. 158.It Bq Er ENOENT 159The file referred to by 160.Fa path 161does not exist. 162.It Bq Er EACCES 163Search permission is denied for a component of the path prefix of 164.Fa path . 165.It Bq Er ELOOP 166Too many symbolic links were encountered in translating 167.Fa path . 168.It Bq Er EFAULT 169The 170.Fa fhp 171argument 172points to an invalid address. 173.It Bq Er EFAULT 174The 175.Fa path 176argument 177points to an invalid address. 178.It Bq Er EIO 179An 180.Tn I/O 181error occurred while reading from or writing to the file system. 182.It Bq Er EINTEGRITY 183Corrupted data was detected while reading from the file system. 184.It Bq Er ESTALE 185The file handle 186.Fa fhp 187is no longer valid. 188.El 189.Pp 190In addition to the errors returned by 191.Fn getfh , 192and 193.Fn lgetfh , 194the 195.Fn getfhat 196system call may fail if: 197.Bl -tag -width Er 198.It Bq Er EBADF 199The 200.Fa path 201argument does not specify an absolute path and the 202.Fa fd 203argument, is neither 204.Dv AT_FDCWD 205nor a valid file descriptor open for searching. 206.It Bq Er EINVAL 207The value of the 208.Fa flag 209argument is not valid. 210.It Bq Er ENOTDIR 211The 212.Fa path 213argument is not an absolute path and 214.Fa fd 215is neither 216.Dv AT_FDCWD 217nor a file descriptor associated with a directory. 218.Sh SEE ALSO 219.Xr fhopen 2 , 220.Xr open 2 , 221.Xr stat 2 222.Sh HISTORY 223The 224.Fn getfh 225system call first appeared in 226.Bx 4.4 . 227