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