Copyright (c) 1980, 1991, 1993
The Regents of the University of California. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the name of the University nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
@(#)access.2 8.2 (Berkeley) 4/1/94
.Dd January 12, 2013 .Dt ACCESS 2 .Os .Sh NAME .Nm access , .Nm faccessat .Nd check access permissions of a file or pathname .Sh LIBRARY .Lb libc .Sh SYNOPSIS n unistd.h .Ft int .Fn access "const char *path" "int mode" n fcntl.h .Ft int .Fn faccessat "int fd" "const char *path" "int mode" "int flags" .Sh DESCRIPTION The .Fn access function checks the accessibility of the file named by .Fa path . The .Fn faccessat function checks the accessibility of the file named by .Fa path using .Fa fd as the starting point for relative pathnames. If .Fa fd is .Dv AT_FDCWD the current directory is used. Calling .Fn access is equivalent to calling .Fn faccessat with .Fa fd set to .Dv AT_FDCWD and .Fa flags set to 0.
p The form of access to check is specified by the bitwise or of the following values for .Fa mode : l -tag -width W_OK t Dv R_OK Check for read permission. t Dv W_OK Check for write permission. t Dv X_OK Check for execute/search permission. t Dv F_OK Check only for existence. .El
p All components of the pathname .Fa path are checked for access permissions as well.
p
Maybe this paragraph should be removed...
The owner of a file has permission checked with respect to the
.Dq owner
read, write, and execute mode bits, members of the file's group
other than the owner have permission checked with respect to the
.Dq group
mode bits, and all others have permissions checked with respect to
the
.Dq other
mode bits.
p
The file descriptor
.Fa fd
must name a directory.
Search permission is required on this directory.
(These alternatives await a decision about the semantics of O_SEARCH)
Search permission is required on this directory, except if
.Fa fd
was opened with the
.Dv O_SEARCH
flag.
- or -
The directory referred to by
.Fa fd
must have been opened with the
.Dv O_SEARCH
flag.
- or -
The directory referred to by
.Fa fd
must have been opened with the
.Dv O_SEARCH
flag or must be searchable by the current process at the time the
call is made.
p The .Fa flags argument to .Fn faccessat can specify the following optional behavior: l -tag -width AT_SYMLINK_NOFOLLOW t AT_EACCESS Use the effective user and group IDs instead of the real user and group IDs for checking permission. See discussion below. t AT_SYMLINK_NOFOLLOW Do not follow a symbolic link encountered as the last component in .Fa path . .El
p For .Fn access , and .Fn faccessat when the .Dv AT_EACCESS flag is not passed, the real user ID and the real group ID are used for checking permission in place of the effective user ID and effective group ID. This affects only set-user-ID and set-group-ID programs, which should not use these functions. (For other programs, the real and effective IDs are the same.)
p
For processes running with super-user privileges, these functions may
return success for read and write checks regardless of whether read
and write permission bits are actually set.
This reflects the fact that the super-user may read and write all
files regardless of permission settings.
However, even for the super-user, an execute check using
.Dv X_OK
will succeed only if the target object has at least one of its
execute permission bits set.
XXX: Is this true of search permission and directories? (I believe so.)
(This does not guarantee that the target object can necessarily be
successfully executed.
See
.Xr execve 2 . )
.Sh RETURN VALUES
The
.Fn access
and
.Fn faccessat
functions succeed and return 0 if, at some point in the recent past,
the target object named by
.Fa path
existed and its permission settings allowed the requested access as
described above.
If the requested access would not have been granted, the object did
not exist, or the path lookup failed, the value -1 is returned
and the value of
.Va errno
is set to reflect what went wrong.
.Sh ERRORS
These functions fail if:
l -tag -width Er t Bq Er EACCES Search permission is denied for
.Fa fd ,
or for the current directory, or for a directory in the prefix of
.Fa path ;
or the permission bits on the target file system object do not permit
the requested access.
t Bq Er EBADF The file descriptor
.Fa fd
is not open and is not
.Dv AT_FDCWD .
(possibly -- future)
or was not opened for searching with
.Dv O_SEARCH .
t Bq Er EFAULT .Fa path
points outside the process's allocated address space.
t Bq Er EINVAL The
.Fa mode
or
.Fa flags
argument contained an invalid value.
t Bq Er EIO An I/O error occurred while reading from or writing to the file system.
t Bq Er ELOOP Too many symbolic links were encountered in translating the pathname.
t Bq Er ENAMETOOLONG A component of a pathname exceeded
rq Dv NAME_MAX characters, or an entire path name exceeded
rq Dv PATH_MAX characters.
t Bq Er ENOENT The named file does not exist.
t Bq Er ENOTDIR The file descriptor
.Fa fd
does not name a directory, or a component of the path prefix is not a
directory.
t Bq Er EROFS Write access is requested for a file on a read-only file system.
t Bq Er ETXTBSY Write access is requested for a pure procedure (shared text)
file presently being executed.
.El
.Sh SEE ALSO
.Xr chmod 2 ,
.Xr execve 2 ,
.Xr stat 2 ,
.Xr secure_path 3
.Sh STANDARDS
The
.Fn access
function conforms to
.St -p1003.1-90 .
.Fn faccessat
function conforms to
.St -p1003.1-2008 .
This paragraph could be moved to the end of DESCRIPTION if people
don't like having it here.
p Note that .Fn faccessat violates the historic convention that system calls whose names begin with `f' operate on file handles rather than paths. There is no equivalent to .Fn access for checking access properties of an already-opened file. .Sh SECURITY CONSIDERATIONS Because the results of these calls reflect the state of the file system at the time they ran, and the file system can potentially be modified between that time and the time the caller attempts to act on the results, they should .Em never be used for security enforcement.
p Privileged programs that need to restrict their actions to files or directories properly accessible to unprivileged users .Em must do this by assuming or restoring an unprivileged state (see .Xr seteuid 2 ) when performing the pertinent actions. Checking in advance (with .Fn access or any other method) and performing such actions while privileged introduces a race condition that in most cases is easily exploitable by even a naive adversary.
p Even for non-privileged programs, the opportunity for the world to change after the call runs makes .Fn access and .Fn faccessat not very useful. In general only .Dv F_OK should be used, and that too, sparingly. The other checks may occasionally be useful for user interface or diagnostic purposes.
Indexes created Sat Sep 20 22:09:52 GMT 2025