# access

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


## NAME



           access, faccessat — determine accessibility of a file descriptor
    


## SYNOPSIS



           #include <unistd.h>
    
           int access(const char *_path_ , int _amode_);
    
           #include <fcntl.h>
    
           int faccessat(int _fd_ , const char *_path_ , int _amode_ , int _flag_);
    


## DESCRIPTION



           The _access_() function shall check the file named by the pathname
           pointed to by the _path_ argument for accessibility according to the
           bit pattern contained in _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.
    
           The value of _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).
    
           If any access permissions are checked, each shall be checked
           individually, as described in the Base Definitions volume of
           POSIX.1‐2017, _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.
    
           The _faccessat_() function, when called with a _flag_ value of zero,
           shall be equivalent to the _access_() function, except in the case
           where _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 _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.
    
           If _faccessat_() is passed the special value AT_FDCWD in the _fd_
           parameter, the current working directory shall be used and, if
           flag is zero, the behavior shall be identical to a call to
           _access_().
    
           Values for _flag_ are constructed by a bitwise-inclusive OR of flags
           from the following list, defined in _< fcntl.h>_:
    
           AT_EACCESS  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 _access_().
    


## RETURN VALUE



           Upon successful completion, these functions shall return 0.
           Otherwise, these functions shall return -1 and set _errno_ to
           indicate the error.
    


## ERRORS



           These functions shall fail if:
    
           **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.
    
           **ELOOP** A loop exists in symbolic links encountered during
                  resolution of the _path_ argument.
    
           **ENAMETOOLONG**
                  The length of a component of a pathname is longer than
                  {NAME_MAX}.
    
           **ENOENT** A component of _path_ does not name an existing file or _path_
                  is an empty string.
    
           **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 _path_ argument contains at least one non-<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.
    
           **EROFS** Write access is requested for a file on a read-only file
                  system.
    
           The _faccessat_() function shall fail if:
    
           **EACCES** The access mode of the open file description associated
                  with _fd_ is not O_SEARCH and the permissions of the
                  directory underlying _fd_ do not permit directory searches.
    
           **EBADF** The _path_ argument does not specify an absolute path and the
                  _fd_ argument is neither AT_FDCWD nor a valid file descriptor
                  open for reading or searching.
    
           **ENOTDIR**
                  The _path_ argument is not an absolute path and _fd_ is a file
                  descriptor associated with a non-directory file.
    
           These functions may fail if:
    
           **EINVAL** The value of the _amode_ argument is invalid.
    
           **ELOOP** More than {SYMLOOP_MAX} symbolic links were encountered
                  during resolution of the _path_ argument.
    
           **ENAMETOOLONG**
                  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}.
    
           **ETXTBSY**
                  Write access is requested for a pure procedure (shared
                  text) file that is being executed.
    
           The _faccessat_() function may fail if:
    
           **EINVAL** The value of the _flag_ argument is not valid.
    
           _The following sections are informative._
    


## EXAMPLES



       **Testing for the Existence of a File**
           The following example tests whether a file named **myfile** exists in
           the **/tmp** directory.
    
               #include <unistd.h>
               ...
               int result;
               const char *pathname = "/tmp/myfile";
    
               result = access (pathname, F_OK);
    


## 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 **[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 _access_() or _faccessat_() without AT_EACCES would have been
           used.)
    
           Historically, one of the uses of _access_() 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
           _access_() 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 _access_(), the
           change of IDs has no effect on the privileges and therefore they
           are taken into account in the accessibility checks. Thus, _access_()
           (and _faccessat_() 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.
    
           If a relative pathname is used, no account is taken of whether the
           current directory (or the directory associated with the file
           descriptor _fd_) is accessible via any absolute pathname.
           Applications using _access_(), or _faccessat_() 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 _fd_) in the file
           hierarchy.
    
           If _access_() or _faccessat_() 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‐2017, _Section 4.3_ , _Directory Protection_).
    
           Additional values of _amode_ other than the set defined in the
           description may be valid; for example, if a system has extended
           access controls.
    
           The use of the AT_EACCESS value for _flag_ enables functionality not
           available in _access_().
    


## RATIONALE



           In early proposals, some inadequacies in the _access_() function led
           to the creation of an _eaccess_() function because:
    
            1. Historical implementations of _access_() 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.
    
            2. 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
               _access_() to test their file access permissions.
    
           However, the historical model of _eaccess_() does not resolve
           problem (1), so this volume of POSIX.1‐2017 now allows _access_() 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 _open_(), _chdir_(), or one of the _exec_
           functions as appropriate and responding to the error, rather than
           creating a new function that would not be as reliable. Therefore,
           _eaccess_() is not included in this volume of POSIX.1‐2017.
    
           The sentence concerning appropriate privileges and execute
           permission bits reflects the two possibilities implemented by
           historical implementations when checking superuser access for
           X_OK.
    
           New implementations are discouraged from returning X_OK unless at
           least one execution permission bit is set.
    
           The purpose of the _faccessat_() 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 _access_(), resulting in unspecified behavior. By opening a file
           descriptor for the target directory and using the _faccessat_()
           function it can be guaranteed that the file tested for
           accessibility is located relative to the desired directory.
    


## FUTURE DIRECTIONS



           These functions may be formally deprecated (for example, by
           shading them OB) in a future version of this standard.
    


* * *