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

NAME

6       access, faccessat, faccessat2 - 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                       /* But see C library/kernel differences, below */
18
19       #include <fcntl.h>            /* Definition of AT_* constants */
20       #include <sys/syscall.h>      /* Definition of SYS_* constants */
21       #include <unistd.h>
22
23       int syscall(SYS_faccessat2,
24                   int dirfd, const char *pathname, int mode, int flags);
25
26   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
27
28       faccessat():
29           Since glibc 2.10:
30               _POSIX_C_SOURCE >= 200809L
31           Before glibc 2.10:
32               _ATFILE_SOURCE
33

DESCRIPTION

35       access()  checks  whether the calling process can access the file path‐
36       name.  If pathname is a symbolic link, it is dereferenced.
37
38       The mode specifies the accessibility check(s) to be performed,  and  is
39       either the value F_OK, or a mask consisting of the bitwise OR of one or
40       more of R_OK, W_OK, and X_OK.  F_OK tests  for  the  existence  of  the
41       file.   R_OK,  W_OK,  and  X_OK test whether the file exists and grants
42       read, write, and execute permissions, respectively.
43
44       The check is done using the calling process's real UID and GID,  rather
45       than the effective IDs as is done when actually attempting an operation
46       (e.g., open(2)) on the file.  Similarly, for the root user,  the  check
47       uses the set of permitted capabilities rather than the set of effective
48       capabilities; and for non-root users, the check uses an  empty  set  of
49       capabilities.
50
51       This  allows  set-user-ID  programs  and capability-endowed programs to
52       easily determine the invoking user's authority.  In  other  words,  ac‐
53       cess()  does not answer the "can I read/write/execute this file?" ques‐
54       tion.  It answers a slightly different question: "(assuming I'm  a  se‐
55       tuid  binary)  can  the  user  who  invoked  me read/write/execute this
56       file?", which gives set-user-ID programs the possibility to prevent ma‐
57       licious  users from causing them to read files which users shouldn't be
58       able to read.
59
60       If the calling process is privileged (i.e., its real UID is zero), then
61       an X_OK check is successful for a regular file if execute permission is
62       enabled for any of the file owner, group, or other.
63
64   faccessat()
65       faccessat() operates in exactly the same way as  access(),  except  for
66       the differences described here.
67
68       If  the  pathname given in pathname is relative, then it is interpreted
69       relative to the directory referred to  by  the  file  descriptor  dirfd
70       (rather  than  relative to the current working directory of the calling
71       process, as is done by access() for a relative pathname).
72
73       If pathname is relative and dirfd is the special value  AT_FDCWD,  then
74       pathname  is  interpreted  relative to the current working directory of
75       the calling process (like access()).
76
77       If pathname is absolute, then dirfd is ignored.
78
79       flags is constructed by ORing together zero or more  of  the  following
80       values:
81
82       AT_EACCESS
83              Perform  access  checks  using the effective user and group IDs.
84              By default, faccessat() uses the real IDs (like access()).
85
86       AT_SYMLINK_NOFOLLOW
87              If pathname is a symbolic link, do not dereference  it:  instead
88              return information about the link itself.
89
90       See openat(2) for an explanation of the need for faccessat().
91
92   faccessat2()
93       The  description  of faccessat() given above corresponds to POSIX.1 and
94       to the implementation provided by glibc.  However, the glibc  implemen‐
95       tation was an imperfect emulation (see BUGS) that papered over the fact
96       that the raw Linux faccessat() system call does not have a flags  argu‐
97       ment.   To  allow for a proper implementation, Linux 5.8 added the fac‐
98       cessat2() system call, which supports the flags argument and  allows  a
99       correct implementation of the faccessat() wrapper function.
100

RETURN VALUE

102       On  success (all requested permissions granted, or mode is F_OK and the
103       file exists), zero is returned.  On error (at least  one  bit  in  mode
104       asked  for  a  permission  that is denied, or mode is F_OK and the file
105       does not exist, or some other error occurred), -1 is returned, and  er‐
106       rno is set to indicate the error.
107

ERRORS

109       EACCES The requested access would be denied to the file, or search per‐
110              mission is denied for one of the directories in the path  prefix
111              of pathname.  (See also path_resolution(7).)
112
113       EBADF  (faccessat()) pathname is relative but dirfd is neither AT_FDCWD
114              (faccessat()) nor a valid file descriptor.
115
116       EFAULT pathname points outside your accessible address space.
117
118       EINVAL mode was incorrectly specified.
119
120       EINVAL (faccessat()) Invalid flag specified in flags.
121
122       EIO    An I/O error occurred.
123
124       ELOOP  Too many symbolic links were encountered in resolving pathname.
125
126       ENAMETOOLONG
127              pathname is too long.
128
129       ENOENT A component of pathname does not exist or is a dangling symbolic
130              link.
131
132       ENOMEM Insufficient kernel memory was available.
133
134       ENOTDIR
135              A  component  used as a directory in pathname is not, in fact, a
136              directory.
137
138       ENOTDIR
139              (faccessat()) pathname is relative and dirfd is a file  descrip‐
140              tor referring to a file other than a directory.
141
142       EROFS  Write  permission  was  requested  for  a  file  on  a read-only
143              filesystem.
144
145       ETXTBSY
146              Write access was requested to an executable which is being  exe‐
147              cuted.
148

VERSIONS

150       faccessat()  was  added  to Linux in kernel 2.6.16; library support was
151       added to glibc in version 2.4.
152
153       faccessat2() was added to Linux in version 5.8.
154

CONFORMING TO

156       access(): SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
157
158       faccessat(): POSIX.1-2008.
159
160       faccessat2(): Linux-specific.
161

NOTES

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

BUGS

215       Because  the  Linux kernel's faccessat() system call does not support a
216       flags argument, the glibc  faccessat()  wrapper  function  provided  in
217       glibc 2.32 and earlier emulates the required functionality using a com‐
218       bination of the faccessat() system call and fstatat(2).  However,  this
219       emulation  does  not take ACLs into account.  Starting with glibc 2.33,
220       the wrapper function avoids this bug by making use of the  faccessat2()
221       system call where it is provided by the underlying kernel.
222
223       In  kernel  2.4 (and earlier) there is some strangeness in the handling
224       of X_OK tests for superuser.  If all categories of  execute  permission
225       are  disabled for a nondirectory file, then the only access() test that
226       returns -1 is when mode is specified as just X_OK; if R_OK or  W_OK  is
227       also  specified in mode, then access() returns 0 for such files.  Early
228       2.6 kernels (up to and including 2.6.3) also behaved in the same way as
229       kernel 2.4.
230
231       In  kernels  before  2.6.20,  these  calls  ignored  the  effect of the
232       MS_NOEXEC flag if it was used to mount(2)  the  underlying  filesystem.
233       Since kernel 2.6.20, the MS_NOEXEC flag is honored.
234

SEE ALSO

236       chmod(2),  chown(2),  open(2),  setgid(2),  setuid(2), stat(2), euidac‐
237       cess(3), credentials(7), path_resolution(7), symlink(7)
238

COLOPHON

240       This page is part of release 5.13 of the Linux  man-pages  project.   A
241       description  of  the project, information about reporting bugs, and the
242       latest    version    of    this    page,    can     be     found     at
243       https://www.kernel.org/doc/man-pages/.
244
245
246
247Linux                             2021-08-27                         ACCESS(2)
Impressum