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 March 30, 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 .El
 116 .Pp
 117 If
 118 .Fn getfhat
 119 is passed the special value
 120 .Dv AT_FDCWD
 121 in the
 122 .Fa fd
 123 parameter, the current working directory is used and the behavior is
 124 identical to a call to
 125 .Fn getfth
 126 or
 127 .Fn lgetfh
 128 respectively, depending on whether or not the
 129 .Dv AT_SYMLINK_NOFOLLOW
 130 bit is set in
 131 .Fa flag .
 132 .Pp
 133 When
 134 .Fn getfhat
 135 is called with an absolute
 136 .Fa path
 137 without the
 138 .Dv AT_BENEATH
 139 flag, it ignores the
 140 .Fa fd
 141 argument.
 142 When
 143 .Dv AT_BENEATH
 144 is specified with an absolute
 145 .Fa path ,
 146 a directory passed by the
 147 .Fa fd
 148 argument is used as the topping point for the resolution.
 149 These system calls are restricted to the superuser.
 150 .Sh RETURN VALUES
 151 .Rv -std
 152 .Sh ERRORS
 153 The
 154 .Fn getfh
 155 and
 156 .Fn lgetfh
 157 system calls
 158 fail if one or more of the following are true:
 159 .Bl -tag -width Er
 160 .It Bq Er ENOTDIR
 161 A component of the path prefix of
 162 .Fa path
 163 is not a directory.
 164 .It Bq Er ENAMETOOLONG
 165 The length of a component of
 166 .Fa path
 167 exceeds 255 characters,
 168 or the length of
 169 .Fa path
 170 exceeds 1023 characters.
 171 .It Bq Er ENOENT
 172 The file referred to by
 173 .Fa path
 174 does not exist.
 175 .It Bq Er EACCES
 176 Search permission is denied for a component of the path prefix of
 177 .Fa path .
 178 .It Bq Er ELOOP
 179 Too many symbolic links were encountered in translating
 180 .Fa path .
 181 .It Bq Er EFAULT
 182 The
 183 .Fa fhp
 184 argument
 185 points to an invalid address.
 186 .It Bq Er EFAULT
 187 The
 188 .Fa path
 189 argument
 190 points to an invalid address.
 191 .It Bq Er EIO
 192 An
 193 .Tn I/O
 194 error occurred while reading from or writing to the file system.
 195 .It Bq Er EINTEGRITY
 196 Corrupted data was detected while reading from the file system.
 197 .It Bq Er ESTALE
 198 The file handle
 199 .Fa fhp
 200 is no longer valid.
 201 .El
 202 .Pp
 203 In addition to the errors returned by
 204 .Fn getfh ,
 205 and
 206 .Fn lgetfh ,
 207 the
 208 .Fn getfhat
 209 system call may fail if:
 210 .Bl -tag -width Er
 211 .It Bq Er EBADF
 212 The
 213 .Fa path
 214 argument does not specify an absolute path and the
 215 .Fa fd
 216 argument, is neither
 217 .Dv AT_FDCWD
 218 nor a valid file descriptor open for searching.
 219 .It Bq Er EINVAL
 220 The value of the
 221 .Fa flag
 222 argument is not valid.
 223 .It Bq Er ENOTDIR
 224 The
 225 .Fa path
 226 argument is not an absolute path and
 227 .Fa fd
 228 is neither
 229 .Dv AT_FDCWD
 230 nor a file descriptor associated with a directory.
 231 .Sh SEE ALSO
 232 .Xr fhopen 2 ,
 233 .Xr open 2 ,
 234 .Xr stat 2
 235 .Sh HISTORY
 236 The
 237 .Fn getfh
 238 system call first appeared in
 239 .Bx 4.4 .