NAME
access,
faccessat —
check access permissions of a file or pathname
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <unistd.h>
int
access(
const char
*path,
int mode);
#include <fcntl.h>
int
faccessat(
int
fd,
const char *path,
int mode,
int flags);
DESCRIPTION
The
access() function checks the accessibility of the file
named by
path. The
faccessat()
function checks the accessibility of the file named by
path using
fd as the starting
point for relative pathnames. If
fd is
AT_FDCWD
the current directory is used. Calling
access() is equivalent to calling
faccessat() with
fd set to
AT_FDCWD
and
flags set to 0.
The form of access to check is specified by the bitwise or of the following
values for
mode:
-
-
R_OK
- Check for read permission.
-
-
W_OK
- Check for write permission.
-
-
X_OK
- Check for execute/search permission.
-
-
F_OK
- Check only for existence.
All components of the pathname
path are checked for access
permissions as well.
The owner of a file has permission checked with respect to the
“owner” read, write, and execute mode bits, members of the file's
group other than the owner have permission checked with respect to the
“group” mode bits, and all others have permissions checked with
respect to the “other” mode bits.
The file descriptor
fd must name a directory. Search
permission is required on this directory.
The
flags argument to
faccessat() can
specify the following optional behavior:
-
-
- AT_EACCESS
- Use the effective user and group IDs instead of the real
user and group IDs for checking permission. See discussion below.
-
-
- AT_SYMLINK_NOFOLLOW
- Do not follow a symbolic link encountered as the last
component in path.
For
access(), and
faccessat() when the
AT_EACCESS
flag is not passed, the real user ID and
the real group ID are used for checking permission in place of the effective
user ID and effective group ID. This affects only set-user-ID and set-group-ID
programs, which should not use these functions. (For other programs, the real
and effective IDs are the same.)
For processes running with super-user privileges, these functions may return
success for read and write checks regardless of whether read and write
permission bits are actually set. This reflects the fact that the super-user
may read and write all files regardless of permission settings. However, even
for the super-user, an execute check using
X_OK
will
succeed only if the target object has at least one of its execute permission
bits set. (This does not guarantee that the target object can necessarily be
successfully executed. See
execve(2).)
RETURN VALUES
The
access() and
faccessat() functions
succeed and return 0 if, at some point in the recent past, the target object
named by
path existed and its permission settings
allowed the requested access as described above. If the requested access would
not have been granted, the object did not exist, or the path lookup failed,
the value -1 is returned and the value of
errno is set
to reflect what went wrong.
ERRORS
These functions fail if:
-
-
- [
EACCES
]
- Search permission is denied for fd,
or for the current directory, or for a directory in the prefix of
path; or the permission bits on the target file
system object do not permit the requested access.
-
-
- [
EBADF
]
- The file descriptor fd is not open
and is not
AT_FDCWD
.
-
-
- [
EFAULT
]
- path points outside the process's
allocated address space.
-
-
- [
EINVAL
]
- The mode or
flags argument contained an invalid value.
-
-
- [
EIO
]
- An I/O error occurred while reading from or writing to the
file system.
-
-
- [
ELOOP
]
- Too many symbolic links were encountered in translating the
pathname.
-
-
- [
ENAMETOOLONG
]
- A component of a pathname exceeded
{
NAME_MAX
} characters, or an entire path name
exceeded {PATH_MAX
} characters.
-
-
- [
ENOENT
]
- The named file does not exist.
-
-
- [
ENOTDIR
]
- The file descriptor fd does not name
a directory, or a component of the path prefix is not a directory.
-
-
- [
EROFS
]
- Write access is requested for a file on a read-only file
system.
-
-
- [
ETXTBSY
]
- Write access is requested for a pure procedure (shared
text) file presently being executed.
SEE ALSO
chmod(2),
execve(2),
stat(2),
secure_path(3)
STANDARDS
The
access() function conforms to
IEEE Std
1003.1-1990 (“POSIX.1”).
faccessat()
function conforms to
IEEE Std 1003.1-2008
(“POSIX.1”).
Note that
faccessat() violates the historic convention that
system calls whose names begin with `f' operate on file handles rather than
paths. There is no equivalent to
access() for checking
access properties of an already-opened file.
SECURITY CONSIDERATIONS
Because the results of these calls reflect the state of the file system at the
time they ran, and the file system can potentially be modified between that
time and the time the caller attempts to act on the results, they should
never be used for security enforcement.
Privileged programs that need to restrict their actions to files or directories
properly accessible to unprivileged users
must do this by
assuming or restoring an unprivileged state (see
seteuid(2)) when performing the
pertinent actions. Checking in advance (with
access() or any
other method) and performing such actions while privileged introduces a race
condition that in most cases is easily exploitable by even a naive adversary.
Even for non-privileged programs, the opportunity for the world to change after
the call runs makes
access() and
faccessat() not very useful. In general only
F_OK
should be used, and that too, sparingly. The
other checks may occasionally be useful for user interface or diagnostic
purposes.