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