Print this page
markup tweaks per mandoc author
fcntl.h only needed for faccessat
copyright
document standards for access, faccess
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man2/access.2
+++ new/usr/src/man/man2/access.2
1 -'\" te
1 +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 3 .\" Copyright 1989 AT&T
4 4 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
5 5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/.
6 6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
7 7 .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
8 8 .\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
9 9 .\" This notice shall appear on any product containing this material.
10 10 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
11 11 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
12 12 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
13 -.TH ACCESS 2 "Jun 16, 2009"
14 -.SH NAME
15 -access, faccessat \- determine accessibility of a file
16 -.SH SYNOPSIS
17 -.LP
18 -.nf
19 -#include <unistd.h>
20 -#include <sys/fcntl.h>
21 -
22 -\fBint\fR \fBaccess\fR(\fBconst char *\fR\fIpath\fR, \fBint\fR \fIamode\fR);
23 -.fi
24 -
25 -.LP
26 -.nf
27 -\fBint\fR \fBfaccessat\fR(\fBint\fR \fIfd\fR, \fBconst char *\fR\fIpath\fR, \fBint\fR \fIamode\fR, \fBint\fR \fIflag\fR);
28 -.fi
29 -
30 -.SH DESCRIPTION
31 -.sp
32 -.LP
33 -The \fBaccess()\fR function checks the file named by the pathname pointed to by
34 -the \fIpath\fR argument for accessibility according to the bit pattern
35 -contained in \fIamode\fR, using the real user \fBID\fR in place of the
36 -effective user \fBID\fR and the real group \fBID\fR in place of the effective
13 +.Dd "Jul 24, 2014"
14 +.Dt ACCESS 2
15 +.Os
16 +.Sh NAME
17 +.Nm access ,
18 +.Nm faccessat
19 +.Nd determine accessibility of a file
20 +.Sh SYNOPSIS
21 +.In unistd.h
22 +.Ft int
23 +.Fo access
24 +.Fa "const char *path"
25 +.Fa "int amode"
26 +.Fc
27 +.
28 +.In unistd.h
29 +.In fcntl.h
30 +.Ft int
31 +.Fo faccessat
32 +.Fa "int fd"
33 +.Fa "const char *path"
34 +.Fa "int amode"
35 +.Fa "int flag"
36 +.Fc
37 +.Sh DESCRIPTION
38 +The
39 +.Fn access
40 +function checks the file named by the pathname pointed to by
41 +the
42 +.Fa path
43 +argument for accessibility according to the bit pattern
44 +contained in
45 +.Fa amode ,
46 +using the real user ID in place of the
47 +effective user ID and the real group IDR in place of the effective
37 48 group ID. This allows a setuid process to verify that the user running it would
38 49 have had permission to access this file.
39 -.sp
40 -.LP
41 -The value of \fIamode\fR is either the bitwise inclusive \fBOR\fR of the access
42 -permissions to be checked (\fBR_OK\fR, \fBW_OK\fR, \fBX_OK\fR) or the existence
43 -test, \fBF_OK\fR.
44 -.sp
45 -.LP
46 -These constants are defined in <\fBunistd.h\fR> as follows:
47 -.sp
48 -.ne 2
49 -.na
50 -\fB\fBR_OK\fR\fR
51 -.ad
52 -.RS 8n
50 +.Lp
51 +The value of
52 +.Fa amode
53 +is either the bitwise inclusive
54 +.Sy OR
55 +of the access
56 +permissions to be checked
57 +.Po
58 +.Dv R_OK ,
59 +.Dv W_OK ,
60 +.Dv X_OK
61 +.Pc
62 +or the existence
63 +test,
64 +.Dv F_OK .
65 +.Lp
66 +These constants are defined in
67 +.In unistd.h
68 +as follows:
69 +.Bl -tag -offset indent -width Dv
70 +.It Dv R_OK
53 71 Test for read permission.
54 -.RE
55 -
56 -.sp
57 -.ne 2
58 -.na
59 -\fB\fBW_OK\fR\fR
60 -.ad
61 -.RS 8n
72 +.It Dv W_OK
62 73 Test for write permission.
63 -.RE
64 -
65 -.sp
66 -.ne 2
67 -.na
68 -\fB\fBX_OK\fR\fR
69 -.ad
70 -.RS 8n
74 +.It Dv X_OK
71 75 Test for execute or search permission.
72 -.RE
73 -
74 -.sp
75 -.ne 2
76 -.na
77 -\fB\fBF_OK\fR\fR
78 -.ad
79 -.RS 8n
76 +.It Dv F_OK
80 77 Check existence of file
81 -.RE
82 -
83 -.sp
84 -.LP
85 -See \fBIntro\fR(2) for additional information about "File Access Permission".
86 -.sp
87 -.LP
78 +.El
79 +.Lp
80 +See
81 +.Xr Intro 2
82 +for additional information about "File Access Permission".
83 +.Lp
88 84 If any access permissions are to be checked, each will be checked individually,
89 -as described in \fBIntro\fR(2). If the process has appropriate privileges, an
90 -implementation may indicate success for \fBX_OK\fR even if none of the execute
91 -file permission bits are set.
92 -.sp
93 -.LP
94 -The \fBfaccessat()\fR function is equivalent to the \fBaccess()\fR function,
95 -except in the case where \fIpath\fR specifies a relative path. In this case the
85 +as described in
86 +.Xr Intro 2 .
87 +If the process has appropriate privileges, an
88 +implementation may indicate success for
89 +.Dv X_OK
90 +even if none of the execute file permission bits are set.
91 +.Lp
92 +The
93 +.Fn faccessat
94 +function is equivalent to the
95 +.Fn access
96 +function,
97 +except in the case where
98 +.Fa path
99 +specifies a relative path. In this case the
96 100 file whose accessibility is to be determined is located relative to the
97 -directory associated with the file descriptor \fIfd\fR instead of the current
98 -working directory.
99 -.sp
100 -.LP
101 -If \fBfaccessat()\fR is passed in the \fIfd\fR parameter the special value
102 -\fBAT_FDCWD\fR, defined in \fB<fcntl.h>\fR, the current working directory is
103 -used and the behavior is identical to a call to \fBaccess()\fR.
104 -.sp
105 -.LP
106 -Values for \fIflag\fR are constructed by a bitwise-inclusive OR of flags from
107 -the following list, defined in \fB<fcntl.h>\fR:
108 -.sp
109 -.ne 2
110 -.na
111 -\fB\fBAT_EACCESS\fR\fR
112 -.ad
113 -.RS 14n
101 +directory associated with the file descriptor
102 +.Fa fd
103 +instead of the current working directory.
104 +.Lp
105 +If
106 +.Fn faccessat
107 +is passed in the
108 +.Fa fd
109 +parameter the special value
110 +.Dv AT_FDCWD ,
111 +defined in
112 +.In fcntl.h ,
113 +the current working directory is
114 +used and the behavior is identical to a call to
115 +.Fn access .
116 +.Lp
117 +Values for
118 +.Fa flag
119 +are constructed by a bitwise-inclusive OR of flags from
120 +the following list, defined in
121 +.In fcntl.h :
122 +.Bl -tag -offset indent -width Dv
123 +.It Dv AT_EACCESS
114 124 The checks for accessibility are performed using the effective user and group
115 125 IDs instead of the real user and group ID as required in a call to
116 -\fBaccess()\fR.
117 -.RE
118 -
119 -.SH RETURN VALUES
120 -.sp
121 -.LP
122 -If the requested access is permitted, \fBaccess()\fR and
123 -\fBfaccessat()\fRsucceed and return \fB0\fR. Otherwise, \fB\(mi1\fR is returned
124 -and \fBerrno\fR is set to indicate the error.
125 -.SH ERRORS
126 -.sp
127 -.LP
128 -The \fBaccess()\fR and \fBfaccessat()\fR functions will fail if:
129 -.sp
130 -.ne 2
131 -.na
132 -\fB\fBEACCES\fR\fR
133 -.ad
134 -.RS 16n
126 +.Fn access .
127 +.El
128 +.Sh RETURN VALUES
129 +If the requested access is permitted,
130 +.Fn access
131 +and
132 +.Fn faccessat
133 +succeed and return 0. Otherwise, \(mi1 is returned
134 +and
135 +.Va errno
136 +is set to indicate the error.
137 +.Sh ERRORS
138 +The
139 +.Fn access
140 +and
141 +.Fn faccessat
142 +functions will fail if:
143 +.Bl -tag -width Er
144 +.It Er EACCES
135 145 Permission bits of the file mode do not permit the requested access, or search
136 146 permission is denied on a component of the path prefix.
137 -.RE
138 -
139 -.sp
140 -.ne 2
141 -.na
142 -\fB\fBEFAULT\fR\fR
143 -.ad
144 -.RS 16n
145 -The \fIpath\fR argument points to an illegal address.
146 -.RE
147 -
148 -.sp
149 -.ne 2
150 -.na
151 -\fB\fBEINTR\fR\fR
152 -.ad
153 -.RS 16n
154 -A signal was caught during the \fBaccess()\fR function.
155 -.RE
156 -
157 -.sp
158 -.ne 2
159 -.na
160 -\fB\fBELOOP\fR\fR
161 -.ad
162 -.RS 16n
163 -Too many symbolic links were encountered in resolving \fIpath\fR, or loop
164 -exists in symbolic links encountered during resolution of the \fIpath\fR
147 +.
148 +.It Er EFAULT
149 +The
150 +.Fa path
151 +argument points to an illegal address.
152 +.
153 +.It Er EINTR
154 +A signal was caught during the
155 +.Fn access
156 +function.
157 +.
158 +.It Er ELOOP
159 +Too many symbolic links were encountered in resolving
160 +.Fa path ,
161 +or loop exists in symbolic links encountered during resolution of the
162 +.Fa path
165 163 argument.
166 -.RE
167 -
168 -.sp
169 -.ne 2
170 -.na
171 -\fB\fBENAMETOOLONG\fR\fR
172 -.ad
173 -.RS 16n
174 -The length of the \fIpath\fR argument exceeds {\fBPATH_MAX\fR}, or a pathname
175 -component is longer than {\fBNAME_MAX\fR} while \fB_POSIX_NO_TRUNC\fR is in
176 -effect.
177 -.RE
178 -
179 -.sp
180 -.ne 2
181 -.na
182 -\fB\fBENOENT\fR\fR
183 -.ad
184 -.RS 16n
185 -A component of \fIpath\fR does not name an existing file or \fIpath\fR is an
186 -empty string.
187 -.RE
188 -
189 -.sp
190 -.ne 2
191 -.na
192 -\fB\fBENOLINK\fR\fR
193 -.ad
194 -.RS 16n
195 -The \fIpath\fR argument points to a remote machine and the link to that machine
164 +.
165 +.It Er ENAMETOOLONG
166 +The length of the
167 +.Fa path
168 +argument exceeds
169 +.Brq Dv PATH_MAX ,
170 +or a pathname
171 +component is longer than
172 +.Brq Dv NAME_MAX
173 +while
174 +.Dv _POSIX_NO_TRUNC
175 +is in effect.
176 +.
177 +.It Er ENOENT
178 +A component of
179 +.Fa path
180 +does not name an existing file or
181 +.Fa path
182 +is an empty string.
183 +.
184 +.It Er ENOLINK
185 +The
186 +.Fa path
187 +argument points to a remote machine and the link to that machine
196 188 is no longer active.
197 -.RE
198 -
199 -.sp
200 -.ne 2
201 -.na
202 -\fB\fBENOTDIR\fR\fR
203 -.ad
204 -.RS 16n
189 +.
190 +.It Er ENOTDIR
205 191 A component of the path prefix is not a directory.
206 -.RE
207 -
208 -.sp
209 -.ne 2
210 -.na
211 -\fB\fBENXIO\fR\fR
212 -.ad
213 -.RS 16n
214 -The \fIpath\fR argument points to a character or block device special file and
192 +.
193 +.It Er ENXIO
194 +The
195 +.Fa path
196 +argument points to a character or block device special file and
215 197 the corresponding device has been retired by the fault management framework.
216 -.RE
217 -
218 -.sp
219 -.ne 2
220 -.na
221 -\fB\fBEROFS\fR\fR
222 -.ad
223 -.RS 16n
198 +.
199 +.It Er EROFS
224 200 Write access is requested for a file on a read-only file system.
225 -.RE
226 -
227 -.sp
228 -.LP
229 -The \fBfaccessat()\fR function will fail if:
230 -.sp
231 -.ne 2
232 -.na
233 -\fB\fBEBADF\fR\fR
234 -.ad
235 -.RS 9n
236 -The \fIpath\fR argument does not specify an absolute path and the \fIfd\fR
237 -argument is neither \fBAT_FDCWD\fR nor a valid file descriptor open for reading
238 -or searching.
239 -.RE
240 -
241 -.sp
242 -.LP
243 -The \fBaccess()\fR and \fBfaccessat()\fR functions may fail if:
244 -.sp
245 -.ne 2
246 -.na
247 -\fB\fBEINVAL\fR\fR
248 -.ad
249 -.RS 16n
250 -The value of the \fIamode\fR argument is invalid.
251 -.RE
252 -
253 -.sp
254 -.ne 2
255 -.na
256 -\fB\fBENAMETOOLONG\fR\fR
257 -.ad
258 -.RS 16n
201 +.
202 +.El
203 +.Lp
204 +The
205 +.Fn faccessat
206 +function will fail if:
207 +.Bl -tag -width Er
208 +.It Er EBADF
209 +The
210 +.Fa path
211 +argument does not specify an absolute path and the
212 +.Fa fd
213 +argument is neither
214 +.Dv AT_FDCWD
215 +nor a valid file descriptor open for reading or searching.
216 +.El
217 +.Lp
218 +The
219 +.Fn access
220 +and
221 +.Fn faccessat
222 +functions may fail if:
223 +.Bl -tag -width Er
224 +.
225 +.It Er EINVAL
226 +The value of the
227 +.Fa amode
228 +argument is invalid.
229 +.
230 +.It Er ENAMETOOLONG
259 231 Pathname resolution of a symbolic link produced an intermediate result whose
260 -length exceeds {\fBPATH_MAX\fR}.
261 -.RE
262 -
263 -.sp
264 -.ne 2
265 -.na
266 -\fB\fBETXTBSY\fR\fR
267 -.ad
268 -.RS 16n
232 +length exceeds
233 +.Brq Dv PATH_MAX .
234 +.
235 +.It Er ETXTBSY
269 236 Write access is requested for a pure procedure (shared text) file that is being
270 237 executed.
271 -.RE
272 -
273 -.sp
274 -.LP
275 -The \fBfaccessat()\fR function may fail if:
276 -.sp
277 -.ne 2
278 -.na
279 -\fB\fBEINVAL\fR\fR
280 -.ad
281 -.RS 11n
282 -The value of the \fIflag\fR argument is not valid.
283 -.RE
284 -
285 -.sp
286 -.ne 2
287 -.na
288 -\fB\fBENOTDIR\fR\fR
289 -.ad
290 -.RS 11n
291 -The \fIpath\fR argument is not an absolute path and \fIfd\fR is neither
292 -\fBAT_FDCWD\fR nor a file descriptor associated with a directory.
293 -.RE
294 -
295 -.SH USAGE
296 -.sp
297 -.LP
298 -Additional values of \fIamode\fR other than the set defined in the description
238 +.El
239 +.Lp
240 +The
241 +.Fn faccessat
242 +function may fail if:
243 +.Bl -tag -width Er
244 +.
245 +.It Er BEINVAL
246 +The value of the
247 +.Fa flag
248 +argument is not valid.
249 +.
250 +.It Er ENOTDIR
251 +The
252 +.Fa path
253 +argument is not an absolute path and
254 +.Fa fd
255 +is neither
256 +.Dv AT_FDCWD
257 +nor a file descriptor associated with a directory.
258 +.El
259 +.Sh USAGE
260 +Additional values of
261 +.Fa amode
262 +other than the set defined in the description
299 263 might be valid, for example, if a system has extended access controls.
300 -.sp
301 -.LP
302 -The purpose of the \fBfaccessat()\fR function is to enable the checking of the
264 +.Lp
265 +The purpose of the
266 +.Fn faccessat
267 +function is to enable the checking of the
303 268 accessibility of files in directories other than the current working directory
304 269 without exposure to race conditions. Any part of the path of a file could be
305 -changed in parallel to a call to \fBaccess()\fR, resulting in unspecified
270 +changed in parallel to a call to
271 +.Fn access ,
272 +resulting in unspecified
306 273 behavior. By opening a file descriptor for the target directory and using the
307 -\fBfaccessat()\fR function, it can be guaranteed that the file tested for
274 +.Fn faccessat
275 +function, it can be guaranteed that the file tested for
308 276 accessibility is located relative to the desired directory.
309 -.SH ATTRIBUTES
310 -.sp
311 -.LP
312 -See \fBattributes\fR(5) for descriptions of the following attributes:
313 -.sp
314 -
315 -.sp
316 -.TS
317 -box;
318 -c | c
319 -l | l .
320 -ATTRIBUTE TYPE ATTRIBUTE VALUE
321 -_
322 -Interface Stability Committed
323 -_
324 -MT-Level Async-Signal-Safe
325 -_
326 -Standard See below.
327 -.TE
328 -
329 -.sp
330 -.LP
331 -For \fBaccess()\fR, see \fBstandards\fR(5).
332 -.SH SEE ALSO
333 -.sp
334 -.LP
335 -\fBIntro\fR(2), \fBchmod\fR(2), \fBstat\fR(2), \fBattributes\fR(5),
336 -\fBstandards\fR(5)
277 +.Sh INTERFACE STABILITY
278 +.Sy Standard .
279 +.Sh MT-LEVEL
280 +.Sy Async-Signal-Safe .
281 +.Sh SEE ALSO
282 +.Xr Intro 2 ,
283 +.Xr chmod 2 ,
284 +.Xr stat 2 ,
285 +.Xr standards 5
286 +.Sh STANDARDS
287 +The
288 +.Fn access
289 +function is defined in
290 +.St -p1003.1 .
291 +The
292 +.Fn faccessat
293 +function was introduced in
294 +.St -p1003.1-2008 .
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX