lib/libc/sys/getfh.2

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