]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
ac56b6a8 | 2 | .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. |
687dcec2 | 3 | .\" and Copyright (C) 2004, 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 4 | .\" |
93015253 | 5 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
6 | .\" Permission is granted to make and distribute verbatim copies of this |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
c13182ef | 14 | .\" |
fea681da MK |
15 | .\" Since the Linux kernel and libraries are constantly changing, this |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
c13182ef | 22 | .\" |
fea681da MK |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
fea681da MK |
26 | .\" |
27 | .\" Modified 1993-07-21 Rik Faith (faith@cs.unc.edu) | |
28 | .\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com): | |
29 | .\" Removed note about old kernel (pre-1.1.44) using wrong id on path. | |
30 | .\" Modified 1996-03-18 by Martin Schulze (joey@infodrom.north.de): | |
31 | .\" Stated more clearly how it behaves with symbolic links. | |
32 | .\" Added correction due to Nick Duffek (nsd@bbc.com), aeb, 960426 | |
33 | .\" Modified 1996-09-07 by Michael Haardt: | |
34 | .\" Restrictions for NFS | |
35 | .\" Modified 1997-09-09 by Joseph S. Myers <jsm28@cam.ac.uk> | |
36 | .\" Modified 1998-01-13 by Michael Haardt: | |
37 | .\" Using access is often insecure | |
38 | .\" Modified 2001-10-16 by aeb | |
39 | .\" Modified 2002-04-23 by Roger Luethi <rl@hellgate.ch> | |
40 | .\" Modified 2004-06-23 by Michael Kerrisk | |
02d79ece | 41 | .\" 2007-06-10, mtk, various parts rewritten, and added BUGS section. |
fea681da | 42 | .\" |
97986708 | 43 | .TH ACCESS 2 2016-03-15 "Linux" "Linux Programmer's Manual" |
fea681da | 44 | .SH NAME |
687dcec2 | 45 | access, faccessat \- check user's permissions for a file |
fea681da MK |
46 | .SH SYNOPSIS |
47 | .nf | |
48 | .B #include <unistd.h> | |
4ba0bbde | 49 | .PP |
fea681da | 50 | .BI "int access(const char *" pathname ", int " mode ); |
687dcec2 | 51 | |
2626921f | 52 | .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" |
687dcec2 | 53 | .B #include <unistd.h> |
4ba0bbde | 54 | .PP |
687dcec2 MK |
55 | .BI "int faccessat(int " dirfd ", const char *" pathname ", int " \ |
56 | mode ", int " flags ); | |
57 | .fi | |
4ba0bbde | 58 | .PP |
687dcec2 MK |
59 | .in -4n |
60 | Feature Test Macro Requirements for glibc (see | |
61 | .BR feature_test_macros (7)): | |
62 | .in | |
4ba0bbde | 63 | .PP |
687dcec2 MK |
64 | .BR faccessat (): |
65 | .PD 0 | |
66 | .ad l | |
67 | .RS 4 | |
68 | .TP 4 | |
69 | Since glibc 2.10: | |
b0da7b8b | 70 | _POSIX_C_SOURCE\ >=\ 200809L |
687dcec2 MK |
71 | .TP |
72 | Before glibc 2.10: | |
73 | _ATFILE_SOURCE | |
74 | .RE | |
75 | .ad | |
76 | .PD | |
fea681da | 77 | .SH DESCRIPTION |
e511ffb6 | 78 | .BR access () |
02d79ece | 79 | checks whether the calling process can access the file |
fea681da MK |
80 | .IR pathname . |
81 | If | |
82 | .I pathname | |
02d79ece | 83 | is a symbolic link, it is dereferenced. |
4ba0bbde | 84 | .PP |
02d79ece | 85 | The |
fea681da | 86 | .I mode |
02d79ece MK |
87 | specifies the accessibility check(s) to be performed, |
88 | and is either the value | |
89 | .BR F_OK , | |
60948d68 | 90 | .\" F_OK is defined as 0 on every system that I know of. |
b0742c81 | 91 | or a mask consisting of the bitwise OR of one or more of |
02d79ece | 92 | .BR R_OK ", " W_OK ", and " X_OK . |
fea681da | 93 | .B F_OK |
02d79ece MK |
94 | tests for the existence of the file. |
95 | .BR R_OK ", " W_OK ", and " X_OK | |
96 | test whether the file exists and grants read, write, and | |
97 | execute permissions, respectively. | |
4ba0bbde | 98 | .PP |
02d79ece | 99 | The check is done using the calling process's |
fea681da | 100 | .I real |
02d79ece MK |
101 | UID and GID, rather than the effective IDs as is done when |
102 | actually attempting an operation (e.g., | |
103 | .BR open (2)) | |
cae279c4 MK |
104 | on the file. |
105 | Similarly, for the root user, the check uses the set of | |
062d1cb3 | 106 | permitted capabilities rather than the set of effective |
cae279c4 | 107 | capabilities; and for non-root users, the check uses an empty set |
062d1cb3 | 108 | of capabilities. |
4ba0bbde | 109 | .PP |
062d1cb3 | 110 | This allows set-user-ID programs and capability-endowed programs |
cae279c4 MK |
111 | to easily determine the invoking user's authority. |
112 | In other words, | |
062d1cb3 DV |
113 | .BR access () |
114 | does not answer the "can I read/write/execute this file?" question. | |
cae279c4 MK |
115 | It answers a slightly different question: |
116 | "(assuming I'm a setuid binary) can | |
062d1cb3 DV |
117 | .I the user who invoked me |
118 | read/write/execute this file?", | |
cae279c4 MK |
119 | which gives set-user-ID programs the possibility to |
120 | prevent malicious users from causing them to read files | |
121 | which users shouldn't be able to read. | |
4ba0bbde | 122 | .PP |
02d79ece MK |
123 | If the calling process is privileged (i.e., its real UID is zero), |
124 | then an | |
fea681da | 125 | .B X_OK |
02d79ece MK |
126 | check is successful for a regular file if execute permission |
127 | is enabled for any of the file owner, group, or other. | |
e04fe041 | 128 | .SS faccessat() |
687dcec2 MK |
129 | The |
130 | .BR faccessat () | |
131 | system call operates in exactly the same way as | |
cadd38ba | 132 | .BR access (), |
687dcec2 | 133 | except for the differences described here. |
4ba0bbde | 134 | .PP |
687dcec2 MK |
135 | If the pathname given in |
136 | .I pathname | |
137 | is relative, then it is interpreted relative to the directory | |
138 | referred to by the file descriptor | |
139 | .I dirfd | |
140 | (rather than relative to the current working directory of | |
141 | the calling process, as is done by | |
9d3ea7a2 | 142 | .BR access () |
687dcec2 | 143 | for a relative pathname). |
4ba0bbde | 144 | .PP |
687dcec2 MK |
145 | If |
146 | .I pathname | |
147 | is relative and | |
148 | .I dirfd | |
149 | is the special value | |
150 | .BR AT_FDCWD , | |
151 | then | |
152 | .I pathname | |
153 | is interpreted relative to the current working | |
154 | directory of the calling process (like | |
98d3114d | 155 | .BR access ()). |
4ba0bbde | 156 | .PP |
687dcec2 MK |
157 | If |
158 | .I pathname | |
159 | is absolute, then | |
160 | .I dirfd | |
161 | is ignored. | |
4ba0bbde | 162 | .PP |
687dcec2 MK |
163 | .I flags |
164 | is constructed by ORing together zero or more of the following values: | |
165 | .TP | |
166 | .B AT_EACCESS | |
167 | Perform access checks using the effective user and group IDs. | |
168 | By default, | |
169 | .BR faccessat () | |
170 | uses the real IDs (like | |
98d3114d | 171 | .BR access ()). |
687dcec2 MK |
172 | .TP |
173 | .B AT_SYMLINK_NOFOLLOW | |
174 | If | |
175 | .I pathname | |
176 | is a symbolic link, do not dereference it: | |
177 | instead return information about the link itself. | |
2907fa3e MK |
178 | .PP |
179 | See | |
180 | .BR openat (2) | |
181 | for an explanation of the need for | |
182 | .BR faccessat (). | |
d282bb24 | 183 | .SH RETURN VALUE |
72d34312 MK |
184 | On success (all requested permissions granted, or |
185 | .I mode | |
186 | is | |
187 | .B F_OK | |
188 | and the file exists), zero is returned. | |
fea681da MK |
189 | On error (at least one bit in |
190 | .I mode | |
72d34312 MK |
191 | asked for a permission that is denied, or |
192 | .I mode | |
193 | is | |
194 | .B F_OK | |
195 | and the file does not exist, or some other error occurred), | |
fea681da MK |
196 | \-1 is returned, and |
197 | .I errno | |
198 | is set appropriately. | |
199 | .SH ERRORS | |
e511ffb6 | 200 | .BR access () |
32e370f2 MK |
201 | and |
202 | .BR faccessat () | |
fea681da MK |
203 | shall fail if: |
204 | .TP | |
205 | .B EACCES | |
dfaae362 | 206 | The requested access would be denied to the file, or search permission |
fea681da MK |
207 | is denied for one of the directories in the path prefix of |
208 | .IR pathname . | |
209 | (See also | |
ad7cc990 | 210 | .BR path_resolution (7).) |
fea681da MK |
211 | .TP |
212 | .B ELOOP | |
213 | Too many symbolic links were encountered in resolving | |
214 | .IR pathname . | |
215 | .TP | |
216 | .B ENAMETOOLONG | |
217 | .I pathname | |
218 | is too long. | |
219 | .TP | |
220 | .B ENOENT | |
33e820cb | 221 | A component of |
fea681da | 222 | .I pathname |
33e820cb | 223 | does not exist or is a dangling symbolic link. |
fea681da MK |
224 | .TP |
225 | .B ENOTDIR | |
226 | A component used as a directory in | |
227 | .I pathname | |
228 | is not, in fact, a directory. | |
229 | .TP | |
230 | .B EROFS | |
9ee4a2b6 | 231 | Write permission was requested for a file on a read-only filesystem. |
fea681da | 232 | .PP |
e511ffb6 | 233 | .BR access () |
32e370f2 MK |
234 | and |
235 | .BR faccessat () | |
fea681da MK |
236 | may fail if: |
237 | .TP | |
238 | .B EFAULT | |
239 | .I pathname | |
240 | points outside your accessible address space. | |
241 | .TP | |
242 | .B EINVAL | |
243 | .I mode | |
244 | was incorrectly specified. | |
245 | .TP | |
246 | .B EIO | |
247 | An I/O error occurred. | |
248 | .TP | |
249 | .B ENOMEM | |
250 | Insufficient kernel memory was available. | |
251 | .TP | |
252 | .B ETXTBSY | |
253 | Write access was requested to an executable which is being | |
254 | executed. | |
687dcec2 MK |
255 | .PP |
256 | The following additional errors can occur for | |
257 | .BR faccessat (): | |
258 | .TP | |
259 | .B EBADF | |
260 | .I dirfd | |
261 | is not a valid file descriptor. | |
262 | .TP | |
263 | .B EINVAL | |
264 | Invalid flag specified in | |
265 | .IR flags . | |
266 | .TP | |
267 | .B ENOTDIR | |
268 | .I pathname | |
269 | is relative and | |
270 | .I dirfd | |
271 | is a file descriptor referring to a file other than a directory. | |
272 | .SH VERSIONS | |
273 | .BR faccessat () | |
274 | was added to Linux in kernel 2.6.16; | |
275 | library support was added to glibc in version 2.4. | |
d282bb24 | 276 | .SH CONFORMING TO |
9d3ea7a2 | 277 | .BR access (): |
b9f4755d | 278 | SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. |
4ba0bbde | 279 | .PP |
cadd38ba | 280 | .BR faccessat (): |
687dcec2 | 281 | POSIX.1-2008. |
b07cd0a9 | 282 | .SH NOTES |
fea681da | 283 | .PP |
4df883b9 | 284 | .BR Warning : |
32e370f2 | 285 | Using these calls to check if a user is authorized to, for example, |
dfaae362 | 286 | open a file before actually doing so using |
fea681da MK |
287 | .BR open (2) |
288 | creates a security hole, because the user might exploit the short time | |
289 | interval between checking and opening the file to manipulate it. | |
02d79ece | 290 | .BR "For this reason, the use of this system call should be avoided" . |
47135643 MK |
291 | (In the example just described, |
292 | a safer alternative would be to temporarily switch the process's | |
293 | effective user ID to the real ID and then call | |
294 | .BR open (2).) | |
02d79ece | 295 | .PP |
27d47e71 | 296 | .BR access () |
05b92251 MK |
297 | always dereferences symbolic links. |
298 | If you need to check the permissions on a symbolic link, use | |
9f102936 | 299 | .BR faccessat () |
05b92251 MK |
300 | with the flag |
301 | .BR AT_SYMLINK_NOFOLLOW . | |
302 | .PP | |
32e370f2 | 303 | These calls return an error if any of the access types in |
02d79ece MK |
304 | .I mode |
305 | is denied, even if some of the other access types in | |
306 | .I mode | |
307 | are permitted. | |
308 | .PP | |
309 | If the calling process has appropriate privileges (i.e., is superuser), | |
7a35b981 | 310 | POSIX.1-2001 permits an implementation to indicate success for an |
02d79ece MK |
311 | .B X_OK |
312 | check even if none of the execute file permission bits are set. | |
d8ccd692 | 313 | .\" HPU-UX 11 and Tru64 5.1 do this. |
02d79ece MK |
314 | Linux does not do this. |
315 | .PP | |
33a0ccb2 | 316 | A file is accessible only if the permissions on each of the |
02d79ece MK |
317 | directories in the path prefix of |
318 | .I pathname | |
319 | grant search (i.e., execute) access. | |
320 | If any directory is inaccessible, then the | |
321 | .BR access () | |
26cd31fd | 322 | call fails, regardless of the permissions on the file itself. |
02d79ece MK |
323 | .PP |
324 | Only access bits are checked, not the file type or contents. | |
325 | Therefore, if a directory is found to be writable, | |
326 | it probably means that files can be created in the directory, | |
327 | and not that the directory can be written as a file. | |
328 | Similarly, a DOS file may be found to be "executable," but the | |
329 | .BR execve (2) | |
330 | call will still fail. | |
331 | .PP | |
32e370f2 | 332 | These calls |
1a7d4eb7 | 333 | may not work correctly on NFSv2 filesystems with UID mapping enabled, |
02d79ece | 334 | because UID mapping is done on the server and hidden from the client, |
1a7d4eb7 BF |
335 | which checks permissions. (NFS versions 3 and higher perform the check on |
336 | the server.) | |
e0a699c1 | 337 | Similar problems can occur to FUSE mounts. |
92692952 MK |
338 | .\" |
339 | .\" | |
0722a578 | 340 | .SS C library/kernel differences |
2907fa3e MK |
341 | The raw |
342 | .BR faccessat () | |
343 | system call takes only the first three arguments. | |
687dcec2 MK |
344 | The |
345 | .B AT_EACCESS | |
346 | and | |
347 | .B AT_SYMLINK_NOFOLLOW | |
348 | flags are actually implemented within the glibc wrapper function for | |
349 | .BR faccessat (). | |
350 | If either of these flags is specified, then the wrapper function employs | |
351 | .BR fstatat (2) | |
352 | to determine access permissions. | |
cf81f364 MK |
353 | .SS Glibc notes |
354 | On older kernels where | |
355 | .BR faccessat () | |
356 | is unavailable (and when the | |
357 | .B AT_EACCESS | |
358 | and | |
359 | .B AT_SYMLINK_NOFOLLOW | |
360 | flags are not specified), | |
361 | the glibc wrapper function falls back to the use of | |
362 | .BR access (). | |
363 | When | |
364 | .I pathname | |
365 | is a relative pathname, | |
366 | glibc constructs a pathname based on the symbolic link in | |
367 | .IR /proc/self/fd | |
368 | that corresponds to the | |
369 | .IR dirfd | |
370 | argument. | |
02d79ece MK |
371 | .SH BUGS |
372 | In kernel 2.4 (and earlier) there is some strangeness in the handling of | |
373 | .B X_OK | |
374 | tests for superuser. | |
375 | If all categories of execute permission are disabled | |
24b74457 | 376 | for a nondirectory file, then the only |
02d79ece MK |
377 | .BR access () |
378 | test that returns \-1 is when | |
379 | .I mode | |
380 | is specified as just | |
381 | .BR X_OK ; | |
382 | if | |
383 | .B R_OK | |
384 | or | |
385 | .B W_OK | |
386 | is also specified in | |
387 | .IR mode , | |
388 | then | |
389 | .BR access () | |
390 | returns 0 for such files. | |
391 | .\" This behavior appears to have been an implementation accident. | |
392 | Early 2.6 kernels (up to and including 2.6.3) | |
393 | also behaved in the same way as kernel 2.4. | |
4ba0bbde | 394 | .PP |
a1d5f77c | 395 | In kernels before 2.6.20, |
32e370f2 | 396 | these calls ignored the effect of the |
a1d5f77c MK |
397 | .B MS_NOEXEC |
398 | flag if it was used to | |
399 | .BR mount (2) | |
9ee4a2b6 | 400 | the underlying filesystem. |
32e370f2 MK |
401 | Since kernel 2.6.20, the |
402 | .B MS_NOEXEC | |
8d0418af | 403 | flag is honored. |
d282bb24 | 404 | .SH SEE ALSO |
fea681da MK |
405 | .BR chmod (2), |
406 | .BR chown (2), | |
407 | .BR open (2), | |
fea681da MK |
408 | .BR setgid (2), |
409 | .BR setuid (2), | |
d975050c | 410 | .BR stat (2), |
70d1cb2d | 411 | .BR euidaccess (3), |
53a1443c | 412 | .BR credentials (7), |
687dcec2 MK |
413 | .BR path_resolution (7), |
414 | .BR symlink (7) |