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