[PATCH v2 1/5] manual: Document faccessat

[Florian Weimer]

* 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

This looks okay to me.

Reviewed-by: Florian Weimer <fweimer@redhat.com>

Note that we are currently in freeze, so this needs RM approval
(presumably after the full series has been reviewed).

Thanks,
Florian