[PATCH v2 1/5] manual: Document faccessat

[Florian Weimer]

* 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.

Sorry, missed that this should mention AT_FDCWD.

Maybe we should decoument this and EINVAL in the general section under
the Descriptor-Relative Access node?

>> +@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