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, faccessat — determine accessibility of a file descriptor
13

SYNOPSIS

15       #include <unistd.h>
16
17       int access(const char *path, int amode);
18
19       #include <fcntl.h>
20
21       int faccessat(int fd, const char *path, int amode, int flag);
22

DESCRIPTION

24       The access() function shall  check  the  file  named  by  the  pathname
25       pointed  to by the path argument for accessibility according to the bit
26       pattern contained in amode.  The checks  for  accessibility  (including
27       directory permissions checked during pathname resolution) shall be per‐
28       formed using the real user ID in place of the effective user ID and the
29       real group ID in place of the effective group ID.
30
31       The  value  of  amode  is either the bitwise-inclusive OR of the access
32       permissions to be checked (R_OK, W_OK,  X_OK)  or  the  existence  test
33       (F_OK).
34
35       If  any access permissions are checked, each shall be checked individu‐
36       ally, as described in the Base Definitions volume of POSIX.1‐2017, Sec‐
37       tion  4.5,  File Access Permissions, except that where that description
38       refers to execute permission for a process with appropriate privileges,
39       an implementation may indicate success for X_OK even if execute permis‐
40       sion is not granted to any user.
41
42       The faccessat() function, when called with a flag value of zero,  shall
43       be  equivalent  to the access() function, except in the case where path
44       specifies a relative path. In this case the file whose accessibility is
45       to  be determined shall be located relative to the directory associated
46       with the file descriptor fd instead of the current  working  directory.
47       If  the  access  mode  of the open file description associated with the
48       file descriptor is not  O_SEARCH,  the  function  shall  check  whether
49       directory  searches  are permitted using the current permissions of the
50       directory underlying the  file  descriptor.   If  the  access  mode  is
51       O_SEARCH, the function shall not perform the check.
52
53       If  faccessat()  is passed the special value AT_FDCWD in the fd parame‐
54       ter, the current working directory shall be used and, if flag is  zero,
55       the behavior shall be identical to a call to access().
56
57       Values for flag are constructed by a bitwise-inclusive OR of flags from
58       the following list, defined in <fcntl.h>:
59
60       AT_EACCESS  The checks for accessibility (including  directory  permis‐
61                   sions  checked  during  pathname  resolution) shall be per‐
62                   formed using the effective user ID and group ID instead  of
63                   the  real  user  ID  and  group ID as required in a call to
64                   access().
65

RETURN VALUE

67       Upon successful completion, these functions shall return 0.  Otherwise,
68       these functions shall return -1 and set errno to indicate the error.
69

ERRORS

71       These functions shall fail if:
72
73       EACCES Permission  bits  of  the  file mode do not permit the requested
74              access, or search permission is denied on  a  component  of  the
75              path prefix.
76
77       ELOOP  A loop exists in symbolic links encountered during resolution of
78              the path argument.
79
80       ENAMETOOLONG
81              The  length  of  a  component  of  a  pathname  is  longer  than
82              {NAME_MAX}.
83
84       ENOENT A component of path does not name an existing file or path is an
85              empty string.
86
87       ENOTDIR
88              A component of the path prefix names an existing  file  that  is
89              neither  a  directory nor a symbolic link to a directory, or the
90              path argument contains at least one  non-<slash>  character  and
91              ends  with  one or more trailing <slash> characters and the last
92              pathname component names an existing  file  that  is  neither  a
93              directory nor a symbolic link to a directory.
94
95       EROFS  Write access is requested for a file on a read-only file system.
96
97       The faccessat() function shall fail if:
98
99       EACCES The  access mode of the open file description associated with fd
100              is not O_SEARCH and the permissions of the directory  underlying
101              fd do not permit directory searches.
102
103       EBADF  The  path  argument does not specify an absolute path and the fd
104              argument is neither AT_FDCWD nor a valid  file  descriptor  open
105              for reading or searching.
106
107       ENOTDIR
108              The  path  argument  is  not  an  absolute path and fd is a file
109              descriptor associated with a non-directory file.
110
111       These functions may fail if:
112
113       EINVAL The value of the amode argument is invalid.
114
115       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
116              resolution of the path argument.
117
118       ENAMETOOLONG
119              The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
120              tion of a symbolic link produced an intermediate result  with  a
121              length that exceeds {PATH_MAX}.
122
123       ETXTBSY
124              Write  access  is  requested  for a pure procedure (shared text)
125              file that is being executed.
126
127       The faccessat() function may fail if:
128
129       EINVAL The value of the flag argument is not valid.
130
131       The following sections are informative.
132

EXAMPLES

134   Testing for the Existence of a File
135       The following example tests whether a file named myfile exists  in  the
136       /tmp directory.
137
138
139           #include <unistd.h>
140           ...
141           int result;
142           const char *pathname = "/tmp/myfile";
143
144           result = access (pathname, F_OK);
145

APPLICATION USAGE

147       Use  of  these  functions is discouraged since by the time the returned
148       information is acted upon, it is out-of-date. (That is, acting upon the
149       information  always leads to a time-of-check-to-time-of-use race condi‐
150       tion.) An application should instead attempt the action itself and han‐
151       dle  the [EACCES] error that occurs if the file is not accessible (with
152       a change of effective user and group  IDs  beforehand,  and  perhaps  a
153       change back afterwards, in the case where access() or faccessat() with‐
154       out AT_EACCES would have been used.)
155
156       Historically, one of the uses of access() was in set-user-ID root  pro‐
157       grams  to  check  whether  the user running the program had access to a
158       file. This relied on ``super-user'' privileges which were granted based
159       on  the  effective  user  ID being zero, so that when access() used the
160       real user ID to check accessibility those  privileges  were  not  taken
161       into  account.  On newer systems where privileges can be assigned which
162       have no association with user or group IDs,  if  a  program  with  such
163       privileges calls access(), the change of IDs has no effect on the priv‐
164       ileges and therefore they are taken into account in  the  accessibility
165       checks.  Thus, access() (and faccessat() with flag zero) cannot be used
166       for this historical purpose in such programs.  Likewise,  if  a  system
167       provides  any  additional  or  alternate file access control mechanisms
168       that are not user ID-based, they will still be taken into account.
169
170       If a relative pathname is used, no account is taken of whether the cur‐
171       rent  directory  (or  the directory associated with the file descriptor
172       fd)  is  accessible  via  any  absolute  pathname.  Applications  using
173       access(),  or faccessat() without AT_EACCES, may consequently act as if
174       the file would be accessible to a user with the real user ID and  group
175       ID  of  the  process  when such a user would not in practice be able to
176       access the file because access would be denied at some point above  the
177       current directory (or the directory associated with the file descriptor
178       fd) in the file hierarchy.
179
180       If access() or faccessat() is used with W_OK to check for write  access
181       to a directory which has the S_ISVTX bit set, a return value indicating
182       the directory is writable can be misleading since  some  operations  on
183       files in the directory would not be permitted based on the ownership of
184       those files (see the Base Definitions volume of  POSIX.1‐2017,  Section
185       4.3, Directory Protection).
186
187       Additional  values  of amode other than the set defined in the descrip‐
188       tion may be valid; for example, if a system has  extended  access  con‐
189       trols.
190
191       The  use  of  the  AT_EACCESS  value for flag enables functionality not
192       available in access().
193

RATIONALE

195       In early proposals, some inadequacies in the access() function  led  to
196       the creation of an eaccess() function because:
197
198        1. Historical implementations of access() do not test file access cor‐
199           rectly when the process' real user ID is superuser. In  particular,
200           they  always  return  zero when testing execute permissions without
201           regard to whether the file is executable.
202
203        2. The superuser has complete access to all files on a  system.  As  a
204           consequence,  programs started by the superuser and switched to the
205           effective user ID with lesser privileges  cannot  use  access()  to
206           test their file access permissions.
207
208       However,  the  historical  model  of eaccess() does not resolve problem
209       (1), so this volume of POSIX.1‐2017 now allows access()  to  behave  in
210       the  desired  way  because  several  implementations have corrected the
211       problem. It was also argued that problem (2) is more easily  solved  by
212       using  open(), chdir(), or one of the exec functions as appropriate and
213       responding to the error, rather than creating a new function that would
214       not be as reliable. Therefore, eaccess() is not included in this volume
215       of POSIX.1‐2017.
216
217       The sentence concerning appropriate privileges and  execute  permission
218       bits reflects the two possibilities implemented by historical implemen‐
219       tations when checking superuser access for X_OK.
220
221       New implementations are discouraged from returning X_OK unless at least
222       one execution permission bit is set.
223
224       The  purpose  of  the faccessat() function is to enable the checking of
225       the accessibility of files in directories other than the current  work‐
226       ing directory without exposure to race conditions. Any part of the path
227       of a file could be changed in parallel to a call to access(), resulting
228       in  unspecified  behavior.  By opening a file descriptor for the target
229       directory and using the faccessat() function it can be guaranteed  that
230       the  file  tested  for accessibility is located relative to the desired
231       directory.
232

FUTURE DIRECTIONS

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

SEE ALSO

238       chmod(), fstatat()
239
240       The  Base  Definitions volume of POSIX.1‐2017, Section 4.5, File Access
241       Permissions, <fcntl.h>, <unistd.h>
242
244       Portions of this text are reprinted and reproduced in  electronic  form
245       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
246       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
247       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
248       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
249       event of any discrepancy between this version and the original IEEE and
250       The Open Group Standard, the original IEEE and The Open Group  Standard
251       is  the  referee document. The original Standard can be obtained online
252       at http://www.opengroup.org/unix/online.html .
253
254       Any typographical or formatting errors that appear  in  this  page  are
255       most likely to have been introduced during the conversion of the source
256       files to man page format. To report such errors,  see  https://www.ker
257       nel.org/doc/man-pages/reporting_bugs.html .
258
259
260
261IEEE/The Open Group                  2017                           ACCESS(3P)
Impressum