]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" This manpage is Copyright (C) 1992 Drew Eckhardt; | |
4 | .\" 1993 Michael Haardt, Ian Jackson. | |
5 | .\" | |
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. | |
25 | .\" | |
26 | .\" Modified 1993-07-21 Rik Faith (faith@cs.unc.edu) | |
27 | .\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com): | |
28 | .\" Removed note about old kernel (pre-1.1.44) using wrong id on path. | |
29 | .\" Modified 1996-03-18 by Martin Schulze (joey@infodrom.north.de): | |
30 | .\" Stated more clearly how it behaves with symbolic links. | |
31 | .\" Added correction due to Nick Duffek (nsd@bbc.com), aeb, 960426 | |
32 | .\" Modified 1996-09-07 by Michael Haardt: | |
33 | .\" Restrictions for NFS | |
34 | .\" Modified 1997-09-09 by Joseph S. Myers <jsm28@cam.ac.uk> | |
35 | .\" Modified 1998-01-13 by Michael Haardt: | |
36 | .\" Using access is often insecure | |
37 | .\" Modified 2001-10-16 by aeb | |
38 | .\" Modified 2002-04-23 by Roger Luethi <rl@hellgate.ch> | |
39 | .\" Modified 2004-06-23 by Michael Kerrisk | |
40 | .\" | |
41 | .TH ACCESS 2 2004-06-23 "Linux" "Linux Programmer's Manual" | |
42 | .SH NAME | |
43 | access \- check user's permissions for a file | |
44 | .SH SYNOPSIS | |
45 | .nf | |
46 | .B #include <unistd.h> | |
47 | .sp | |
48 | .BI "int access(const char *" pathname ", int " mode ); | |
49 | .fi | |
50 | .SH DESCRIPTION | |
e511ffb6 | 51 | .BR access () |
fea681da MK |
52 | checks whether the process would be allowed to read, |
53 | write or test for existence of the file (or other file system | |
54 | object) whose name is | |
55 | .IR pathname . | |
56 | If | |
57 | .I pathname | |
58 | is a symbolic link permissions of the file referred to by this | |
59 | symbolic link are tested. | |
60 | ||
61 | .I mode | |
62 | is a mask consisting of one or more of | |
63 | .BR R_OK ", " W_OK ", " X_OK " and " F_OK . | |
64 | ||
65 | .BR R_OK ", " W_OK " and " X_OK | |
66 | request checking whether the file exists and has read, write and | |
67 | execute permissions, respectively. | |
68 | .B F_OK | |
69 | just requests checking for the existence of the file. | |
70 | ||
71 | The tests depend on the permissions of the directories | |
72 | occurring in the path to the file, as given in | |
73 | .IR pathname , | |
74 | and on the permissions of directories and files referred to by symbolic | |
75 | links encountered on the way. | |
76 | ||
77 | The check is done with the process's | |
78 | .I real | |
79 | UID and GID, rather than with the effective IDs as is done when | |
880f5b4b MK |
80 | actually attempting an operation. |
81 | This is to allow set-user-ID programs to | |
fea681da MK |
82 | easily determine the invoking user's authority. |
83 | ||
c13182ef MK |
84 | Only access bits are checked, not the file type or contents. |
85 | Therefore, if | |
fea681da MK |
86 | a directory is found to be "writable," it probably means that files can be |
87 | created in the directory, and not that the directory can be written as a | |
c13182ef MK |
88 | file. |
89 | Similarly, a DOS file may be found to be "executable," but the | |
fea681da MK |
90 | .BR execve (2) |
91 | call will still fail. | |
92 | ||
93 | If the process has appropriate privileges, an implementation may | |
94 | indicate success for | |
95 | .B X_OK | |
c13182ef | 96 | even if none of the execute file permission bits are set. |
fea681da MK |
97 | .SH "RETURN VALUE" |
98 | On success (all requested permissions granted), zero is returned. | |
99 | On error (at least one bit in | |
100 | .I mode | |
101 | asked for a permission that is denied, or some other error occurred), | |
102 | \-1 is returned, and | |
103 | .I errno | |
104 | is set appropriately. | |
105 | .SH ERRORS | |
e511ffb6 | 106 | .BR access () |
fea681da MK |
107 | shall fail if: |
108 | .TP | |
109 | .B EACCES | |
110 | The requested access would be denied to the file or search permission | |
111 | is denied for one of the directories in the path prefix of | |
112 | .IR pathname . | |
113 | (See also | |
114 | .BR path_resolution (2).) | |
115 | .TP | |
116 | .B ELOOP | |
117 | Too many symbolic links were encountered in resolving | |
118 | .IR pathname . | |
119 | .TP | |
120 | .B ENAMETOOLONG | |
121 | .I pathname | |
122 | is too long. | |
123 | .TP | |
124 | .B ENOENT | |
33e820cb | 125 | A component of |
fea681da | 126 | .I pathname |
33e820cb | 127 | does not exist or is a dangling symbolic link. |
fea681da MK |
128 | .TP |
129 | .B ENOTDIR | |
130 | A component used as a directory in | |
131 | .I pathname | |
132 | is not, in fact, a directory. | |
133 | .TP | |
134 | .B EROFS | |
135 | Write permission was requested for a file on a read-only filesystem. | |
136 | .PP | |
e511ffb6 | 137 | .BR access () |
fea681da MK |
138 | may fail if: |
139 | .TP | |
140 | .B EFAULT | |
141 | .I pathname | |
142 | points outside your accessible address space. | |
143 | .TP | |
144 | .B EINVAL | |
145 | .I mode | |
146 | was incorrectly specified. | |
147 | .TP | |
148 | .B EIO | |
149 | An I/O error occurred. | |
150 | .TP | |
151 | .B ENOMEM | |
152 | Insufficient kernel memory was available. | |
153 | .TP | |
154 | .B ETXTBSY | |
155 | Write access was requested to an executable which is being | |
156 | executed. | |
4fb31341 MK |
157 | .SH "NOTES" |
158 | .SS Linux Notes | |
dc0b1e23 MK |
159 | In kernels before 2.6.20, |
160 | .BR access () | |
c13182ef | 161 | ignored the effect of the |
dc0b1e23 MK |
162 | .B MS_NOEXEC |
163 | flag if it was used to | |
164 | .BR mount (2) | |
165 | the underlying file system. | |
166 | Since kernel 2.6.20, | |
167 | .BR access () | |
168 | honours this flag. | |
b07cd0a9 | 169 | .SH NOTES |
e511ffb6 | 170 | .BR access () |
fea681da MK |
171 | returns an error if any of the access types in the requested call |
172 | fails, even if other types might be successful. | |
173 | .PP | |
e511ffb6 | 174 | .BR access () |
fea681da MK |
175 | may not work correctly on NFS file systems with UID mapping enabled, |
176 | because UID mapping is done on the server and hidden from the client, | |
177 | which checks permissions. | |
178 | .PP | |
b07cd0a9 | 179 | .BR Warning: |
fea681da | 180 | Using |
e511ffb6 | 181 | .BR access () |
fea681da MK |
182 | to check if a user is authorized to e.g. open a file before actually |
183 | doing so using | |
184 | .BR open (2) | |
185 | creates a security hole, because the user might exploit the short time | |
186 | interval between checking and opening the file to manipulate it. | |
187 | .SH "CONFORMING TO" | |
75b48e9d | 188 | SVr4, 4.3BSD, POSIX.1-2001. |
fea681da MK |
189 | .SH "SEE ALSO" |
190 | .BR chmod (2), | |
191 | .BR chown (2), | |
22e3b8b1 | 192 | .BR faccessat (2), |
fea681da MK |
193 | .BR open (2), |
194 | .BR path_resolution (2), | |
195 | .BR setgid (2), | |
196 | .BR setuid (2), | |
d975050c MK |
197 | .BR stat (2), |
198 | .BR eauidaccess (3) |