1access(2)                     System Calls Manual                    access(2)
2
3
4

NAME

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

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

VERSIONS

156       If the calling process has appropriate privileges (i.e., is superuser),
157       POSIX.1-2001  permits an implementation to indicate success for an X_OK
158       check even if none of the execute file permission bits are set.   Linux
159       does not do this.
160
161   C library/kernel differences
162       The  raw  faccessat() system call takes only the first three arguments.
163       The AT_EACCESS and AT_SYMLINK_NOFOLLOW flags are  actually  implemented
164       within  the glibc wrapper function for faccessat().  If either of these
165       flags is specified, then the wrapper function employs fstatat(2) to de‐
166       termine access permissions, but see BUGS.
167
168   glibc notes
169       On older kernels where faccessat() is unavailable (and when the AT_EAC‐
170       CESS and AT_SYMLINK_NOFOLLOW flags are not specified), the glibc  wrap‐
171       per  function  falls  back  to the use of access().  When pathname is a
172       relative pathname, glibc constructs a pathname based  on  the  symbolic
173       link in /proc/self/fd that corresponds to the dirfd argument.
174

STANDARDS

176       access()
177       faccessat()
178              POSIX.1-2008.
179
180       faccessat2()
181              Linux.
182

HISTORY

184       access()
185              SVr4, 4.3BSD, POSIX.1-2001.
186
187       faccessat()
188              Linux 2.6.16, glibc 2.4.
189
190       faccessat2()
191              Linux 5.8.
192

NOTES

194       Warning: Using these calls to check if a user is authorized to, for ex‐
195       ample, open a file before actually doing so using open(2) creates a se‐
196       curity hole, because the user might exploit the short time interval be‐
197       tween checking and opening the file to manipulate it.  For this reason,
198       the  use  of  this system call should be avoided.  (In the example just
199       described, a safer alternative  would  be  to  temporarily  switch  the
200       process's effective user ID to the real ID and then call open(2).)
201
202       access()  always dereferences symbolic links.  If you need to check the
203       permissions on a symbolic link, use faccessat() with the  flag  AT_SYM‐
204       LINK_NOFOLLOW.
205
206       These  calls  return an error if any of the access types in mode is de‐
207       nied, even if some of the other access types in mode are permitted.
208
209       A file is accessible only if the permissions on each of the directories
210       in the path prefix of pathname grant search (i.e., execute) access.  If
211       any directory is inaccessible, then the access() call fails, regardless
212       of the permissions on the file itself.
213
214       Only  access  bits  are checked, not the file type or contents.  There‐
215       fore, if a directory is found to be writable, it  probably  means  that
216       files  can  be created in the directory, and not that the directory can
217       be written as a file.  Similarly, a DOS file may be  reported  as  exe‐
218       cutable, but the execve(2) call will still fail.
219
220       These  calls  may not work correctly on NFSv2 filesystems with UID map‐
221       ping enabled, because UID mapping is done on the server and hidden from
222       the  client, which checks permissions.  (NFS versions 3 and higher per‐
223       form the check on the server.)  Similar  problems  can  occur  to  FUSE
224       mounts.
225

BUGS

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

SEE ALSO

248       chmod(2),  chown(2),  open(2),  setgid(2),  setuid(2), stat(2), euidac‐
249       cess(3), credentials(7), path_resolution(7), symlink(7)
250
251
252
253Linux man-pages 6.04              2023-03-30                         access(2)
Impressum