diff options
Diffstat (limited to 'upstream/debian-bookworm/man2/access.2')
| -rw-r--r-- | upstream/debian-bookworm/man2/access.2 | 443 |
1 files changed, 443 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man2/access.2 b/upstream/debian-bookworm/man2/access.2 new file mode 100644 index 00000000..d5fce785 --- /dev/null +++ b/upstream/debian-bookworm/man2/access.2 @@ -0,0 +1,443 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2004, 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" 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): +.\" Removed note about old kernel (pre-1.1.44) using wrong id on path. +.\" Modified 1996-03-18 by Martin Schulze (joey@infodrom.north.de): +.\" Stated more clearly how it behaves with symbolic links. +.\" Added correction due to Nick Duffek (nsd@bbc.com), aeb, 960426 +.\" Modified 1996-09-07 by Michael Haardt: +.\" Restrictions for NFS +.\" Modified 1997-09-09 by Joseph S. Myers <jsm28@cam.ac.uk> +.\" Modified 1998-01-13 by Michael Haardt: +.\" Using access is often insecure +.\" 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 2023-02-05 "Linux man-pages 6.03" +.SH NAME +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> +.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 calling process can access the file +.IR pathname . +If +.I pathname +is a symbolic link, it is dereferenced. +.PP +The +.I mode +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 +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 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 +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 +.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 to indicate the error. +.SH ERRORS +.TP +.B EACCES +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 (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 +.IR pathname . +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +A component of +.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 ENOTDIR +.RB ( faccessat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B EPERM +Write permission was requested to a file that has the immutable flag set. +See also +.BR ioctl_iflags (2). +.TP +.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 VERSIONS +.BR faccessat () +was added in Linux 2.6.16; +library support was added in glibc 2.4. +.PP +.BR faccessat2 () +was added in Linux 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 () +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 () +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 +In Linux 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 () +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 Linux 2.6 (up to and including Linux 2.6.3) +also behaved in the same way as Linux 2.4. +.PP +Before Linux 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 Linux 2.6.20, the +.B MS_NOEXEC +flag is honored. +.SH SEE ALSO +.BR chmod (2), +.BR chown (2), +.BR open (2), +.BR setgid (2), +.BR setuid (2), +.BR stat (2), +.BR euidaccess (3), +.BR credentials (7), +.BR path_resolution (7), +.BR symlink (7) |