]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
ac56b6a8 | 2 | .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. |
c11b1abf | 3 | .\" and Copyright (C) 2007 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 | .\" |
fd399570 | 43 | .TH ACCESS 2 2013-02-28 "Linux" "Linux Programmer's Manual" |
fea681da | 44 | .SH NAME |
02d79ece | 45 | access \- check real user's permissions for a file |
fea681da MK |
46 | .SH SYNOPSIS |
47 | .nf | |
48 | .B #include <unistd.h> | |
49 | .sp | |
50 | .BI "int access(const char *" pathname ", int " mode ); | |
51 | .fi | |
52 | .SH DESCRIPTION | |
e511ffb6 | 53 | .BR access () |
02d79ece | 54 | checks whether the calling process can access the file |
fea681da MK |
55 | .IR pathname . |
56 | If | |
57 | .I pathname | |
02d79ece | 58 | is a symbolic link, it is dereferenced. |
fea681da | 59 | |
02d79ece | 60 | The |
fea681da | 61 | .I mode |
02d79ece MK |
62 | specifies the accessibility check(s) to be performed, |
63 | and is either the value | |
64 | .BR F_OK , | |
60948d68 | 65 | .\" F_OK is defined as 0 on every system that I know of. |
b0742c81 | 66 | or a mask consisting of the bitwise OR of one or more of |
02d79ece | 67 | .BR R_OK ", " W_OK ", and " X_OK . |
fea681da | 68 | .B F_OK |
02d79ece MK |
69 | tests for the existence of the file. |
70 | .BR R_OK ", " W_OK ", and " X_OK | |
71 | test whether the file exists and grants read, write, and | |
72 | execute permissions, respectively. | |
fea681da | 73 | |
02d79ece | 74 | The check is done using the calling process's |
fea681da | 75 | .I real |
02d79ece MK |
76 | UID and GID, rather than the effective IDs as is done when |
77 | actually attempting an operation (e.g., | |
78 | .BR open (2)) | |
79 | on the file. | |
80 | This allows set-user-ID programs to | |
fea681da MK |
81 | easily determine the invoking user's authority. |
82 | ||
02d79ece MK |
83 | If the calling process is privileged (i.e., its real UID is zero), |
84 | then an | |
fea681da | 85 | .B X_OK |
02d79ece MK |
86 | check is successful for a regular file if execute permission |
87 | is enabled for any of the file owner, group, or other. | |
e0a699c1 | 88 | .SH "RETURN VALUE" |
fea681da MK |
89 | On success (all requested permissions granted), zero is returned. |
90 | On error (at least one bit in | |
91 | .I mode | |
92 | asked for a permission that is denied, or some other error occurred), | |
93 | \-1 is returned, and | |
94 | .I errno | |
95 | is set appropriately. | |
96 | .SH ERRORS | |
e511ffb6 | 97 | .BR access () |
fea681da MK |
98 | shall fail if: |
99 | .TP | |
100 | .B EACCES | |
dfaae362 | 101 | The requested access would be denied to the file, or search permission |
fea681da MK |
102 | is denied for one of the directories in the path prefix of |
103 | .IR pathname . | |
104 | (See also | |
ad7cc990 | 105 | .BR path_resolution (7).) |
fea681da MK |
106 | .TP |
107 | .B ELOOP | |
108 | Too many symbolic links were encountered in resolving | |
109 | .IR pathname . | |
110 | .TP | |
111 | .B ENAMETOOLONG | |
112 | .I pathname | |
113 | is too long. | |
114 | .TP | |
115 | .B ENOENT | |
33e820cb | 116 | A component of |
fea681da | 117 | .I pathname |
33e820cb | 118 | does not exist or is a dangling symbolic link. |
fea681da MK |
119 | .TP |
120 | .B ENOTDIR | |
121 | A component used as a directory in | |
122 | .I pathname | |
123 | is not, in fact, a directory. | |
124 | .TP | |
125 | .B EROFS | |
24d01c53 | 126 | Write permission was requested for a file on a read-only file system. |
fea681da | 127 | .PP |
e511ffb6 | 128 | .BR access () |
fea681da MK |
129 | may fail if: |
130 | .TP | |
131 | .B EFAULT | |
132 | .I pathname | |
133 | points outside your accessible address space. | |
134 | .TP | |
135 | .B EINVAL | |
136 | .I mode | |
137 | was incorrectly specified. | |
138 | .TP | |
139 | .B EIO | |
140 | An I/O error occurred. | |
141 | .TP | |
142 | .B ENOMEM | |
143 | Insufficient kernel memory was available. | |
144 | .TP | |
145 | .B ETXTBSY | |
146 | Write access was requested to an executable which is being | |
147 | executed. | |
e0a699c1 | 148 | .SH "CONFORMING TO" |
a1d5f77c | 149 | SVr4, 4.3BSD, POSIX.1-2001. |
b07cd0a9 | 150 | .SH NOTES |
fea681da | 151 | .PP |
4df883b9 | 152 | .BR Warning : |
fea681da | 153 | Using |
e511ffb6 | 154 | .BR access () |
dfaae362 MK |
155 | to check if a user is authorized to, for example, |
156 | open a file before actually doing so using | |
fea681da MK |
157 | .BR open (2) |
158 | creates a security hole, because the user might exploit the short time | |
159 | interval between checking and opening the file to manipulate it. | |
02d79ece | 160 | .BR "For this reason, the use of this system call should be avoided" . |
47135643 MK |
161 | (In the example just described, |
162 | a safer alternative would be to temporarily switch the process's | |
163 | effective user ID to the real ID and then call | |
164 | .BR open (2).) | |
02d79ece | 165 | .PP |
27d47e71 | 166 | .BR access () |
05b92251 MK |
167 | always dereferences symbolic links. |
168 | If you need to check the permissions on a symbolic link, use | |
6fdbc779 | 169 | .BR faccessat (2) |
05b92251 MK |
170 | with the flag |
171 | .BR AT_SYMLINK_NOFOLLOW . | |
172 | .PP | |
02d79ece MK |
173 | .BR access () |
174 | returns an error if any of the access types in | |
175 | .I mode | |
176 | is denied, even if some of the other access types in | |
177 | .I mode | |
178 | are permitted. | |
179 | .PP | |
180 | If the calling process has appropriate privileges (i.e., is superuser), | |
7a35b981 | 181 | POSIX.1-2001 permits an implementation to indicate success for an |
02d79ece MK |
182 | .B X_OK |
183 | check even if none of the execute file permission bits are set. | |
d8ccd692 | 184 | .\" HPU-UX 11 and Tru64 5.1 do this. |
02d79ece MK |
185 | Linux does not do this. |
186 | .PP | |
33a0ccb2 | 187 | A file is accessible only if the permissions on each of the |
02d79ece MK |
188 | directories in the path prefix of |
189 | .I pathname | |
190 | grant search (i.e., execute) access. | |
191 | If any directory is inaccessible, then the | |
192 | .BR access () | |
193 | call will fail, regardless of the permissions on the file itself. | |
194 | .PP | |
195 | Only access bits are checked, not the file type or contents. | |
196 | Therefore, if a directory is found to be writable, | |
197 | it probably means that files can be created in the directory, | |
198 | and not that the directory can be written as a file. | |
199 | Similarly, a DOS file may be found to be "executable," but the | |
200 | .BR execve (2) | |
201 | call will still fail. | |
202 | .PP | |
203 | .BR access () | |
204 | may not work correctly on NFS file systems with UID mapping enabled, | |
205 | because UID mapping is done on the server and hidden from the client, | |
206 | which checks permissions. | |
e0a699c1 | 207 | Similar problems can occur to FUSE mounts. |
02d79ece MK |
208 | .SH BUGS |
209 | In kernel 2.4 (and earlier) there is some strangeness in the handling of | |
210 | .B X_OK | |
211 | tests for superuser. | |
212 | If all categories of execute permission are disabled | |
24b74457 | 213 | for a nondirectory file, then the only |
02d79ece MK |
214 | .BR access () |
215 | test that returns \-1 is when | |
216 | .I mode | |
217 | is specified as just | |
218 | .BR X_OK ; | |
219 | if | |
220 | .B R_OK | |
221 | or | |
222 | .B W_OK | |
223 | is also specified in | |
224 | .IR mode , | |
225 | then | |
226 | .BR access () | |
227 | returns 0 for such files. | |
228 | .\" This behavior appears to have been an implementation accident. | |
229 | Early 2.6 kernels (up to and including 2.6.3) | |
230 | also behaved in the same way as kernel 2.4. | |
231 | ||
a1d5f77c MK |
232 | In kernels before 2.6.20, |
233 | .BR access () | |
234 | ignored the effect of the | |
235 | .B MS_NOEXEC | |
236 | flag if it was used to | |
237 | .BR mount (2) | |
238 | the underlying file system. | |
239 | Since kernel 2.6.20, | |
240 | .BR access () | |
d9bfdb9c | 241 | honors this flag. |
e0a699c1 | 242 | .SH "SEE ALSO" |
fea681da MK |
243 | .BR chmod (2), |
244 | .BR chown (2), | |
22e3b8b1 | 245 | .BR faccessat (2), |
fea681da | 246 | .BR open (2), |
fea681da MK |
247 | .BR setgid (2), |
248 | .BR setuid (2), | |
d975050c | 249 | .BR stat (2), |
70d1cb2d | 250 | .BR euidaccess (3), |
53a1443c | 251 | .BR credentials (7), |
ad7cc990 | 252 | .BR path_resolution (7) |