X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/9bccf70c0258c7cac2dcb80011b2a964d884c552..c18c124eaa464aaaa5549e99e5a70fc9cbb50944:/bsd/man/man2/access.2

diff --git a/bsd/man/man2/access.2 b/bsd/man/man2/access.2
index 0d168d3c8..2c89f7a11 100644
--- a/bsd/man/man2/access.2
+++ b/bsd/man/man2/access.2
@@ -37,12 +37,18 @@
 .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
@@ -50,9 +56,9 @@ function checks the accessibility of the
 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
@@ -72,6 +78,38 @@ and the real group access list
 (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.
@@ -82,46 +120,87 @@ and
 .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 ,
@@ -131,7 +210,10 @@ The
 .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.