ACCESS(2)

ACCESS(2) | System Calls Manual | ACCESS(2)

# 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.

January 12, 2013 | NetBSD 10.1