[v2,1/5] manual: Document faccessat

  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(-)
  

* 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
  

* 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
  

> >  @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).

Adding docs is fine imho, so OK after reviews...

> 
> Thanks,
> Florian
> 
>