1ACCESS(2)                  Linux Programmer's Manual                 ACCESS(2)
2
3
4

NAME

6       access, faccessat - check user's permissions for a file
7

SYNOPSIS

9       #include <unistd.h>
10
11       int access(const char *pathname, int mode);
12
13       #include <fcntl.h>           /* Definition of AT_* constants */
14       #include <unistd.h>
15
16       int faccessat(int dirfd, const char *pathname, int mode, int flags);
17
18   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
19
20       faccessat():
21           Since glibc 2.10:
22               _POSIX_C_SOURCE >= 200809L
23           Before glibc 2.10:
24               _ATFILE_SOURCE
25

DESCRIPTION

27       access()  checks  whether the calling process can access the file path‐
28       name.  If pathname is a symbolic link, it is dereferenced.
29
30       The mode specifies the accessibility check(s) to be performed,  and  is
31       either the value F_OK, or a mask consisting of the bitwise OR of one or
32       more of R_OK, W_OK, and X_OK.  F_OK tests  for  the  existence  of  the
33       file.   R_OK,  W_OK,  and  X_OK test whether the file exists and grants
34       read, write, and execute permissions, respectively.
35
36       The check is done using the calling process's real UID and GID,  rather
37       than the effective IDs as is done when actually attempting an operation
38       (e.g., open(2)) on the file.  Similarly, for the root user,  the  check
39       uses the set of permitted capabilities rather than the set of effective
40       capabilities; and for non-root users, the check uses an  empty  set  of
41       capabilities.
42
43       This  allows  set-user-ID  programs  and capability-endowed programs to
44       easily determine  the  invoking  user's  authority.   In  other  words,
45       access()  does  not  answer  the  "can I read/write/execute this file?"
46       question.  It answers a slightly different question: "(assuming  I'm  a
47       setuid  binary)  can  the  user  who invoked me read/write/execute this
48       file?", which gives set-user-ID programs  the  possibility  to  prevent
49       malicious  users  from causing them to read files which users shouldn't
50       be able to read.
51
52       If the calling process is privileged (i.e., its real UID is zero), then
53       an X_OK check is successful for a regular file if execute permission is
54       enabled for any of the file owner, group, or other.
55
56   faccessat()
57       The faccessat() system  call  operates  in  exactly  the  same  way  as
58       access(), except for the differences described here.
59
60       If  the  pathname given in pathname is relative, then it is interpreted
61       relative to the directory referred to  by  the  file  descriptor  dirfd
62       (rather  than  relative to the current working directory of the calling
63       process, as is done by access() for a relative pathname).
64
65       If pathname is relative and dirfd is the special value  AT_FDCWD,  then
66       pathname  is  interpreted  relative to the current working directory of
67       the calling process (like access()).
68
69       If pathname is absolute, then dirfd is ignored.
70
71       flags is constructed by ORing together zero or more  of  the  following
72       values:
73
74       AT_EACCESS
75              Perform  access  checks  using the effective user and group IDs.
76              By default, faccessat() uses the real IDs (like access()).
77
78       AT_SYMLINK_NOFOLLOW
79              If pathname is a symbolic link, do not dereference  it:  instead
80              return information about the link itself.
81
82       See openat(2) for an explanation of the need for faccessat().
83

RETURN VALUE

85       On  success (all requested permissions granted, or mode is F_OK and the
86       file exists), zero is returned.  On error (at least  one  bit  in  mode
87       asked  for  a  permission  that is denied, or mode is F_OK and the file
88       does not exist, or some other error  occurred),  -1  is  returned,  and
89       errno is set appropriately.
90

ERRORS

92       access() and faccessat() shall fail if:
93
94       EACCES The requested access would be denied to the file, or search per‐
95              mission is denied for one of the directories in the path  prefix
96              of pathname.  (See also path_resolution(7).)
97
98       ELOOP  Too many symbolic links were encountered in resolving pathname.
99
100       ENAMETOOLONG
101              pathname is too long.
102
103       ENOENT A component of pathname does not exist or is a dangling symbolic
104              link.
105
106       ENOTDIR
107              A component used as a directory in pathname is not, in  fact,  a
108              directory.
109
110       EROFS  Write  permission  was  requested  for  a  file  on  a read-only
111              filesystem.
112
113       access() and faccessat() may fail if:
114
115       EFAULT pathname points outside your accessible address space.
116
117       EINVAL mode was incorrectly specified.
118
119       EIO    An I/O error occurred.
120
121       ENOMEM Insufficient kernel memory was available.
122
123       ETXTBSY
124              Write access was requested to an executable which is being  exe‐
125              cuted.
126
127       The following additional errors can occur for faccessat():
128
129       EBADF  dirfd is not a valid file descriptor.
130
131       EINVAL Invalid flag specified in flags.
132
133       ENOTDIR
134              pathname is relative and dirfd is a file descriptor referring to
135              a file other than a directory.
136

VERSIONS

138       faccessat() was added to Linux in kernel 2.6.16;  library  support  was
139       added to glibc in version 2.4.
140

CONFORMING TO

142       access(): SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
143
144       faccessat(): POSIX.1-2008.
145

NOTES

147       Warning:  Using  these  calls  to check if a user is authorized to, for
148       example, open a file before actually doing so using open(2)  creates  a
149       security  hole,  because the user might exploit the short time interval
150       between checking and opening the file to manipulate it.  For this  rea‐
151       son,  the  use  of this system call should be avoided.  (In the example
152       just described, a safer alternative would be to temporarily switch  the
153       process's effective user ID to the real ID and then call open(2).)
154
155       access()  always dereferences symbolic links.  If you need to check the
156       permissions on a symbolic link, use faccessat() with the  flag  AT_SYM‐
157       LINK_NOFOLLOW.
158
159       These  calls  return  an  error  if  any of the access types in mode is
160       denied, even if some of the other access types in mode are permitted.
161
162       If the calling process has appropriate privileges (i.e., is superuser),
163       POSIX.1-2001  permits an implementation to indicate success for an X_OK
164       check even if none of the execute file permission bits are set.   Linux
165       does not do this.
166
167       A file is accessible only if the permissions on each of the directories
168       in the path prefix of pathname grant search (i.e., execute) access.  If
169       any directory is inaccessible, then the access() call fails, regardless
170       of the permissions on the file itself.
171
172       Only access bits are checked, not the file type  or  contents.   There‐
173       fore,  if  a  directory is found to be writable, it probably means that
174       files can be created in the directory, and not that the  directory  can
175       be  written  as a file.  Similarly, a DOS file may be found to be "exe‐
176       cutable," but the execve(2) call will still fail.
177
178       These calls may not work correctly on NFSv2 filesystems with  UID  map‐
179       ping enabled, because UID mapping is done on the server and hidden from
180       the client, which checks permissions.  (NFS versions 3 and higher  per‐
181       form  the  check  on  the  server.)  Similar problems can occur to FUSE
182       mounts.
183
184   C library/kernel differences
185       The raw faccessat() system call takes only the first  three  arguments.
186       The  AT_EACCESS  and AT_SYMLINK_NOFOLLOW flags are actually implemented
187       within the glibc wrapper function for faccessat().  If either of  these
188       flags  is  specified,  then  the wrapper function employs fstatat(2) to
189       determine access permissions.
190
191   Glibc notes
192       On older kernels where faccessat() is unavailable (and when the AT_EAC‐
193       CESS  and AT_SYMLINK_NOFOLLOW flags are not specified), the glibc wrap‐
194       per function falls back to the use of access().   When  pathname  is  a
195       relative  pathname,  glibc  constructs a pathname based on the symbolic
196       link in /proc/self/fd that corresponds to the dirfd argument.
197

BUGS

199       In kernel 2.4 (and earlier) there is some strangeness in  the  handling
200       of  X_OK  tests for superuser.  If all categories of execute permission
201       are disabled for a nondirectory file, then the only access() test  that
202       returns  -1  is when mode is specified as just X_OK; if R_OK or W_OK is
203       also specified in mode, then access() returns 0 for such files.   Early
204       2.6 kernels (up to and including 2.6.3) also behaved in the same way as
205       kernel 2.4.
206
207       In kernels before  2.6.20,  these  calls  ignored  the  effect  of  the
208       MS_NOEXEC  flag  if  it was used to mount(2) the underlying filesystem.
209       Since kernel 2.6.20, the MS_NOEXEC flag is honored.
210

SEE ALSO

212       chmod(2), chown(2), open(2),  setgid(2),  setuid(2),  stat(2),  euidac‐
213       cess(3), credentials(7), path_resolution(7), symlink(7)
214

COLOPHON

216       This  page  is  part of release 4.16 of the Linux man-pages project.  A
217       description of the project, information about reporting bugs,  and  the
218       latest     version     of     this    page,    can    be    found    at
219       https://www.kernel.org/doc/man-pages/.
220
221
222
223Linux                             2016-03-15                         ACCESS(2)
Impressum