.Dt ACCESS 2
.Os BSD 4
.Sh NAME
-.Nm access
+.Nm access ,
+.Nm faccessat
.Nd check access permissions of a file or pathname
.Sh SYNOPSIS
.Fd #include <unistd.h>
.Ft int
-.Fn access "const char *path" "int mode"
+.Fo access
+.Fa "const char *path"
+.Fa "int amode"
+.Fc
+.Ft int
+.Fn faccessat "int fd" "const char *path" "int mode" "int flag"
.Sh DESCRIPTION
The
.Fn access
file named by
.Fa path
for the access permissions indicated by
-.Fa mode .
+.Fa amode .
The value of
-.Fa mode
+.Fa amode
is the bitwise inclusive OR of the access permissions to be
checked
.Pf ( Dv R_OK
(including the real group ID) are
used in place of the effective ID for verifying permission.
.Pp
+The
+.Fn faccessat
+system call is equivalent to
+.Fn access
+except in the case where
+.Fa path
+specifies a relative path.
+In this case the file whose accessibility is to be determined is
+located relative to the directory associated with the file descriptor
+.Fa fd
+instead of the current working directory.
+If
+.Fn faccessat
+is passed the special value
+.Dv AT_FDCWD
+in the
+.Fa fd
+parameter, the current working directory is used and the behavior is
+identical to a call to
+.Fn access .
+Values for
+.Fa flag
+are constructed by a bitwise-inclusive OR of flags from the following
+list, defined in
+.In fcntl.h :
+.Bl -tag -width indent
+.It Dv AT_EACCESS
+The checks for accessibility are performed using the effective user and group
+IDs instead of the real user and group ID as required in a call to
+.Fn access .
+.El
+.Pp
Even if a process has appropriate privileges and indicates success for
.Dv X_OK ,
the file may not actually have execute permission bits set.
.Sh RETURN VALUES
If
.Fa path
-cannot be found or if any of the desired access modes would
-not be granted, then a -1 value is returned; otherwise
-a 0 value is returned.
+cannot be found
+or if any of the desired access modes would not be granted,
+then a -1 value is returned and the global integer variable
+.Va errno
+is set to indicate the error.
+Otherwise, a 0 value is returned.
.Sh ERRORS
Access to the file is denied if:
.Bl -tag -width Er
-.It Bq Er ENOTDIR
-A component of the path prefix is not a directory.
+.\" ==========
+.It Bq Er EACCES
+Permission bits of the file mode do not permit the requested access,
+or search permission is denied on a component of the path prefix.
+.Pp
+The owner of a file has permission checked
+with respect to the ``owner'' read, write, and execute mode bits,
+members of the file's group other than the owner have permission checked
+with respect to the ``group'' mode bits,
+and all others have permissions checked
+with respect to the ``other'' mode bits.
+.\"
+.\" ==========
+.It Bq Er EFAULT
+.Fa Path
+points outside the process's allocated address space.
+.It Bq Er EINVAL
+An invalid value was specified for
+.Ar amode .
+.\" ==========
+.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
.Dv {NAME_MAX}
characters, or an entire path name exceeded
.Dv {PATH_MAX}
characters.
+.\" ==========
.It Bq Er ENOENT
The named file does not exist.
-.It Bq Er ELOOP
-Too many symbolic links were encountered in translating the pathname.
+.\" ==========
+.It Bq Er ENOTDIR
+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.
-.It Bq Er EACCES
-Permission bits of the file mode do not permit the requested
-access, or search permission is denied on a component of the
-path prefix. The owner of a file has permission checked with
-respect to the ``owner'' read, write, and execute mode bits,
-members of the file's group other than the owner have permission
-checked with respect to the ``group'' mode bits, and all
-others have permissions checked with respect to the ``other''
-mode bits.
-.It Bq Er EFAULT
-.Fa Path
-points outside the process's allocated address space.
-.It Bq Er EIO
-An I/O error occurred while reading from or writing to the file system.
+file that is presently being executed.
+.El
+.Pp
+Also, the
+.Fn faccessat
+system call may fail if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa path
+argument does not specify an absolute path and the
+.Fa fd
+argument is
+neither
+.Dv AT_FDCWD
+nor a valid file descriptor.
.It Bq Er EINVAL
-An invalid value was specified for
-.Ar mode .
+The value of the
+.Fa flag
+argument is not valid.
+.It Bq Er ENOTDIR
+The
+.Fa path
+argument is not an absolute path and
+.Fa fd
+is neither
+.Dv AT_FDCWD
+nor a file descriptor associated with a directory.
.El
.Sh SEE ALSO
.Xr chmod 2 ,
.Fn access
function conforms to
.St -p1003.1-90 .
+The
+.Fn faccessat
+system call is expected to conform to POSIX.1-2008 .
.Sh CAVEAT
-.Fn Access
+.Fn access
is a potential security hole and
should never be used.
projects / apple / xnu.git / blobdiff