man2/access.2

   1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   2 .\"             and Copyright (C) 1993 Michael Haardt, Ian Jackson.
   3 .\" and Copyright (C) 2004, 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" Modified 1993-07-21 Rik Faith (faith@cs.unc.edu)
  28 .\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com):
  29 .\"   Removed note about old kernel (pre-1.1.44) using wrong id on path.
  30 .\" Modified 1996-03-18 by Martin Schulze (joey@infodrom.north.de):
  31 .\"   Stated more clearly how it behaves with symbolic links.
  32 .\" Added correction due to Nick Duffek (nsd@bbc.com), aeb, 960426
  33 .\" Modified 1996-09-07 by Michael Haardt:
  34 .\"   Restrictions for NFS
  35 .\" Modified 1997-09-09 by Joseph S. Myers <jsm28@cam.ac.uk>
  36 .\" Modified 1998-01-13 by Michael Haardt:
  37 .\"   Using access is often insecure
  38 .\" Modified 2001-10-16 by aeb
  39 .\" Modified 2002-04-23 by Roger Luethi <rl@hellgate.ch>
  40 .\" Modified 2004-06-23 by Michael Kerrisk
  41 .\" 2007-06-10, mtk, various parts rewritten, and added BUGS section.
  42 .\"
  43 .TH ACCESS 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  44 .SH NAME
  45 access, faccessat, faccessat2 \- check user's permissions for a file
  46 .SH SYNOPSIS
  47 .nf
  48 .B #include <unistd.h>
  49 .PP
  50 .BI "int access(const char *" pathname ", int " mode );
  51 .PP
  52 .BR "#include <fcntl.h>" "            /* Definition of " AT_* " constants */"
  53 .B #include <unistd.h>
  54 .PP
  55 .BI "int faccessat(int " dirfd ", const char *" pathname ", int " \
  56 mode ", int " flags );
  57                 /* But see C library/kernel differences, below */
  58 .PP
  59 .BR "#include <fcntl.h>" "            /* Definition of " AT_* " constants */"
  60 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
  61 .B #include <unistd.h>
  62 .PP
  63 .BI "int syscall(SYS_faccessat2,"
  64 .BI "            int " dirfd ", const char *" pathname ", int " mode \
  65 ", int " flags );
  66 .fi
  67 .PP
  68 .RS -4
  69 Feature Test Macro Requirements for glibc (see
  70 .BR feature_test_macros (7)):
  71 .RE
  72 .PP
  73 .BR faccessat ():
  74 .nf
  75     Since glibc 2.10:
  76         _POSIX_C_SOURCE >= 200809L
  77     Before glibc 2.10:
  78         _ATFILE_SOURCE
  79 .fi
  80 .SH DESCRIPTION
  81 .BR access ()
  82 checks whether the calling process can access the file
  83 .IR pathname .
  84 If
  85 .I pathname
  86 is a symbolic link, it is dereferenced.
  87 .PP
  88 The
  89 .I mode
  90 specifies the accessibility check(s) to be performed,
  91 and is either the value
  92 .BR F_OK ,
  93 .\" F_OK is defined as 0 on every system that I know of.
  94 or a mask consisting of the bitwise OR of one or more of
  95 .BR R_OK ", " W_OK ", and " X_OK .
  96 .B F_OK
  97 tests for the existence of the file.
  98 .BR R_OK ", " W_OK ", and " X_OK
  99 test whether the file exists and grants read, write, and
 100 execute permissions, respectively.
 101 .PP
 102 The check is done using the calling process's
 103 .I real
 104 UID and GID, rather than the effective IDs as is done when
 105 actually attempting an operation (e.g.,
 106 .BR open (2))
 107 on the file.
 108 Similarly, for the root user, the check uses the set of
 109 permitted capabilities rather than the set of effective
 110 capabilities; and for non-root users, the check uses an empty set
 111 of capabilities.
 112 .PP
 113 This allows set-user-ID programs and capability-endowed programs
 114 to easily determine the invoking user's authority.
 115 In other words,
 116 .BR access ()
 117 does not answer the "can I read/write/execute this file?" question.
 118 It answers a slightly different question:
 119 "(assuming I'm a setuid binary) can
 120 .I the user who invoked me
 121 read/write/execute this file?",
 122 which gives set-user-ID programs the possibility to
 123 prevent malicious users from causing them to read files
 124 which users shouldn't be able to read.
 125 .PP
 126 If the calling process is privileged (i.e., its real UID is zero),
 127 then an
 128 .B X_OK
 129 check is successful for a regular file if execute permission
 130 is enabled for any of the file owner, group, or other.
 131 .SS faccessat()
 132 .BR faccessat ()
 133 operates in exactly the same way as
 134 .BR access (),
 135 except for the differences described here.
 136 .PP
 137 If the pathname given in
 138 .I pathname
 139 is relative, then it is interpreted relative to the directory
 140 referred to by the file descriptor
 141 .I dirfd
 142 (rather than relative to the current working directory of
 143 the calling process, as is done by
 144 .BR access ()
 145 for a relative pathname).
 146 .PP
 147 If
 148 .I pathname
 149 is relative and
 150 .I dirfd
 151 is the special value
 152 .BR AT_FDCWD ,
 153 then
 154 .I pathname
 155 is interpreted relative to the current working
 156 directory of the calling process (like
 157 .BR access ()).
 158 .PP
 159 If
 160 .I pathname
 161 is absolute, then
 162 .I dirfd
 163 is ignored.
 164 .PP
 165 .I flags
 166 is constructed by ORing together zero or more of the following values:
 167 .TP
 168 .B AT_EACCESS
 169 Perform access checks using the effective user and group IDs.
 170 By default,
 171 .BR faccessat ()
 172 uses the real IDs (like
 173 .BR access ()).
 174 .TP
 175 .B AT_SYMLINK_NOFOLLOW
 176 If
 177 .I pathname
 178 is a symbolic link, do not dereference it:
 179 instead return information about the link itself.
 180 .PP
 181 See
 182 .BR openat (2)
 183 for an explanation of the need for
 184 .BR faccessat ().
 185 .\"
 186 .SS faccessat2()
 187 The description of
 188 .BR faccessat ()
 189 given above corresponds to POSIX.1 and
 190 to the implementation provided by glibc.
 191 However, the glibc implementation was an imperfect emulation (see BUGS)
 192 that papered over the fact that the raw Linux
 193 .BR faccessat ()
 194 system call does not have a
 195 .I flags
 196 argument.
 197 To allow for a proper implementation, Linux 5.8 added the
 198 .BR faccessat2 ()
 199 system call, which supports the
 200 .I flags
 201 argument and allows a correct implementation of the
 202 .BR faccessat ()
 203 wrapper function.
 204 .SH RETURN VALUE
 205 On success (all requested permissions granted, or
 206 .I mode
 207 is
 208 .B F_OK
 209 and the file exists), zero is returned.
 210 On error (at least one bit in
 211 .I mode
 212 asked for a permission that is denied, or
 213 .I mode
 214 is
 215 .B F_OK
 216 and the file does not exist, or some other error occurred),
 217 \-1 is returned, and
 218 .I errno
 219 is set to indicate the error.
 220 .SH ERRORS
 221 .BR access ()
 222 and
 223 .BR faccessat ()
 224 shall fail if:
 225 .TP
 226 .B EACCES
 227 The requested access would be denied to the file, or search permission
 228 is denied for one of the directories in the path prefix of
 229 .IR pathname .
 230 (See also
 231 .BR path_resolution (7).)
 232 .TP
 233 .B ELOOP
 234 Too many symbolic links were encountered in resolving
 235 .IR pathname .
 236 .TP
 237 .B ENAMETOOLONG
 238 .I pathname
 239 is too long.
 240 .TP
 241 .B ENOENT
 242 A component of
 243 .I pathname
 244 does not exist or is a dangling symbolic link.
 245 .TP
 246 .B ENOTDIR
 247 A component used as a directory in
 248 .I pathname
 249 is not, in fact, a directory.
 250 .TP
 251 .B EROFS
 252 Write permission was requested for a file on a read-only filesystem.
 253 .PP
 254 .BR access ()
 255 and
 256 .BR faccessat ()
 257 may fail if:
 258 .TP
 259 .B EFAULT
 260 .I pathname
 261 points outside your accessible address space.
 262 .TP
 263 .B EINVAL
 264 .I mode
 265 was incorrectly specified.
 266 .TP
 267 .B EIO
 268 An I/O error occurred.
 269 .TP
 270 .B ENOMEM
 271 Insufficient kernel memory was available.
 272 .TP
 273 .B ETXTBSY
 274 Write access was requested to an executable which is being
 275 executed.
 276 .PP
 277 The following additional errors can occur for
 278 .BR faccessat ():
 279 .TP
 280 .B EBADF
 281 .I dirfd
 282 is not a valid file descriptor.
 283 .TP
 284 .B EINVAL
 285 Invalid flag specified in
 286 .IR flags .
 287 .TP
 288 .B ENOTDIR
 289 .I pathname
 290 is relative and
 291 .I dirfd
 292 is a file descriptor referring to a file other than a directory.
 293 .SH VERSIONS
 294 .BR faccessat ()
 295 was added to Linux in kernel 2.6.16;
 296 library support was added to glibc in version 2.4.
 297 .PP
 298 .BR faccessat2 ()
 299 was added to Linux in version 5.8.
 300 .SH CONFORMING TO
 301 .BR access ():
 302 SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
 303 .PP
 304 .BR faccessat ():
 305 POSIX.1-2008.
 306 .PP
 307 .BR faccessat2 ():
 308 Linux-specific.
 309 .SH NOTES
 310 .BR Warning :
 311 Using these calls to check if a user is authorized to, for example,
 312 open a file before actually doing so using
 313 .BR open (2)
 314 creates a security hole, because the user might exploit the short time
 315 interval between checking and opening the file to manipulate it.
 316 .BR "For this reason, the use of this system call should be avoided" .
 317 (In the example just described,
 318 a safer alternative would be to temporarily switch the process's
 319 effective user ID to the real ID and then call
 320 .BR open (2).)
 321 .PP
 322 .BR access ()
 323 always dereferences symbolic links.
 324 If you need to check the permissions on a symbolic link, use
 325 .BR faccessat ()
 326 with the flag
 327 .BR AT_SYMLINK_NOFOLLOW .
 328 .PP
 329 These calls return an error if any of the access types in
 330 .I mode
 331 is denied, even if some of the other access types in
 332 .I mode
 333 are permitted.
 334 .PP
 335 If the calling process has appropriate privileges (i.e., is superuser),
 336 POSIX.1-2001 permits an implementation to indicate success for an
 337 .B X_OK
 338 check even if none of the execute file permission bits are set.
 339 .\" HPU-UX 11 and Tru64 5.1 do this.
 340 Linux does not do this.
 341 .PP
 342 A file is accessible only if the permissions on each of the
 343 directories in the path prefix of
 344 .I pathname
 345 grant search (i.e., execute) access.
 346 If any directory is inaccessible, then the
 347 .BR access ()
 348 call fails, regardless of the permissions on the file itself.
 349 .PP
 350 Only access bits are checked, not the file type or contents.
 351 Therefore, if a directory is found to be writable,
 352 it probably means that files can be created in the directory,
 353 and not that the directory can be written as a file.
 354 Similarly, a DOS file may be reported as executable, but the
 355 .BR execve (2)
 356 call will still fail.
 357 .PP
 358 These calls
 359 may not work correctly on NFSv2 filesystems with UID mapping enabled,
 360 because UID mapping is done on the server and hidden from the client,
 361 which checks permissions.  (NFS versions 3 and higher perform the check on
 362 the server.)
 363 Similar problems can occur to FUSE mounts.
 364 .\"
 365 .\"
 366 .SS C library/kernel differences
 367 The raw
 368 .BR faccessat ()
 369 system call takes only the first three arguments.
 370 The
 371 .B AT_EACCESS
 372 and
 373 .B AT_SYMLINK_NOFOLLOW
 374 flags are actually implemented within the glibc wrapper function for
 375 .BR faccessat ().
 376 If either of these flags is specified, then the wrapper function employs
 377 .BR fstatat (2)
 378 to determine access permissions, but see BUGS.
 379 .\"
 380 .SS Glibc notes
 381 On older kernels where
 382 .BR faccessat ()
 383 is unavailable (and when the
 384 .B AT_EACCESS
 385 and
 386 .B AT_SYMLINK_NOFOLLOW
 387 flags are not specified),
 388 the glibc wrapper function falls back to the use of
 389 .BR access ().
 390 When
 391 .I pathname
 392 is a relative pathname,
 393 glibc constructs a pathname based on the symbolic link in
 394 .IR /proc/self/fd
 395 that corresponds to the
 396 .IR dirfd
 397 argument.
 398 .SH BUGS
 399 Because the Linux kernel's
 400 .BR faccessat ()
 401 system call does not support a
 402 .I flags
 403 argument, the glibc
 404 .BR faccessat ()
 405 wrapper function provided in glibc 2.32 and earlier
 406 emulates the required functionality using
 407 a combination of the
 408 .BR faccessat ()
 409 system call and
 410 .BR fstatat (2).
 411 However, this emulation does not take ACLs into account.
 412 Starting with glibc 2.33, the wrapper function avoids this bug
 413 by making use of the
 414 .BR faccessat2 ()
 415 system call where it is provided by the underlying kernel.
 416 .PP
 417 In kernel 2.4 (and earlier) there is some strangeness in the handling of
 418 .B X_OK
 419 tests for superuser.
 420 If all categories of execute permission are disabled
 421 for a nondirectory file, then the only
 422 .BR access ()
 423 test that returns \-1 is when
 424 .I mode
 425 is specified as just
 426 .BR X_OK ;
 427 if
 428 .B R_OK
 429 or
 430 .B W_OK
 431 is also specified in
 432 .IR mode ,
 433 then
 434 .BR access ()
 435 returns 0 for such files.
 436 .\" This behavior appears to have been an implementation accident.
 437 Early 2.6 kernels (up to and including 2.6.3)
 438 also behaved in the same way as kernel 2.4.
 439 .PP
 440 In kernels before 2.6.20,
 441 these calls ignored the effect of the
 442 .B MS_NOEXEC
 443 flag if it was used to
 444 .BR mount (2)
 445 the underlying filesystem.
 446 Since kernel 2.6.20, the
 447 .B MS_NOEXEC
 448 flag is honored.
 449 .SH SEE ALSO
 450 .BR chmod (2),
 451 .BR chown (2),
 452 .BR open (2),
 453 .BR setgid (2),
 454 .BR setuid (2),
 455 .BR stat (2),
 456 .BR euidaccess (3),
 457 .BR credentials (7),
 458 .BR path_resolution (7),
 459 .BR symlink (7)