[PATCH v2 1/5] manual: Document faccessat

[Arjun Shankar]

This commit adds a note that the Descriptor-Relative Access section does
not list all flags, then documents `faccessat' along with the AT_EACCESS
flag specific to this function.
---
 manual/filesys.texi | 53 +++++++++++++++++++++++++++++++++++++++------
 1 file changed, 46 insertions(+), 7 deletions(-)

diff --git a/manual/filesys.texi b/manual/filesys.texi
index aabb68385b..407c26bd76 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -310,12 +310,17 @@ This is a GNU extension.
 The flags argument in @code{@dots{}at} functions can be a combination of
 the following flags, defined in @file{fcntl.h}.  Not all such functions
 support all flags, and some (such as @code{openat}) do not accept a
-flags argument at all.
-
-In the flag descriptions below, the @dfn{effective final path component}
-refers to the final component (basename) of the full path constructed
-from the descriptor and file name arguments, using file name lookup, as
-described above.
+flags argument at all.  Although the flags specific to each function have
+distinct values from each other, some flags (relevant to different
+functions) might share the same value and therefore are not guaranteed to
+have unique values.
+
+A non-exhaustive list of common flags and their descriptions follows.  Flags
+specific to a function are described alongside the function itself.  In
+these flag descriptions, the @dfn{effective final path component} refers to
+the final component (basename) of the full path constructed from the
+descriptor and file name arguments, using file name lookup, as described
+above.
 
 @vtable @code
 @item AT_EMPTY_PATH
@@ -2980,6 +2985,41 @@ Flag meaning test for execute/search permission.
 Flag meaning test for existence of the file.
 @end deftypevr
 
+@deftypefun int faccessat (int @var{filedes}, const char *@var{filename}, int @var{how}, int @var{flags})
+@standards{POSIX.1-2008, unistd.h}
+@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default
+@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+This function is a descriptor-relative version of the @code{access}
+function above.  @xref{Descriptor-Relative Access}.  The @var{flags}
+argument can contain a combination of the flags @code{AT_EACCESS} described
+below, @code{AT_EMPTY_PATH}, and @code{AT_SYMLINK_NOFOLLOW}.
+
+@vtable @code
+@item AT_EACCESS
+This flag when passed to the @code{faccessat} function causes it to perform
+access checks using effective user and group IDs instead of real IDs, which
+is the default and matches the @code{access} function.
+@end vtable
+
+Compared to @code{access}, the following additional error conditions can
+occur:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item EINVAL
+The @var{flags} argument is not valid for this function.
+
+@item ENOTDIR
+The descriptor @var{filedes} is not associated with a directory, and
+@var{filename} is a relative file name.
+@end table
+
+This function may not work correctly on older kernels missing the
+@code{faccessat2} system call.
+@end deftypefun
+
 @node File Times
 @subsection File Times
 
@@ -3760,7 +3800,6 @@ creation always works like @code{open} with @code{O_EXCL}.
 The @code{mkdtemp} function comes from OpenBSD.
 
 @c FIXME these are undocumented:
-@c faccessat
 @c fchmodat
 @c fchownat
 @c futimesat
-- 
2.47.1