1ACCESS(3P)                 POSIX Programmer's Manual                ACCESS(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       access - determine accessibility of a file
13

SYNOPSIS

15       #include <unistd.h>
16
17       int access(const char *path, int amode);
18
19

DESCRIPTION

21       The access() function shall  check  the  file  named  by  the  pathname
22       pointed  to by the path argument for accessibility according to the bit
23       pattern contained in amode, using the real user  ID  in  place  of  the
24       effective user ID and the real group ID in place of the effective group
25       ID.
26
27       The value of amode is either the bitwise-inclusive  OR  of  the  access
28       permissions  to  be  checked  (R_OK,  W_OK, X_OK) or the existence test
29       (F_OK).
30
31       If any access permissions are checked, each shall be checked  individu‐
32       ally,    as    described    in   the   Base   Definitions   volume   of
33       IEEE Std 1003.1-2001, Chapter 3, Definitions. If the process has appro‐
34       priate privileges, an implementation may indicate success for X_OK even
35       if none of the execute file permission bits are set.
36

RETURN VALUE

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

ERRORS

43       The access() function shall fail if:
44
45       EACCES Permission bits of the file mode do  not  permit  the  requested
46              access,  or  search  permission  is denied on a component of the
47              path prefix.
48
49       ELOOP  A loop exists in symbolic links encountered during resolution of
50              the path argument.
51
52       ENAMETOOLONG
53              The length of the path argument exceeds {PATH_MAX} or a pathname
54              component is longer than {NAME_MAX}.
55
56       ENOENT A component of path does not name an existing file or path is an
57              empty string.
58
59       ENOTDIR
60              A component of the path prefix is not a directory.
61
62       EROFS  Write access is requested for a file on a read-only file system.
63
64
65       The access() function may fail if:
66
67       EINVAL The value of the amode argument is invalid.
68
69       ELOOP  More  than  {SYMLOOP_MAX} symbolic links were encountered during
70              resolution of the path argument.
71
72       ENAMETOOLONG
73              As a result of encountering a symbolic link in resolution of the
74              path  argument,  the  length  of the substituted pathname string
75              exceeded {PATH_MAX}.
76
77       ETXTBSY
78              Write access is requested for a  pure  procedure  (shared  text)
79              file that is being executed.
80
81
82       The following sections are informative.
83

EXAMPLES

85   Testing for the Existence of a File
86       The  following  example tests whether a file named myfile exists in the
87       /tmp directory.
88
89
90              #include <unistd.h>
91              ...
92              int result;
93              const char *filename = "/tmp/myfile";
94
95
96              result = access (filename, F_OK);
97

APPLICATION USAGE

99       Additional values of amode other than the set defined in  the  descrip‐
100       tion  may  be  valid; for example, if a system has extended access con‐
101       trols.
102

RATIONALE

104       In early proposals, some inadequacies in the access() function  led  to
105       the creation of an eaccess() function because:
106
107        1. Historical implementations of access() do not test file access cor‐
108           rectly when the process' real user ID is superuser. In  particular,
109           they  always  return  zero when testing execute permissions without
110           regard to whether the file is executable.
111
112        2. The superuser has complete access to all files on a  system.  As  a
113           consequence,  programs started by the superuser and switched to the
114           effective user ID with lesser privileges  cannot  use  access()  to
115           test their file access permissions.
116
117       However,  the  historical  model  of eaccess() does not resolve problem
118       (1), so this volume of  IEEE Std 1003.1-2001  now  allows  access()  to
119       behave  in  the  desired  way because several implementations have cor‐
120       rected the problem. It was also argued that problem (2) is more  easily
121       solved by using open(), chdir(), or one of the exec functions as appro‐
122       priate and responding to the error, rather than creating a new function
123       that  would not be as reliable. Therefore, eaccess() is not included in
124       this volume of IEEE Std 1003.1-2001.
125
126       The sentence concerning appropriate privileges and  execute  permission
127       bits reflects the two possibilities implemented by historical implemen‐
128       tations when checking superuser access for X_OK.
129
130       New implementations are discouraged from returning X_OK unless at least
131       one execution permission bit is set.
132

FUTURE DIRECTIONS

134       None.
135

SEE ALSO

137       chmod(),  stat(),  the Base Definitions volume of IEEE Std 1003.1-2001,
138       <unistd.h>
139
141       Portions of this text are reprinted and reproduced in  electronic  form
142       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
143       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
144       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
145       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
146       event of any discrepancy between this version and the original IEEE and
147       The Open Group Standard, the original IEEE and The Open Group  Standard
148       is  the  referee document. The original Standard can be obtained online
149       at http://www.opengroup.org/unix/online.html .
150
151
152
153IEEE/The Open Group                  2003                           ACCESS(3P)
Impressum