access.3p (11534B)
- '\" 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 .