-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\"
.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
-.\" 1993 Michael Haardt, Ian Jackson.
-.\"
-.\" Permission is granted to make and distribute verbatim copies of this
-.\" manual provided the copyright notice and this permission notice are
-.\" preserved on all copies.
+.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
+.\" and Copyright (C) 2004, 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
-.\" Permission is granted to copy and distribute modified versions of this
-.\" manual under the conditions for verbatim copying, provided that the
-.\" entire resulting derived work is distributed under the terms of a
-.\" permission notice identical to this one.
-.\"
-.\" Since the Linux kernel and libraries are constantly changing, this
-.\" manual page may be incorrect or out-of-date. The author(s) assume no
-.\" responsibility for errors or omissions, or for damages resulting from
-.\" the use of the information contained herein. The author(s) may not
-.\" have taken the same level of care in the production of this manual,
-.\" which is licensed free of charge, as they might when working
-.\" professionally.
-.\"
-.\" Formatted or processed versions of this manual, if unaccompanied by
-.\" the source, must acknowledge the copyright and authors of this work.
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" Modified 1993-07-21 Rik Faith (faith@cs.unc.edu)
.\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com):
.\" Modified 2001-10-16 by aeb
.\" Modified 2002-04-23 by Roger Luethi <rl@hellgate.ch>
.\" Modified 2004-06-23 by Michael Kerrisk
+.\" 2007-06-10, mtk, various parts rewritten, and added BUGS section.
.\"
-.TH ACCESS 2 2004-06-23 "Linux" "Linux Programmer's Manual"
+.TH ACCESS 2 2021-08-27 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
.SH NAME
-access \- check user's permissions for a file
+access, faccessat, faccessat2 \- check user's permissions for a file
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.sp
+.PP
.BI "int access(const char *" pathname ", int " mode );
+.PP
+.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int faccessat(int " dirfd ", const char *" pathname ", int " \
+mode ", int " flags );
+ /* But see C library/kernel differences, below */
+.PP
+.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
+.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.B int syscall(SYS_faccessat2,
+.BI " int " dirfd ", const char *" pathname ", int " mode \
+", int " flags );
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR faccessat ():
+.nf
+ Since glibc 2.10:
+ _POSIX_C_SOURCE >= 200809L
+ Before glibc 2.10:
+ _ATFILE_SOURCE
.fi
.SH DESCRIPTION
.BR access ()
-checks whether the process would be allowed to read,
-write or test for existence of the file (or other file system
-object) whose name is
+checks whether the calling process can access the file
.IR pathname .
If
.I pathname
-is a symbolic link permissions of the file referred to by this
-symbolic link are tested.
-
+is a symbolic link, it is dereferenced.
+.PP
+The
.I mode
-is a mask consisting of one or more of
-.BR R_OK ", " W_OK ", " X_OK " and " F_OK .
-
-.BR R_OK ", " W_OK " and " X_OK
-request checking whether the file exists and has read, write and
-execute permissions, respectively.
+specifies the accessibility check(s) to be performed,
+and is either the value
+.BR F_OK ,
+.\" F_OK is defined as 0 on every system that I know of.
+or a mask consisting of the bitwise OR of one or more of
+.BR R_OK ", " W_OK ", and " X_OK .
.B F_OK
-just requests checking for the existence of the file.
-
-The tests depend on the permissions of the directories
-occurring in the path to the file, as given in
-.IR pathname ,
-and on the permissions of directories and files referred to by symbolic
-links encountered on the way.
-
-The check is done with the process's
+tests for the existence of the file.
+.BR R_OK ", " W_OK ", and " X_OK
+test whether the file exists and grants read, write, and
+execute permissions, respectively.
+.PP
+The check is done using the calling process's
.I real
-UID and GID, rather than with the effective IDs as is done when
-actually attempting an operation.
-This is to allow set-user-ID programs to
-easily determine the invoking user's authority.
-
-Only access bits are checked, not the file type or contents. Therefore, if
-a directory is found to be "writable," it probably means that files can be
-created in the directory, and not that the directory can be written as a
-file. Similarly, a DOS file may be found to be "executable," but the
-.BR execve (2)
-call will still fail.
-
-If the process has appropriate privileges, an implementation may
-indicate success for
+UID and GID, rather than the effective IDs as is done when
+actually attempting an operation (e.g.,
+.BR open (2))
+on the file.
+Similarly, for the root user, the check uses the set of
+permitted capabilities rather than the set of effective
+capabilities; and for non-root users, the check uses an empty set
+of capabilities.
+.PP
+This allows set-user-ID programs and capability-endowed programs
+to easily determine the invoking user's authority.
+In other words,
+.BR access ()
+does not answer the "can I read/write/execute this file?" question.
+It answers a slightly different question:
+"(assuming I'm a setuid binary) can
+.I the user who invoked me
+read/write/execute this file?",
+which gives set-user-ID programs the possibility to
+prevent malicious users from causing them to read files
+which users shouldn't be able to read.
+.PP
+If the calling process is privileged (i.e., its real UID is zero),
+then an
.B X_OK
-even if none of the execute file permission bits are set.
-.SH "RETURN VALUE"
-On success (all requested permissions granted), zero is returned.
+check is successful for a regular file if execute permission
+is enabled for any of the file owner, group, or other.
+.SS faccessat()
+.BR faccessat ()
+operates in exactly the same way as
+.BR access (),
+except for the differences described here.
+.PP
+If the pathname given in
+.I pathname
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.I dirfd
+(rather than relative to the current working directory of
+the calling process, as is done by
+.BR access ()
+for a relative pathname).
+.PP
+If
+.I pathname
+is relative and
+.I dirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I pathname
+is interpreted relative to the current working
+directory of the calling process (like
+.BR access ()).
+.PP
+If
+.I pathname
+is absolute, then
+.I dirfd
+is ignored.
+.PP
+.I flags
+is constructed by ORing together zero or more of the following values:
+.TP
+.B AT_EACCESS
+Perform access checks using the effective user and group IDs.
+By default,
+.BR faccessat ()
+uses the real IDs (like
+.BR access ()).
+.TP
+.B AT_SYMLINK_NOFOLLOW
+If
+.I pathname
+is a symbolic link, do not dereference it:
+instead return information about the link itself.
+.PP
+See
+.BR openat (2)
+for an explanation of the need for
+.BR faccessat ().
+.\"
+.SS faccessat2()
+The description of
+.BR faccessat ()
+given above corresponds to POSIX.1 and
+to the implementation provided by glibc.
+However, the glibc implementation was an imperfect emulation (see BUGS)
+that papered over the fact that the raw Linux
+.BR faccessat ()
+system call does not have a
+.I flags
+argument.
+To allow for a proper implementation, Linux 5.8 added the
+.BR faccessat2 ()
+system call, which supports the
+.I flags
+argument and allows a correct implementation of the
+.BR faccessat ()
+wrapper function.
+.SH RETURN VALUE
+On success (all requested permissions granted, or
+.I mode
+is
+.B F_OK
+and the file exists), zero is returned.
On error (at least one bit in
.I mode
-asked for a permission that is denied, or some other error occurred),
+asked for a permission that is denied, or
+.I mode
+is
+.B F_OK
+and the file does not exist, or some other error occurred),
\-1 is returned, and
.I errno
-is set appropriately.
+is set to indicate the error.
.SH ERRORS
-.BR access ()
-shall fail if:
.TP
.B EACCES
-The requested access would be denied to the file or search permission
+The requested access would be denied to the file, or search permission
is denied for one of the directories in the path prefix of
.IR pathname .
(See also
-.BR path_resolution (2).)
+.BR path_resolution (7).)
+.TP
+.B EBADF
+.RB ( faccessat ())
+.I pathname
+is relative but
+.I dirfd
+is neither
+.B AT_FDCWD
+.RB ( faccessat ())
+nor a valid file descriptor.
+.TP
+.B EFAULT
+.I pathname
+points outside your accessible address space.
+.TP
+.B EINVAL
+.I mode
+was incorrectly specified.
+.TP
+.B EINVAL
+.RB ( faccessat ())
+Invalid flag specified in
+.IR flags .
+.TP
+.B EIO
+An I/O error occurred.
.TP
.B ELOOP
Too many symbolic links were encountered in resolving
.I pathname
does not exist or is a dangling symbolic link.
.TP
+.B ENOMEM
+Insufficient kernel memory was available.
+.TP
.B ENOTDIR
A component used as a directory in
.I pathname
is not, in fact, a directory.
.TP
-.B EROFS
-Write permission was requested for a file on a read-only filesystem.
-.PP
-.BR access ()
-may fail if:
-.TP
-.B EFAULT
+.B ENOTDIR
+.RB ( faccessat ())
.I pathname
-points outside your accessible address space.
+is relative and
+.I dirfd
+is a file descriptor referring to a file other than a directory.
.TP
-.B EINVAL
-.I mode
-was incorrectly specified.
-.TP
-.B EIO
-An I/O error occurred.
+.B EPERM
+Write permission was requested to a file that has the immutable flag set.
+See also
+.BR ioctl_iflags (2).
.TP
-.B ENOMEM
-Insufficient kernel memory was available.
+.B EROFS
+Write permission was requested for a file on a read-only filesystem.
.TP
.B ETXTBSY
Write access was requested to an executable which is being
executed.
-.SH "LINUX NOTES"
-In kernels before 2.6.20,
-.BR access ()
-ignored the effect of the
-.B MS_NOEXEC
-flag if it was used to
-.BR mount (2)
-the underlying file system.
-Since kernel 2.6.20,
-.BR access ()
-honours this flag.
-.SH RESTRICTIONS
+.SH VERSIONS
+.BR faccessat ()
+was added to Linux in kernel 2.6.16;
+library support was added to glibc in version 2.4.
+.PP
+.BR faccessat2 ()
+was added to Linux in version 5.8.
+.SH STANDARDS
+.BR access ():
+SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
+.PP
+.BR faccessat ():
+POSIX.1-2008.
+.PP
+.BR faccessat2 ():
+Linux-specific.
+.SH NOTES
+.BR Warning :
+Using these calls to check if a user is authorized to, for example,
+open a file before actually doing so using
+.BR open (2)
+creates a security hole, because the user might exploit the short time
+interval between checking and opening the file to manipulate it.
+.BR "For this reason, the use of this system call should be avoided" .
+(In the example just described,
+a safer alternative would be to temporarily switch the process's
+effective user ID to the real ID and then call
+.BR open (2).)
+.PP
.BR access ()
-returns an error if any of the access types in the requested call
-fails, even if other types might be successful.
+always dereferences symbolic links.
+If you need to check the permissions on a symbolic link, use
+.BR faccessat ()
+with the flag
+.BR AT_SYMLINK_NOFOLLOW .
+.PP
+These calls return an error if any of the access types in
+.I mode
+is denied, even if some of the other access types in
+.I mode
+are permitted.
+.PP
+If the calling process has appropriate privileges (i.e., is superuser),
+POSIX.1-2001 permits an implementation to indicate success for an
+.B X_OK
+check even if none of the execute file permission bits are set.
+.\" HPU-UX 11 and Tru64 5.1 do this.
+Linux does not do this.
.PP
+A file is accessible only if the permissions on each of the
+directories in the path prefix of
+.I pathname
+grant search (i.e., execute) access.
+If any directory is inaccessible, then the
.BR access ()
-may not work correctly on NFS file systems with UID mapping enabled,
+call fails, regardless of the permissions on the file itself.
+.PP
+Only access bits are checked, not the file type or contents.
+Therefore, if a directory is found to be writable,
+it probably means that files can be created in the directory,
+and not that the directory can be written as a file.
+Similarly, a DOS file may be reported as executable, but the
+.BR execve (2)
+call will still fail.
+.PP
+These calls
+may not work correctly on NFSv2 filesystems with UID mapping enabled,
because UID mapping is done on the server and hidden from the client,
which checks permissions.
+(NFS versions 3 and higher perform the check on the server.)
+Similar problems can occur to FUSE mounts.
+.\"
+.\"
+.SS C library/kernel differences
+The raw
+.BR faccessat ()
+system call takes only the first three arguments.
+The
+.B AT_EACCESS
+and
+.B AT_SYMLINK_NOFOLLOW
+flags are actually implemented within the glibc wrapper function for
+.BR faccessat ().
+If either of these flags is specified, then the wrapper function employs
+.BR fstatat (2)
+to determine access permissions, but see BUGS.
+.\"
+.SS Glibc notes
+On older kernels where
+.BR faccessat ()
+is unavailable (and when the
+.B AT_EACCESS
+and
+.B AT_SYMLINK_NOFOLLOW
+flags are not specified),
+the glibc wrapper function falls back to the use of
+.BR access ().
+When
+.I pathname
+is a relative pathname,
+glibc constructs a pathname based on the symbolic link in
+.I /proc/self/fd
+that corresponds to the
+.I dirfd
+argument.
+.SH BUGS
+Because the Linux kernel's
+.BR faccessat ()
+system call does not support a
+.I flags
+argument, the glibc
+.BR faccessat ()
+wrapper function provided in glibc 2.32 and earlier
+emulates the required functionality using
+a combination of the
+.BR faccessat ()
+system call and
+.BR fstatat (2).
+However, this emulation does not take ACLs into account.
+Starting with glibc 2.33, the wrapper function avoids this bug
+by making use of the
+.BR faccessat2 ()
+system call where it is provided by the underlying kernel.
.PP
-Using
+In kernel 2.4 (and earlier) there is some strangeness in the handling of
+.B X_OK
+tests for superuser.
+If all categories of execute permission are disabled
+for a nondirectory file, then the only
.BR access ()
-to check if a user is authorized to e.g. open a file before actually
-doing so using
-.BR open (2)
-creates a security hole, because the user might exploit the short time
-interval between checking and opening the file to manipulate it.
-.SH "CONFORMING TO"
-SVr4, 4.3BSD, POSIX.1-2001.
-.SH "SEE ALSO"
+test that returns \-1 is when
+.I mode
+is specified as just
+.BR X_OK ;
+if
+.B R_OK
+or
+.B W_OK
+is also specified in
+.IR mode ,
+then
+.BR access ()
+returns 0 for such files.
+.\" This behavior appears to have been an implementation accident.
+Early 2.6 kernels (up to and including 2.6.3)
+also behaved in the same way as kernel 2.4.
+.PP
+In kernels before 2.6.20,
+these calls ignored the effect of the
+.B MS_NOEXEC
+flag if it was used to
+.BR mount (2)
+the underlying filesystem.
+Since kernel 2.6.20, the
+.B MS_NOEXEC
+flag is honored.
+.SH SEE ALSO
.BR chmod (2),
.BR chown (2),
-.BR faccessat (2),
.BR open (2),
-.BR path_resolution (2),
.BR setgid (2),
.BR setuid (2),
-.BR stat (2)
+.BR stat (2),
+.BR euidaccess (3),
+.BR credentials (7),
+.BR path_resolution (7),
+.BR symlink (7)
projects / thirdparty / man-pages.git / blobdiff