| blob | 2b3e70e34aa1f3b509888e075c5b4a473150da7a |
1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
2 .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
3 .\" and Copyright (C) 2004, 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" Modified 1993-07-21 Rik Faith (faith@cs.unc.edu)
8 .\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com):
9 .\" Removed note about old kernel (pre-1.1.44) using wrong id on path.
10 .\" Modified 1996-03-18 by Martin Schulze (joey@infodrom.north.de):
11 .\" Stated more clearly how it behaves with symbolic links.
12 .\" Added correction due to Nick Duffek (nsd@bbc.com), aeb, 960426
13 .\" Modified 1996-09-07 by Michael Haardt:
14 .\" Restrictions for NFS
15 .\" Modified 1997-09-09 by Joseph S. Myers <jsm28@cam.ac.uk>
16 .\" Modified 1998-01-13 by Michael Haardt:
17 .\" Using access is often insecure
18 .\" Modified 2001-10-16 by aeb
19 .\" Modified 2002-04-23 by Roger Luethi <rl@hellgate.ch>
20 .\" Modified 2004-06-23 by Michael Kerrisk
21 .\" 2007-06-10, mtk, various parts rewritten, and added BUGS section.
22 .\"
23 .TH access 2 (date) "Linux man-pages (unreleased)"
24 .SH NAME
25 access, faccessat, faccessat2 \- check user's permissions for a file
26 .SH LIBRARY
27 Standard C library
28 .RI ( libc ", " \-lc )
29 .SH SYNOPSIS
30 .nf
31 .B #include <unistd.h>
32 .P
33 .BI "int access(const char *" pathname ", int " mode );
34 .P
35 .BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
36 .B #include <unistd.h>
37 .P
38 .BI "int faccessat(int " dirfd ", const char *" pathname ", int " \
39 mode ", int " flags );
40 /* But see C library/kernel differences, below */
41 .P
42 .BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
43 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
44 .B #include <unistd.h>
45 .P
46 .B int syscall(SYS_faccessat2,
47 .BI " int " dirfd ", const char *" pathname ", int " mode \
48 ", int " flags );
49 .fi
50 .P
51 .RS -4
52 Feature Test Macro Requirements for glibc (see
53 .BR feature_test_macros (7)):
54 .RE
55 .P
56 .BR faccessat ():
57 .nf
58 Since glibc 2.10:
59 _POSIX_C_SOURCE >= 200809L
60 Before glibc 2.10:
61 _ATFILE_SOURCE
62 .fi
63 .SH DESCRIPTION
64 .BR access ()
65 checks whether the calling process can access the file
66 .IR pathname .
67 If
68 .I pathname
69 is a symbolic link, it is dereferenced.
70 .P
71 The
72 .I mode
73 specifies the accessibility check(s) to be performed,
74 and is either the value
75 .BR F_OK ,
76 .\" F_OK is defined as 0 on every system that I know of.
77 or a mask consisting of the bitwise OR of one or more of
78 .BR R_OK ", " W_OK ", and " X_OK .
79 .B F_OK
80 tests for the existence of the file.
81 .BR R_OK ", " W_OK ", and " X_OK
82 test whether the file exists and grants read, write, and
83 execute permissions, respectively.
84 .P
85 The check is done using the calling process's
86 .I real
87 UID and GID, rather than the effective IDs as is done when
88 actually attempting an operation (e.g.,
89 .BR open (2))
90 on the file.
91 Similarly, for the root user, the check uses the set of
92 permitted capabilities rather than the set of effective
93 capabilities; and for non-root users, the check uses an empty set
94 of capabilities.
95 .P
96 This allows set-user-ID programs and capability-endowed programs
97 to easily determine the invoking user's authority.
98 In other words,
99 .BR access ()
100 does not answer the "can I read/write/execute this file?" question.
101 It answers a slightly different question:
102 "(assuming I'm a setuid binary) can
103 .I the user who invoked me
104 read/write/execute this file?",
105 which gives set-user-ID programs the possibility to
106 prevent malicious users from causing them to read files
107 which users shouldn't be able to read.
108 .P
109 If the calling process is privileged (i.e., its real UID is zero),
110 then an
111 .B X_OK
112 check is successful for a regular file if execute permission
113 is enabled for any of the file owner, group, or other.
114 .SS faccessat()
115 .BR faccessat ()
116 operates in exactly the same way as
117 .BR access (),
118 except for the differences described here.
119 .P
120 If the pathname given in
121 .I pathname
122 is relative, then it is interpreted relative to the directory
123 referred to by the file descriptor
124 .I dirfd
125 (rather than relative to the current working directory of
126 the calling process, as is done by
127 .BR access ()
128 for a relative pathname).
129 .P
130 If
131 .I pathname
132 is relative and
133 .I dirfd
134 is the special value
135 .BR AT_FDCWD ,
136 then
137 .I pathname
138 is interpreted relative to the current working
139 directory of the calling process (like
140 .BR access ()).
141 .P
142 If
143 .I pathname
144 is absolute, then
145 .I dirfd
146 is ignored.
147 .P
148 .I flags
149 is constructed by ORing together zero or more of the following values:
150 .TP
151 .B AT_EACCESS
152 Perform access checks using the effective user and group IDs.
153 By default,
154 .BR faccessat ()
155 uses the real IDs (like
156 .BR access ()).
157 .TP
158 .BR AT_EMPTY_PATH " (since Linux 5.8)"
159 If
160 .I pathname
161 is an empty string, operate on the file referred to by
162 .I dirfd
163 (which may have been obtained using the
164 .BR open (2)
165 .B O_PATH
166 flag).
167 In this case,
168 .I dirfd
169 can refer to any type of file, not just a directory.
170 If
171 .I dirfd
172 is
173 .BR AT_FDCWD ,
174 the call operates on the current working directory.
175 This flag is Linux-specific; define
176 .B _GNU_SOURCE
177 to obtain its definition.
178 .TP
179 .B AT_SYMLINK_NOFOLLOW
180 If
181 .I pathname
182 is a symbolic link, do not dereference it:
183 instead return information about the link itself.
184 .P
185 See
186 .BR openat (2)
187 for an explanation of the need for
188 .BR faccessat ().
189 .\"
190 .SS faccessat2()
191 The description of
192 .BR faccessat ()
193 given above corresponds to POSIX.1 and
194 to the implementation provided by glibc.
195 However, the glibc implementation was an imperfect emulation (see BUGS)
196 that papered over the fact that the raw Linux
197 .BR faccessat ()
198 system call does not have a
199 .I flags
200 argument.
201 To allow for a proper implementation, Linux 5.8 added the
202 .BR faccessat2 ()
203 system call, which supports the
204 .I flags
205 argument and allows a correct implementation of the
206 .BR faccessat ()
207 wrapper function.
208 .SH RETURN VALUE
209 On success (all requested permissions granted, or
210 .I mode
211 is
212 .B F_OK
213 and the file exists), zero is returned.
214 On error (at least one bit in
215 .I mode
216 asked for a permission that is denied, or
217 .I mode
218 is
219 .B F_OK
220 and the file does not exist, or some other error occurred),
221 \-1 is returned, and
222 .I errno
223 is set to indicate the error.
224 .SH ERRORS
225 .TP
226 .B EACCES
227 The requested access would be denied to the file, or search permission
228 is denied for one of the directories in the path prefix of
229 .IR pathname .
230 (See also
231 .BR path_resolution (7).)
232 .TP
233 .B EBADF
234 .RB ( faccessat ())
235 .I pathname
236 is relative but
237 .I dirfd
238 is neither
239 .B AT_FDCWD
240 .RB ( faccessat ())
241 nor a valid file descriptor.
242 .TP
243 .B EFAULT
244 .I pathname
245 points outside your accessible address space.
246 .TP
247 .B EINVAL
248 .I mode
249 was incorrectly specified.
250 .TP
251 .B EINVAL
252 .RB ( faccessat ())
253 Invalid flag specified in
254 .IR flags .
255 .TP
256 .B EIO
257 An I/O error occurred.
258 .TP
259 .B ELOOP
260 Too many symbolic links were encountered in resolving
261 .IR pathname .
262 .TP
263 .B ENAMETOOLONG
264 .I pathname
265 is too long.
266 .TP
267 .B ENOENT
268 A component of
269 .I pathname
270 does not exist or is a dangling symbolic link.
271 .TP
272 .B ENOMEM
273 Insufficient kernel memory was available.
274 .TP
275 .B ENOTDIR
276 A component used as a directory in
277 .I pathname
278 is not, in fact, a directory.
279 .TP
280 .B ENOTDIR
281 .RB ( faccessat ())
282 .I pathname
283 is relative and
284 .I dirfd
285 is a file descriptor referring to a file other than a directory.
286 .TP
287 .B EPERM
288 Write permission was requested to a file that has the immutable flag set.
289 See also
290 .BR ioctl_iflags (2).
291 .TP
292 .B EROFS
293 Write permission was requested for a file on a read-only filesystem.
294 .TP
295 .B ETXTBSY
296 Write access was requested to an executable which is being
297 executed.
298 .SH VERSIONS
299 If the calling process has appropriate privileges (i.e., is superuser),
300 POSIX.1-2001 permits an implementation to indicate success for an
301 .B X_OK
302 check even if none of the execute file permission bits are set.
303 .\" HPU-UX 11 and Tru64 5.1 do this.
304 Linux does not do this.
305 .\"
306 .SS C library/kernel differences
307 The raw
308 .BR faccessat ()
309 system call takes only the first three arguments.
310 The
311 .B AT_EACCESS
312 and
313 .B AT_SYMLINK_NOFOLLOW
314 flags are actually implemented within the glibc wrapper function for
315 .BR faccessat ().
316 If either of these flags is specified, then the wrapper function employs
317 .BR fstatat (2)
318 to determine access permissions, but see BUGS.
319 .\"
320 .SS glibc notes
321 On older kernels where
322 .BR faccessat ()
323 is unavailable (and when the
324 .B AT_EACCESS
325 and
326 .B AT_SYMLINK_NOFOLLOW
327 flags are not specified),
328 the glibc wrapper function falls back to the use of
329 .BR access ().
330 When
331 .I pathname
332 is a relative pathname,
333 glibc constructs a pathname based on the symbolic link in
334 .I /proc/self/fd
335 that corresponds to the
336 .I dirfd
337 argument.
338 .SH STANDARDS
339 .TP
340 .BR access ()
341 .TQ
342 .BR faccessat ()
343 POSIX.1-2008.
344 .TP
345 .BR faccessat2 ()
346 Linux.
347 .SH HISTORY
348 .TP
349 .BR access ()
350 SVr4, 4.3BSD, POSIX.1-2001.
351 .TP
352 .BR faccessat ()
353 Linux 2.6.16,
354 glibc 2.4.
355 .TP
356 .BR faccessat2 ()
357 Linux 5.8.
358 .SH NOTES
359 .BR Warning :
360 Using these calls to check if a user is authorized to, for example,
361 open a file before actually doing so using
362 .BR open (2)
363 creates a security hole, because the user might exploit the short time
364 interval between checking and opening the file to manipulate it.
365 .BR "For this reason, the use of this system call should be avoided" .
366 (In the example just described,
367 a safer alternative would be to temporarily switch the process's
368 effective user ID to the real ID and then call
369 .BR open (2).)
370 .P
371 .BR access ()
372 always dereferences symbolic links.
373 If you need to check the permissions on a symbolic link, use
374 .BR faccessat ()
375 with the flag
376 .BR AT_SYMLINK_NOFOLLOW .
377 .P
378 These calls return an error if any of the access types in
379 .I mode
380 is denied, even if some of the other access types in
381 .I mode
382 are permitted.
383 .P
384 A file is accessible only if the permissions on each of the
385 directories in the path prefix of
386 .I pathname
387 grant search (i.e., execute) access.
388 If any directory is inaccessible, then the
389 .BR access ()
390 call fails, regardless of the permissions on the file itself.
391 .P
392 Only access bits are checked, not the file type or contents.
393 Therefore, if a directory is found to be writable,
394 it probably means that files can be created in the directory,
395 and not that the directory can be written as a file.
396 Similarly, a DOS file may be reported as executable, but the
397 .BR execve (2)
398 call will still fail.
399 .P
400 These calls
401 may not work correctly on NFSv2 filesystems with UID mapping enabled,
402 because UID mapping is done on the server and hidden from the client,
403 which checks permissions.
404 (NFS versions 3 and higher perform the check on the server.)
405 Similar problems can occur to FUSE mounts.
406 .\"
407 .SH BUGS
408 Because the Linux kernel's
409 .BR faccessat ()
410 system call does not support a
411 .I flags
412 argument, the glibc
413 .BR faccessat ()
414 wrapper function provided in glibc 2.32 and earlier
415 emulates the required functionality using
416 a combination of the
417 .BR faccessat ()
418 system call and
419 .BR fstatat (2).
420 However, this emulation does not take ACLs into account.
421 Starting with glibc 2.33, the wrapper function avoids this bug
422 by making use of the
423 .BR faccessat2 ()
424 system call where it is provided by the underlying kernel.
425 .P
426 In Linux 2.4 (and earlier) there is some strangeness in the handling of
427 .B X_OK
428 tests for superuser.
429 If all categories of execute permission are disabled
430 for a nondirectory file, then the only
431 .BR access ()
432 test that returns \-1 is when
433 .I mode
434 is specified as just
435 .BR X_OK ;
436 if
437 .B R_OK
438 or
439 .B W_OK
440 is also specified in
441 .IR mode ,
442 then
443 .BR access ()
444 returns 0 for such files.
445 .\" This behavior appears to have been an implementation accident.
446 Early Linux 2.6 (up to and including Linux 2.6.3)
447 also behaved in the same way as Linux 2.4.
448 .P
449 Before Linux 2.6.20,
450 these calls ignored the effect of the
451 .B MS_NOEXEC
452 flag if it was used to
453 .BR mount (2)
454 the underlying filesystem.
455 Since Linux 2.6.20, the
456 .B MS_NOEXEC
457 flag is honored.
458 .SH SEE ALSO
459 .BR chmod (2),
460 .BR chown (2),
461 .BR open (2),
462 .BR setgid (2),
463 .BR setuid (2),
464 .BR stat (2),
465 .BR euidaccess (3),
466 .BR credentials (7),
467 .BR path_resolution (7),
468 .BR symlink (7)