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