]> git.saurik.com Git - apple/xnu.git/blame_incremental - bsd/man/man2/access.2
xnu-3248.20.55.tar.gz
[apple/xnu.git] / bsd / man / man2 / access.2
... / ...
CommitLineData
1.\" $NetBSD: access.2,v 1.7 1995/02/27 12:31:44 cgd Exp $
2.\"
3.\" Copyright (c) 1980, 1991, 1993
4.\" The Regents of the University of California. All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
14.\" 3. All advertising materials mentioning features or use of this software
15.\" must display the following acknowledgement:
16.\" This product includes software developed by the University of
17.\" California, Berkeley and its contributors.
18.\" 4. Neither the name of the University nor the names of its contributors
19.\" may be used to endorse or promote products derived from this software
20.\" without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\" @(#)access.2 8.2 (Berkeley) 4/1/94
35.\"
36.Dd April 1, 1994
37.Dt ACCESS 2
38.Os BSD 4
39.Sh NAME
40.Nm access ,
41.Nm faccessat
42.Nd check access permissions of a file or pathname
43.Sh SYNOPSIS
44.Fd #include <unistd.h>
45.Ft int
46.Fo access
47.Fa "const char *path"
48.Fa "int amode"
49.Fc
50.Ft int
51.Fn faccessat "int fd" "const char *path" "int mode" "int flag"
52.Sh DESCRIPTION
53The
54.Fn access
55function checks the accessibility of the
56file named by
57.Fa path
58for the access permissions indicated by
59.Fa amode .
60The value of
61.Fa amode
62is the bitwise inclusive OR of the access permissions to be
63checked
64.Pf ( Dv R_OK
65for read permission,
66.Dv W_OK
67for write permission and
68.Dv X_OK
69for execute/search permission) or the existence test,
70.Dv F_OK .
71All components of the pathname
72.Fa path
73are checked for access permissions (including
74.Dv F_OK ) .
75.Pp
76The real user ID is used in place of the effective user ID
77and the real group access list
78(including the real group ID) are
79used in place of the effective ID for verifying permission.
80.Pp
81The
82.Fn faccessat
83system call is equivalent to
84.Fn access
85except in the case where
86.Fa path
87specifies a relative path.
88In this case the file whose accessibility is to be determined is
89located relative to the directory associated with the file descriptor
90.Fa fd
91instead of the current working directory.
92If
93.Fn faccessat
94is passed the special value
95.Dv AT_FDCWD
96in the
97.Fa fd
98parameter, the current working directory is used and the behavior is
99identical to a call to
100.Fn access .
101Values for
102.Fa flag
103are constructed by a bitwise-inclusive OR of flags from the following
104list, defined in
105.In fcntl.h :
106.Bl -tag -width indent
107.It Dv AT_EACCESS
108The checks for accessibility are performed using the effective user and group
109IDs instead of the real user and group ID as required in a call to
110.Fn access .
111.El
112.Pp
113Even if a process has appropriate privileges and indicates success for
114.Dv X_OK ,
115the file may not actually have execute permission bits set.
116Likewise for
117.Dv R_OK
118and
119.Dv W_OK .
120.Sh RETURN VALUES
121If
122.Fa path
123cannot be found
124or if any of the desired access modes would not be granted,
125then a -1 value is returned and the global integer variable
126.Va errno
127is set to indicate the error.
128Otherwise, a 0 value is returned.
129.Sh ERRORS
130Access to the file is denied if:
131.Bl -tag -width Er
132.\" ==========
133.It Bq Er EACCES
134Permission bits of the file mode do not permit the requested access,
135or search permission is denied on a component of the path prefix.
136.Pp
137The owner of a file has permission checked
138with respect to the ``owner'' read, write, and execute mode bits,
139members of the file's group other than the owner have permission checked
140with respect to the ``group'' mode bits,
141and all others have permissions checked
142with respect to the ``other'' mode bits.
143.\"
144.\" ==========
145.It Bq Er EFAULT
146.Fa Path
147points outside the process's allocated address space.
148.It Bq Er EINVAL
149An invalid value was specified for
150.Ar amode .
151.\" ==========
152.It Bq Er EIO
153An I/O error occurred while reading from or writing to the file system.
154.\" ==========
155.It Bq Er ELOOP
156Too many symbolic links were encountered in translating the pathname.
157.\" ==========
158.It Bq Er ENAMETOOLONG
159A component of a pathname exceeded
160.Dv {NAME_MAX}
161characters, or an entire path name exceeded
162.Dv {PATH_MAX}
163characters.
164.\" ==========
165.It Bq Er ENOENT
166The named file does not exist.
167.\" ==========
168.It Bq Er ENOTDIR
169A component of the path prefix is not a directory.
170.\" ==========
171.It Bq Er EROFS
172Write access is requested for a file on a read-only file system.
173.\" ==========
174.It Bq Er ETXTBSY
175Write access is requested for a pure procedure (shared text)
176file that is presently being executed.
177.El
178.Pp
179Also, the
180.Fn faccessat
181system call may fail if:
182.Bl -tag -width Er
183.It Bq Er EBADF
184The
185.Fa path
186argument does not specify an absolute path and the
187.Fa fd
188argument is
189neither
190.Dv AT_FDCWD
191nor a valid file descriptor.
192.It Bq Er EINVAL
193The value of the
194.Fa flag
195argument is not valid.
196.It Bq Er ENOTDIR
197The
198.Fa path
199argument is not an absolute path and
200.Fa fd
201is neither
202.Dv AT_FDCWD
203nor a file descriptor associated with a directory.
204.El
205.Sh SEE ALSO
206.Xr chmod 2 ,
207.Xr stat 2
208.Sh STANDARDS
209The
210.Fn access
211function conforms to
212.St -p1003.1-90 .
213The
214.Fn faccessat
215system call is expected to conform to POSIX.1-2008 .
216.Sh CAVEAT
217.Fn access
218is a potential security hole and
219should never be used.