[v4] manual: Add Descriptor-Relative Access section

  From: Florian Weimer <fw@deneb.enyo.de>

And document the functions openat, openat64, fstatat, fstatat64.
(The safety assessment for fstatat was already obsolete because
current glibc assumes kernel support for the underlying system call.)

---
v4: Use “file name” instead of “pathname”.  Some small fixes. 

 manual/filesys.texi | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 manual/llio.texi    |  28 ++++++++++
 manual/startup.texi |   7 ++-
 3 files changed, 182 insertions(+), 7 deletions(-)
  

Hi Florian,

On 12/4/20 2:25 PM, Florian Weimer wrote:
> From: Florian Weimer <fw@deneb.enyo.de>
> 
> And document the functions openat, openat64, fstatat, fstatat64.
> (The safety assessment for fstatat was already obsolete because
> current glibc assumes kernel support for the underlying system call.)

Many changes that I suggested back in April [1], and which I had the 
impression you fixed [2], seem to have been lost? See a few examples
below. Have you accidentally resent an old version of this text?

Thanks,

Michael


> ---
> v4: Use “file name” instead of “pathname”.  Some small fixes. 
> 
>  manual/filesys.texi | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++--
>  manual/llio.texi    |  28 ++++++++++
>  manual/startup.texi |   7 ++-
>  3 files changed, 182 insertions(+), 7 deletions(-)
> 
> diff --git a/manual/filesys.texi b/manual/filesys.texi
> index 73e630842e..9ee0e17abd 100644
> --- a/manual/filesys.texi
> +++ b/manual/filesys.texi
> @@ -15,6 +15,7 @@ access permissions and modification times.
>  @menu
>  * Working Directory::           This is used to resolve relative
>  				 file names.
> +* Descriptor-Relative Access::  Ways to control file name lookup.
>  * Accessing Directories::       Finding out what files a directory
>  				 contains.
>  * Working with Directory Trees:: Apply actions to all files or a selectable
> @@ -206,6 +207,118 @@ An I/O error occurred.
>  @end table
>  @end deftypefun
>  
> +@node Descriptor-Relative Access
> +@section Descriptor-Relative Access
> +@cindex file name resolution based on descriptors
> +@cindex descriptor-based file name resolution
> +@cindex @code{@dots{}at} functions
> +
> +Many functions that accept file names have @code{@dots{}at} variants
> +which accept a file descriptor and file name argument instead of just a
> +file name argument.  For example, @code{fstatat} is the descriptor-based
> +variant of the @code{fstat} function.  Most of such functions also

s/of such/such/

> +accept an additional flags argument which changes the behavior of the
> +file name lookup based on the passed @code{AT_@dots{}} flags.
> +
> +The file descriptor used by these @code{@dots{}at} functions has the
> +following uses:

'used...uses" reads a little clumsily. 

> +
> +@itemize @bullet
> +@item
> +It can be a file descriptor referring to a directory.  Such a descriptor
> +can be created explicitly using the @code{open} function and the
> +@code{O_RDONLY} file access mode, with or without the @code{O_DIRECTORY}
> +flag.  @xref{Opening and Closing Files}.  Or it can be created implicity
> +by @code{opendir} and retrieved using the @code{dirfd} function.
> +@xref{Opening a Directory}.
> +
> +If a directory descriptor is used with one of the @code{@dots{}at}
> +functions, a relative file name argument is resolved relatively to that
> +directory, just as if the directory were the current working directory.
> +Absolute file name arguments (starting with @samp{/}) are resolved
> +against the file system root, and the descriptor argument is effectively
> +ignored.
> +
> +This means that file name lookup is not constrained to the directory of
> +the descriptor.  For example, it is possible to access a file
> +@file{example} in the descriptor's parent directory using a file name
> +argument @code{"../example"}, or in the root directory using
> +@code{"/example"}.
> +
> +If the file descriptor refers to a directory, the empty string @code{""}
> +is not a valid file name argument.
> +
> +@item
> +@vindex @code{AT_FDCWD}
> +The special value @code{AT_FDCWD}.  This means that the current working
> +directory is used for the lookup if the file name is a relative.  For
> +@code{@dots{}at} functions with an @code{AT_@dots{}} flags argument,
> +this provides a shortcut to use those flags with regular (not
> +descriptor-based) file name lookups.
> +
> +If @code{AT_FDCWD} is used, the empty string @code{""} is not a valid
> +file name argument.
> +
> +@item
> +An arbitrary file descriptor, along with an empty string @code{""} as
> +the file name argument, and the @code{AT_EMPTY_PATH} flag.  In this
> +case, the operation uses the file descriptor directly, without further
> +file name resolution.  On Linux, this allows operations on descriptors
> +opened with the @code{O_PATH} flag.  For regular descriptors (opened
> +without @code{O_PATH}), the same functionality is also available through
> +the plain descriptor-based functions (for example, @code{fstat} instead
> +of @code{fstatat}).
> +
> +This is a GNU extension.
> +@end itemize
> +
> +@cindex file name resolution flags
> +@cindex @code{AT_*} file name resolution flags
> +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.
> +
> +@vtable @code
> +@item AT_EMPTY_PATH
> +This flag is used with an empty file name @code{""} and a descriptor
> +which does not necessarily refer to a directory.  It is most useful with
> +@code{O_PATH} descriptors, as described above.  This flag is a GNU
> +extension.
> +
> +@item AT_NO_AUTOMOUNT
> +If the effective final path component refers to a potential file system
> +mount point controlled by an auto-mounting service, the operation does
> +not trigger auto-mounting and refers to the unmounted mount point
> +instead.  @xref{Mount-Unmount-Remount}.  If a file system has already
> +been mounted at the effective final path component, the operation
> +applies to the file or directory in the mounted file system, not the
> +underlying file system that was mounted over.  This flag is a GNU
> +extension.
> +
> +@item AT_SYMLINK_FOLLOW
> +If the effective final path component is a symbolic link, the
> +operation follows the symbolic link and operates on its target.  (For
> +most functions, this is the default behavior.)
> +
> +@item AT_SYMLINK_NOFOLLOW
> +If the effective final path component is a symbolic link, the
> +operation operates on the symbolic link, without following it.  The
> +difference in behavior enabled by this flag is similar to the difference
> +between the @code{lstat} and @code{stat} functions, or the behavior
> +activated by the @code{O_NOFOLLOW} argument to the @code{open} function.
> +Even with the @code{AT_SYMLINK_NOFOLLOW} flag present, symbolic links in
> +a non-final position of the path are still followed.

s/position/component/

> +@end vtable
> +
> +There is no relationship between these flags and the type argument to

Formatting for 'type'?

> +the @code{getauxval} function (with @code{AT_@dots{}} constants defined
> +in @file{elf.h}).
>  
>  @node Accessing Directories
>  @section Accessing Directories
> @@ -1250,10 +1363,11 @@ A hardware error occurred while trying to read or write the to filesystem.
>  
>  The @code{linkat} function is analogous to the @code{link} function,
>  except that it identifies its source and target using a combination of a
> -file descriptor (referring to a directory) and a pathname.  If a
> -pathnames is not absolute, it is resolved relative to the corresponding
> -file descriptor.  The special file descriptor @code{AT_FDCWD} denotes

s/special file descriptor/special value/
or
s/special file descriptor/special file descriptor value/

> -the current directory.
> +file descriptor (referring to a directory) and a file name.
> +@xref{Descriptor-Relative Access}.  For @code{linkat}, if a file name is
> +not absolute, it is resolved relative to the corresponding file
> +descriptor.  As usual, the special file descriptor @code{AT_FDCWD}
> +denotes the current directory.
>  
>  The @var{flags} argument is a combination of the following flags:
>  
> @@ -2095,6 +2209,38 @@ replaces the interface for small files on 32-bit machines.
>  @c available.
>  @c @safety{@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
>  
> +
> +@deftypefun int fstatat (int @var{filedes}, const char *@var{filename}, struct stat *@var{buf}, int @var{flags})
> +@standards{POSIX.1, sys/stat.h}
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +This function is a descriptor-relative version of the @code{fstat}
> +function above.  @xref{Descriptor-Relative Access}.  The @var{flags}
> +argument can contain a combination of the flags @code{AT_EMPTY_PATH},
> +@code{AT_NO_AUTOMOUNT}, @code{AT_SYMLINK_NOFOLLOW}.
> +
> +Compared to @code{fstat}, 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
> +@end deftypefun
> +
> +@deftypefun int fstatat64 (int @var{filedes}, const char *@var{filename}, struct stat64 *@var{buf}, int @var{flags})
> +@standards{GNU, sys/stat.h}
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +This function is the large-file variant of @code{fstatat}, similar to
> +how @code{fstat64} is the variant of @code{fstat}.
> +@end deftypefun
> +
>  @deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf})
>  @standards{BSD, sys/stat.h}
>  @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> diff --git a/manual/llio.texi b/manual/llio.texi
> index c0a53e1a6e..aae0340755 100644
> --- a/manual/llio.texi
> +++ b/manual/llio.texi
> @@ -180,6 +180,34 @@ new, extended API using 64 bit file sizes and offsets transparently
>  replaces the old API.
>  @end deftypefun
>  
> +@deftypefun int openat (int @var{filedes}, const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
> +@standards{POSIX.1, fcntl.h}
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
> +This function is the descriptor-relative variant of the @code{open}
> +function.  @xref{Descriptor-Relative Access}.
> +
> +Note that the @var{flags} argument of @code{openat} does not accept
> +@code{AT_@dots{}} flags, only the flags described for the @code{open}
> +function above.
> +
> +The @code{openat} function can fail for additional reasons:
> +
> +@table @code
> +@item EBADF
> +The @var{filedes} argument is not a valid file descriptor.
> +
> +@item ENOTDIR
> +The descriptor @var{filedes} is not associated with a directory, and
> +@var{filename} is a relative file name.
> +@end table
> +@end deftypefun
> +
> +@deftypefun int openat64 (int @var{filedes}, const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
> +@standards{GNU, fcntl.h}
> +The large-file variant of the @code{openat}, similar to how
> +@code{open64} is the large-file variant of @code{open}.
> +@end deftypefun
> +
>  @deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode})
>  @standards{POSIX.1, fcntl.h}
>  @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
> diff --git a/manual/startup.texi b/manual/startup.texi
> index 9bf24123f5..daedd4ff79 100644
> --- a/manual/startup.texi
> +++ b/manual/startup.texi
> @@ -664,9 +664,10 @@ basis there may be information that is not available any other way.
>  @c Reads from hwcap or iterates over constant auxv.
>  This function is used to inquire about the entries in the auxiliary
>  vector.  The @var{type} argument should be one of the @samp{AT_} symbols
> -defined in @file{elf.h}.  If a matching entry is found, the value is
> -returned; if the entry is not found, zero is returned and @code{errno} is
> -set to @code{ENOENT}.
> +defined in @file{elf.h}.  (There is no relationship between these types
> +and the file name lookup flags in @file{fcntl.h}.)  If a matching entry
> +is found, the value is returned; if the entry is not found, zero is
> +returned and @code{errno} is set to @code{ENOENT}.
>  @end deftypefun
>  
>  For some platforms, the key @code{AT_HWCAP} is the easiest way to inquire
> 

[1] https://sourceware.org/pipermail/libc-alpha/2020-April/113426.html
[2] https://sourceware.org/pipermail/libc-alpha/2020-May/113545.html
  

* Michael Kerrisk:

> Hi Florian,
>
> On 12/4/20 2:25 PM, Florian Weimer wrote:
>> From: Florian Weimer <fw@deneb.enyo.de>
>> 
>> And document the functions openat, openat64, fstatat, fstatat64.
>> (The safety assessment for fstatat was already obsolete because
>> current glibc assumes kernel support for the underlying system call.)
>
> Many changes that I suggested back in April [1], and which I had the 
> impression you fixed [2], seem to have been lost? See a few examples
> below. Have you accidentally resent an old version of this text?

Huh, yes, that's possible.  I had some trouble finding the right version
of the patch.  I may well have picked the wrong one, sorry.

Florian