access

SYNOPSIS
       #include <unistd.h>

       int access(const char *path, int amode);


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,  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 individu-
       ally,   as   described   in   the   Base    Definitions    volume    of
       IEEE Std 1003.1-2001, Chapter 3, Definitions. If the process has appro-
       priate privileges, an implementation may indicate success for X_OK even
       if none of the execute file permission bits are set.

RETURN VALUE
       If  the  requested  access  is  permitted,  access() succeeds and shall
       return 0; otherwise, -1 shall be returned and errno  shall  be  set  to
       indicate the error.

ERRORS
       The access() function 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 the path argument exceeds {PATH_MAX} or a pathname
              component 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 is not a directory.

       EROFS  Write access is requested for a file on a read-only file system.


       The access() function may fail if:

              file that is being executed.


       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 *filename = "/tmp/myfile";


              result = access (filename, F_OK);

APPLICATION USAGE
       Additional  values  of amode other than the set defined in the descrip-
       tion may be valid; for example, if a system has  extended  access  con-
       trols.

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 cor-
           rectly  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  IEEE Std 1003.1-2001 now allows access() to
       behave in the desired way because  several  implementations  have  cor-
       rected  the problem. It was also argued that problem (2) is more easily
       solved by using open(), chdir(), or one of the exec functions as appro-
       priate 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 IEEE Std 1003.1-2001.

       The  sentence  concerning appropriate privileges and execute permission
       bits reflects the two possibilities implemented by historical implemen-
       tations when checking superuser access for X_OK.

       New implementations are discouraged from returning X_OK unless at least
       one execution permission bit is set.

       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 .



IEEE/The Open Group                  2003                            ACCESS(P)