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 February 23, 2021
  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 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 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 .