lib/libc/sys/access.2

   1 .\"     $NetBSD: access.2,v 1.32 2013/01/13 08:15:02 dholland Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)access.2    8.2 (Berkeley) 4/1/94
  31 .\"
  32 .Dd January 12, 2013
  33 .Dt ACCESS 2
  34 .Os
  35 .Sh NAME
  36 .Nm access ,
  37 .Nm faccessat
  38 .Nd check access permissions of a file or pathname
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In unistd.h
  43 .Ft int
  44 .Fn access "const char *path" "int mode"
  45 .In fcntl.h
  46 .Ft int
  47 .Fn faccessat "int fd" "const char *path" "int mode" "int flags"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn access
  51 function checks the accessibility of the
  52 file named by
  53 .Fa path .
  54 The
  55 .Fn faccessat
  56 function checks the accessibility of the file named by
  57 .Fa path
  58 using
  59 .Fa fd
  60 as the starting point for relative pathnames.
  61 If
  62 .Fa fd
  63 is
  64 .Dv AT_FDCWD
  65 the current directory is used.
  66 Calling
  67 .Fn access
  68 is equivalent to calling
  69 .Fn faccessat
  70 with
  71 .Fa fd
  72 set to
  73 .Dv AT_FDCWD
  74 and
  75 .Fa flags
  76 set to 0.
  77 .Pp
  78 The form of access to check is specified by the bitwise or of the
  79 following values for
  80 .Fa mode :
  81 .Bl -tag -width W_OK
  82 .It Dv R_OK
  83 Check for read permission.
  84 .It Dv W_OK
  85 Check for write permission.
  86 .It Dv X_OK
  87 Check for execute/search permission.
  88 .It Dv F_OK
  89 Check only for existence.
  90 .El
  91 .Pp
  92 All components of the pathname
  93 .Fa path
  94 are checked for access permissions as well.
  95 .Pp
  96 .\" Maybe this paragraph should be removed...
  97 The owner of a file has permission checked with respect to the
  98 .Dq owner
  99 read, write, and execute mode bits, members of the file's group
 100 other than the owner have permission checked with respect to the
 101 .Dq group
 102 mode bits, and all others have permissions checked with respect to
 103 the
 104 .Dq other
 105 mode bits.
 106 .Pp
 107 The file descriptor
 108 .Fa fd
 109 must name a directory.
 110 Search permission is required on this directory.
 111 .\"    (These alternatives await a decision about the semantics of O_SEARCH)
 112 .\" Search permission is required on this directory, except if
 113 .\" .Fa fd
 114 .\" was opened with the
 115 .\" .Dv O_SEARCH
 116 .\" flag.
 117 .\"    - or -
 118 .\" The directory referred to by
 119 .\" .Fa fd
 120 .\" must have been opened with the
 121 .\" .Dv O_SEARCH
 122 .\" flag.
 123 .\"    - or -
 124 .\" The directory referred to by
 125 .\" .Fa fd
 126 .\" must have been opened with the
 127 .\" .Dv O_SEARCH
 128 .\" flag or must be searchable by the current process at the time the
 129 .\" call is made.
 130 .Pp
 131 The
 132 .Fa flags
 133 argument to
 134 .Fn faccessat
 135 can specify the following optional behavior:
 136 .Bl -tag -width AT_SYMLINK_NOFOLLOW
 137 .It AT_EACCESS
 138 Use the effective user and group IDs instead of the real user and
 139 group IDs for checking permission.
 140 See discussion below.
 141 .It AT_SYMLINK_NOFOLLOW
 142 Do not follow a symbolic link encountered as the last component in
 143 .Fa path .
 144 .El
 145 .Pp
 146 For
 147 .Fn access ,
 148 and
 149 .Fn faccessat
 150 when the
 151 .Dv AT_EACCESS
 152 flag is not passed, the real user ID and the real group ID are used
 153 for checking permission in place of the effective user ID and
 154 effective group ID.
 155 This affects only set-user-ID and set-group-ID programs, which should
 156 not use these functions.
 157 (For other programs, the real and effective IDs are the same.)
 158 .Pp
 159 For processes running with super-user privileges, these functions may
 160 return success for read and write checks regardless of whether read
 161 and write permission bits are actually set.
 162 This reflects the fact that the super-user may read and write all
 163 files regardless of permission settings.
 164 However, even for the super-user, an execute check using
 165 .Dv X_OK
 166 will succeed only if the target object has at least one of its
 167 execute permission bits set.
 168 .\" XXX: Is this true of search permission and directories? (I believe so.)
 169 (This does not guarantee that the target object can necessarily be
 170 successfully executed.
 171 See
 172 .Xr execve 2 . )
 173 .Sh RETURN VALUES
 174 The
 175 .Fn access
 176 and
 177 .Fn faccessat
 178 functions succeed and return 0 if, at some point in the recent past,
 179 the target object named by
 180 .Fa path
 181 existed and its permission settings allowed the requested access as
 182 described above.
 183 If the requested access would not have been granted, the object did
 184 not exist, or the path lookup failed, the value \-1 is returned
 185 and the value of
 186 .Va errno
 187 is set to reflect what went wrong.
 188 .Sh ERRORS
 189 These functions fail if:
 190 .Bl -tag -width Er
 191 .It Bq Er EACCES
 192 Search permission is denied for
 193 .Fa fd ,
 194 or for the current directory, or for a directory in the prefix of
 195 .Fa path ;
 196 or the permission bits on the target file system object do not permit
 197 the requested access.
 198 .It Bq Er EBADF
 199 The file descriptor
 200 .Fa fd
 201 is not open and is not
 202 .Dv AT_FDCWD .
 203 .\"    (possibly -- future)
 204 .\" or was not opened for searching with
 205 .\" .Dv O_SEARCH .
 206 .It Bq Er EFAULT
 207 .Fa path
 208 points outside the process's allocated address space.
 209 .It Bq Er EINVAL
 210 The
 211 .Fa mode
 212 or
 213 .Fa flags
 214 argument contained an invalid value.
 215 .It Bq Er EIO
 216 An I/O error occurred while reading from or writing to the file system.
 217 .It Bq Er ELOOP
 218 Too many symbolic links were encountered in translating the pathname.
 219 .It Bq Er ENAMETOOLONG
 220 A component of a pathname exceeded
 221 .Brq Dv NAME_MAX
 222 characters, or an entire path name exceeded
 223 .Brq Dv PATH_MAX
 224 characters.
 225 .It Bq Er ENOENT
 226 The named file does not exist.
 227 .It Bq Er ENOTDIR
 228 The file descriptor
 229 .Fa fd
 230 does not name a directory, or a component of the path prefix is not a
 231 directory.
 232 .It Bq Er EROFS
 233 Write access is requested for a file on a read-only file system.
 234 .It Bq Er ETXTBSY
 235 Write access is requested for a pure procedure (shared text)
 236 file presently being executed.
 237 .El
 238 .Sh SEE ALSO
 239 .Xr chmod 2 ,
 240 .Xr execve 2 ,
 241 .Xr stat 2 ,
 242 .Xr secure_path 3
 243 .Sh STANDARDS
 244 The
 245 .Fn access
 246 function conforms to
 247 .St -p1003.1-90 .
 248 .Fn faccessat
 249 function conforms to
 250 .St -p1003.1-2008 .
 251 .\" This paragraph could be moved to the end of DESCRIPTION if people
 252 .\" don't like having it here.
 253 .Pp
 254 Note that
 255 .Fn faccessat
 256 violates the historic convention that system calls whose names begin
 257 with `f' operate on file handles rather than paths.
 258 There is no equivalent to
 259 .Fn access
 260 for checking access properties of an already-opened file.
 261 .Sh SECURITY CONSIDERATIONS
 262 Because the results of these calls reflect the state of the file
 263 system at the time they ran, and the file system can potentially be
 264 modified between that time and the time the caller attempts to act on
 265 the results, they should
 266 .Em never
 267 be used for security enforcement.
 268 .Pp
 269 Privileged programs that need to restrict their actions to files or
 270 directories properly accessible to unprivileged users
 271 .Em must
 272 do this by assuming or restoring an unprivileged state (see
 273 .Xr seteuid 2 )
 274 when performing the pertinent actions.
 275 Checking in advance (with
 276 .Fn access
 277 or any other method) and performing such actions while privileged
 278 introduces a race condition that in most cases is easily exploitable
 279 by even a naive adversary.
 280 .Pp
 281 Even for non-privileged programs, the opportunity for the world to
 282 change after the call runs makes
 283 .Fn access
 284 and
 285 .Fn faccessat
 286 not very useful.
 287 In general only
 288 .Dv F_OK
 289 should be used, and that sparingly.
 290 The other checks may occasionally be useful for user interface or
 291 diagnostic purposes.