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)