Debian Codegraph @

upstream/debian-unstable/man2/access.2

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