diff options
Diffstat (limited to 'man2/access.2')
| -rw-r--r-- | man2/access.2 | 468 |
1 files changed, 0 insertions, 468 deletions
diff --git a/man2/access.2 b/man2/access.2 deleted file mode 100644 index 7e60a33..0000000 --- a/man2/access.2 +++ /dev/null @@ -1,468 +0,0 @@ -.\" 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 2024-01-01 "Linux man-pages 6.7" -.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> -.P -.BI "int access(const char *" pathname ", int " mode ); -.P -.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */" -.B #include <unistd.h> -.P -.BI "int faccessat(int " dirfd ", const char *" pathname ", int " \ -mode ", int " flags ); - /* But see C library/kernel differences, below */ -.P -.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */" -.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" -.B #include <unistd.h> -.P -.B int syscall(SYS_faccessat2, -.BI " int " dirfd ", const char *" pathname ", int " mode \ -", int " flags ); -.fi -.P -.RS -4 -Feature Test Macro Requirements for glibc (see -.BR feature_test_macros (7)): -.RE -.P -.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. -.P -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. -.P -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. -.P -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. -.P -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. -.P -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). -.P -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 ()). -.P -If -.I pathname -is absolute, then -.I dirfd -is ignored. -.P -.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 -.BR AT_EMPTY_PATH " (since Linux 5.8)" -If -.I pathname -is an empty string, operate on the file referred to by -.I dirfd -(which may have been obtained using the -.BR open (2) -.B O_PATH -flag). -In this case, -.I dirfd -can refer to any type of file, not just a directory. -If -.I dirfd -is -.BR AT_FDCWD , -the call operates on the current working directory. -This flag is Linux-specific; define -.B _GNU_SOURCE -to obtain its definition. -.TP -.B AT_SYMLINK_NOFOLLOW -If -.I pathname -is a symbolic link, do not dereference it: -instead return information about the link itself. -.P -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 -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. -.\" -.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 STANDARDS -.TP -.BR access () -.TQ -.BR faccessat () -POSIX.1-2008. -.TP -.BR faccessat2 () -Linux. -.SH HISTORY -.TP -.BR access () -SVr4, 4.3BSD, POSIX.1-2001. -.TP -.BR faccessat () -Linux 2.6.16, -glibc 2.4. -.TP -.BR faccessat2 () -Linux 5.8. -.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).) -.P -.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 . -.P -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. -.P -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. -.P -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. -.P -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. -.\" -.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. -.P -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. -.P -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) |