.\"	$NetBSD: access.2,v 1.33 2017/01/10 06:28:46 abhinav Exp $
.\"
.\" 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
.In unistd.h
.Ft int
.Fn access "const char *path" "int mode"
.In 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.
.Pp
The form of access to check is specified by the bitwise or of the
following values for
.Fa mode :
.Bl -tag -width W_OK
.It Dv R_OK
Check for read permission.
.It Dv W_OK
Check for write permission.
.It Dv X_OK
Check for execute/search permission.
.It Dv F_OK
Check only for existence.
.El
.Pp
All components of the pathname
.Fa path
are checked for access permissions as well.
.Pp
.\" 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.
.Pp
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.
.Pp
The
.Fa flags
argument to
.Fn faccessat
can specify the following optional behavior:
.Bl -tag -width AT_SYMLINK_NOFOLLOW
.It AT_EACCESS
Use the effective user and group IDs instead of the real user and
group IDs for checking permission.
See discussion below.
.It AT_SYMLINK_NOFOLLOW
Do not follow a symbolic link encountered as the last component in
.Fa path .
.El
.Pp
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.)
.Pp
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:
.Bl -tag -width Er
.It 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.
.It 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 .
.It Bq Er EFAULT
.Fa path
points outside the process's allocated address space.
.It Bq Er EINVAL
The
.Fa mode
or
.Fa flags
argument contained an invalid value.
.It Bq Er EIO
An I/O error occurred while reading from or writing to the file system.
.It Bq Er ELOOP
Too many symbolic links were encountered in translating the pathname.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded
.Brq Dv NAME_MAX
characters, or an entire path name exceeded
.Brq Dv PATH_MAX
characters.
.It Bq Er ENOENT
The named file does not exist.
.It Bq Er ENOTDIR
The file descriptor
.Fa fd
does not name a directory, or a component of the path prefix is not a
directory.
.It Bq Er EROFS
Write access is requested for a file on a read-only file system.
.It 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.
.Pp
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.
.Pp
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.
.Pp
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.