access(2) - NetBSD Manual Pages

ACCESS(2)                 NetBSD 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 follow-
     ing 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 func-
     tions.  (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 set-
     tings.  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 translat-
                        ing the pathname.

     [ENAMETOOLONG]     A component of a pathname exceeded {NAME_MAX} charac-
                        ters, or an entire path name exceeded {PATH_MAX} char-
                        acters.

     [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 ISO/IEC 9945-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 per-
     forming 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 pur-
     poses.

NetBSD 9.3                     January 12, 2013                     NetBSD 9.3