1 '\" te
2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
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 .\" 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 .\" 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 .\" 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 .\" This notice shall appear on any product containing this material.
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 .\" 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 .\" 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
37 group ID. This allows a setuid process to verify that the user running it would
38 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
53 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
62 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
71 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
80 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
88 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
96 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
114 The checks for accessibility are performed using the effective user and group
115 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
135 Permission bits of the file mode do not permit the requested access, or search
136 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
165 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
196 is no longer active.
197 .RE
198
199 .sp
200 .ne 2
201 .na
202 \fB\fBENOTDIR\fR\fR
203 .ad
204 .RS 16n
205 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
215 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
224 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
259 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
269 Write access is requested for a pure procedure (shared text) file that is being
270 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
299 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
303 accessibility of files in directories other than the current working directory
304 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
306 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
308 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)
|
1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
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 .\" 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 .\" 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 .\" 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 .\" This notice shall appear on any product containing this material.
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 .\" 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 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
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
48 group ID. This allows a setuid process to verify that the user running it would
49 have had permission to access this file.
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
71 Test for read permission.
72 .It Dv W_OK
73 Test for write permission.
74 .It Dv X_OK
75 Test for execute or search permission.
76 .It Dv F_OK
77 Check existence of file
78 .El
79 .Lp
80 See
81 .Xr Intro 2
82 for additional information about "File Access Permission".
83 .Lp
84 If any access permissions are to be checked, each will be checked individually,
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
100 file whose accessibility is to be determined is located relative to the
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
124 The checks for accessibility are performed using the effective user and group
125 IDs instead of the real user and group ID as required in a call to
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
145 Permission bits of the file mode do not permit the requested access, or search
146 permission is denied on a component of the path prefix.
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
163 argument.
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
188 is no longer active.
189 .
190 .It Er ENOTDIR
191 A component of the path prefix is not a directory.
192 .
193 .It Er ENXIO
194 The
195 .Fa path
196 argument points to a character or block device special file and
197 the corresponding device has been retired by the fault management framework.
198 .
199 .It Er EROFS
200 Write access is requested for a file on a read-only file system.
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
231 Pathname resolution of a symbolic link produced an intermediate result whose
232 length exceeds
233 .Brq Dv PATH_MAX .
234 .
235 .It Er ETXTBSY
236 Write access is requested for a pure procedure (shared text) file that is being
237 executed.
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
263 might be valid, for example, if a system has extended access controls.
264 .Lp
265 The purpose of the
266 .Fn faccessat
267 function is to enable the checking of the
268 accessibility of files in directories other than the current working directory
269 without exposure to race conditions. Any part of the path of a file could be
270 changed in parallel to a call to
271 .Fn access ,
272 resulting in unspecified
273 behavior. By opening a file descriptor for the target directory and using the
274 .Fn faccessat
275 function, it can be guaranteed that the file tested for
276 accessibility is located relative to the desired directory.
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 .
|