diff options
Diffstat (limited to '')
| -rw-r--r-- | upstream/mageia-cauldron/man3p/access.3p | 369 |
1 files changed, 369 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3p/access.3p b/upstream/mageia-cauldron/man3p/access.3p new file mode 100644 index 00000000..edbff485 --- /dev/null +++ b/upstream/mageia-cauldron/man3p/access.3p @@ -0,0 +1,369 @@ +'\" et +.TH ACCESS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +access, faccessat +\(em determine accessibility of a file +descriptor +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> +.P +int access(const char *\fIpath\fP, int \fIamode\fP); +.P +#include <fcntl.h> +.P +int faccessat(int \fIfd\fP, const char *\fIpath\fP, int \fIamode\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIaccess\fR() +function shall check the file named by the pathname pointed to by the +.IR path +argument for accessibility according to the bit pattern contained in +.IR amode . +The checks for accessibility (including directory permissions +checked during pathname resolution) shall be performed using the +real user ID in place of the effective user ID and the real group +ID in place of the effective group ID. +.P +The value of +.IR amode +is either the bitwise-inclusive OR of the access permissions to be +checked (R_OK, W_OK, X_OK) or the existence test (F_OK). +.P +If any access permissions are checked, each shall be checked +individually, as described in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.5" ", " "File Access Permissions", +except that where that description refers to execute permission for +a process with appropriate privileges, an implementation may indicate +success for X_OK even if execute permission is not granted to any user. +.P +The +\fIfaccessat\fR() +function, when called with a +.IR flag +value of zero, shall be equivalent to the +\fIaccess\fR() +function, except in the case where +.IR path +specifies a relative path. In this case the file whose accessibility is +to be determined shall be located relative to the directory associated +with the file descriptor +.IR fd +instead of the current working directory. +If the access mode of the open file description associated with +the file descriptor is not O_SEARCH, the function shall check +whether directory searches are permitted using the current +permissions of the directory underlying the file descriptor. +If the access mode is O_SEARCH, the function shall not perform the check. +.P +If +\fIfaccessat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and, if flag is +zero, the behavior shall be identical to a call to +\fIaccess\fR(). +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR <fcntl.h> : +.IP AT_EACCESS 12 +The checks for accessibility (including directory permissions +checked during pathname resolution) shall be performed using the +effective user ID and group ID instead of the real user ID and group ID +as required in a call to +\fIaccess\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. Otherwise, +these functions shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Permission bits of the file mode do not permit the requested access, or +search permission is denied on a component of the path prefix. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c +<slash> +character and ends with one or more trailing +<slash> +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EROFS +Write access is requested for a file on a read-only file system. +.P +The +\fIfaccessat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR EINVAL +The value of the \fIamode\fP argument is invalid. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ETXTBSY +Write access is requested for a pure procedure (shared text) file that +is being executed. +.P +The +\fIfaccessat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Testing for the Existence of a File" +.P +The following example tests whether a file named +.BR myfile +exists in the +.BR /tmp +directory. +.sp +.RS 4 +.nf + +#include <unistd.h> +\&... +int result; +const char *pathname = "/tmp/myfile"; +.P +result = access (pathname, F_OK); +.fi +.P +.RE +.SH "APPLICATION USAGE" +Use of these functions is discouraged since by the time the +returned information is acted upon, it is out-of-date. (That is, +acting upon the information always leads to a time-of-check-to-time-of-use +race condition.) An application should instead attempt the action +itself and handle the +.BR [EACCES] +error that occurs if the file is not accessible (with a change of +effective user and group IDs beforehand, and perhaps a change back +afterwards, in the case where +\fIaccess\fR() +or +\fIfaccessat\fR() +without AT_EACCES would have been used.) +.P +Historically, one of the uses of +\fIaccess\fR() +was in set-user-ID root programs to check whether the user running +the program had access to a file. This relied on ``super-user'' +privileges which were granted based on the effective user ID being +zero, so that when +\fIaccess\fR() +used the real user ID to check accessibility those privileges +were not taken into account. On newer systems where privileges +can be assigned which have no association with user or group IDs, +if a program with such privileges calls +\fIaccess\fR(), +the change of IDs has no effect on the privileges and therefore +they are taken into account in the accessibility checks. Thus, +\fIaccess\fR() +(and +\fIfaccessat\fR() +with flag zero) cannot be used for this historical purpose in +such programs. Likewise, if a system provides any additional or +alternate file access control mechanisms that are not user ID-based, +they will still be taken into account. +.P +If a relative pathname is used, no account is taken of whether +the current directory (or the directory associated with the +file descriptor +.IR fd ) +is accessible via any absolute pathname. Applications using +\fIaccess\fR(), +or +\fIfaccessat\fR() +without AT_EACCES, may consequently act as if the file would be +accessible to a user with the real user ID and group ID of the +process when such a user would not in practice be able to access the file +because access would be denied at some point above the current directory +(or the directory associated with the file descriptor +.IR fd ) +in the file hierarchy. +.P +If +\fIaccess\fR() +or +\fIfaccessat\fR() +is used with W_OK to check for write access to a directory which has +the S_ISVTX bit set, a return value indicating the directory is +writable can be misleading since some operations on files in the +directory would not be permitted based on the ownership of those files +(see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.3" ", " "Directory Protection"). +.P +Additional values of +.IR amode +other than the set defined in the description may be valid; for +example, if a system has extended access controls. +.P +The use of the AT_EACCESS value for +.IR flag +enables functionality not available in +\fIaccess\fR(). +.SH RATIONALE +In early proposals, some inadequacies in the +\fIaccess\fR() +function led to the creation of an +\fIeaccess\fR() +function because: +.IP " 1." 4 +Historical implementations of +\fIaccess\fR() +do not test file access correctly when the process' +real user ID is +superuser. In particular, they always return zero when testing execute +permissions without regard to whether the file is executable. +.IP " 2." 4 +The superuser has complete access to all files on a system. As a +consequence, programs started by the superuser and switched to the +effective user ID +with lesser privileges cannot use +\fIaccess\fR() +to test their file access permissions. +.P +However, the historical model of +\fIeaccess\fR() +does not resolve problem (1), so this volume of POSIX.1\(hy2017 now allows +\fIaccess\fR() +to behave in the desired way because several implementations have +corrected the problem. It was also argued that problem (2) is more +easily solved by using +\fIopen\fR(), +\fIchdir\fR(), +or one of the +.IR exec +functions as appropriate and responding to the error, rather than +creating a new function that would not be as reliable. Therefore, +\fIeaccess\fR() +is not included in this volume of POSIX.1\(hy2017. +.P +The sentence concerning appropriate privileges and execute permission +bits +reflects the two possibilities implemented by historical +implementations when checking superuser access for X_OK. +.P +New implementations are discouraged from returning X_OK unless at least +one execution permission bit is set. +.P +The purpose of the +\fIfaccessat\fR() +function is to enable the checking of the accessibility of files in +directories other than the current working directory without exposure +to race conditions. Any part of the path of a file could be changed in +parallel to a call to +\fIaccess\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIfaccessat\fR() +function it can be guaranteed that the file tested for accessibility is +located relative to the desired directory. +.SH "FUTURE DIRECTIONS" +These functions may be formally deprecated (for example, by shading +them OB) in a future version of this standard. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.5" ", " "File Access Permissions", +.IR "\fB<fcntl.h>\fP", +.IR "\fB<unistd.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |