[v7] manual: Add Descriptor-Relative Access section
Checks
Context |
Check |
Description |
redhat-pt-bot/TryBot-apply_patch |
success
|
Patch applied to master at the time it was sent
|
redhat-pt-bot/TryBot-32bit |
success
|
Build for i686
|
linaro-tcwg-bot/tcwg_glibc_build--master-arm |
success
|
Build passed
|
linaro-tcwg-bot/tcwg_glibc_build--master-aarch64 |
success
|
Build passed
|
linaro-tcwg-bot/tcwg_glibc_check--master-arm |
success
|
Test passed
|
linaro-tcwg-bot/tcwg_glibc_check--master-aarch64 |
success
|
Test passed
|
Commit Message
Reference this new section from the O_PATH documentation.
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.)
---
v7: Address Adhemerval's review comments.
manual/filesys.texi | 196 ++++++++++++++++++++++++++++++++++++++++++++++++++--
manual/llio.texi | 41 ++++++++++-
manual/startup.texi | 8 ++-
3 files changed, 235 insertions(+), 10 deletions(-)
base-commit: d7eca2714f0da98894baa15e4c4735297ecd738d
Comments
On 07/08/24 09:57, Florian Weimer wrote:
> Reference this new section from the O_PATH documentation.
>
> 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.)
LGTM, only a small type below.
Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
>
> ---
> v7: Address Adhemerval's review comments.
> manual/filesys.texi | 196 ++++++++++++++++++++++++++++++++++++++++++++++++++--
> manual/llio.texi | 41 ++++++++++-
> manual/startup.texi | 8 ++-
> 3 files changed, 235 insertions(+), 10 deletions(-)
>
> diff --git a/manual/filesys.texi b/manual/filesys.texi
> index 47d929744e..f033a3d543 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,151 @@ 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 a 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 such
> +functions also accept an additional flags argument which changes the
> +behavior of the file name lookup based on the passed @code{AT_@dots{}}
> +flags.
> +
> +There are several reasons to use descriptor-relative access:
> +
> +@itemize @bullet
> +@item
> +The working directory is a process-wide resource, so individual threads
> +cannot change it without affecting other threads in the process.
> +Explicitly specifying the directory against which relative paths are
> +resolved can be a thread-safe alternative to changing the working
> +directory.
> +
> +@item
> +If a progrem wishes to access a directory tree which is being modified
s/progrem/program
> +concurrently, perhaps even by a different user on the system, the
> +program must avoid looking up file names with multiple components, in
> +order to detect symbolic links, using the @code{O_NOFOLLOW} flag
> +(@pxref{Open-time Flags}) or the @code{AT_SYMLINK_FOLLOW} flag
> +(described below). Without directory-relative access, it is necessary
> +to use the @code{fchdir} function to change the working directory
> +(@pxref{Working Directory}), which is not thread-safe.
> +
> +@item
> +Listing directory contents using the @code{readdir} or @code{readdir64}
I am not sure if it is usual to reference the LFS names, but it should
ok.
> +functions (@pxref{Reading/Closing Directory}) does not provide full file
> +name paths. Using @code{@dots{}at} functions, it is possible to use the
> +file names directly, without having to construct such full paths.
> +
> +@item
> +Additional flags available with some of the @code{@dots{}at} functions
> +provide access to functionality which is not available otherwise.
> +@end itemize
> +
> +The file descriptor used by these @code{@dots{}at} functions has the
> +following uses:
> +
> +@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
> +implicitly 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 relative to
> +directory referred to by the file descriptor, just as if that 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. It is possible to use @code{"."} to
> +refer to the directory itself. Also see @code{AT_EMPTY_PATH} below.
> +
> +@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 component of the file name are still followed.
> +@end vtable
> +
> +@strong{Note:} There is no relationship between these flags and the type
> +argument to the @code{getauxval} function (with @code{AT_@dots{}}
> +constants defined in @file{elf.h}). @xref{Auxiliary Vector}.
>
> @node Accessing Directories
> @section Accessing Directories
> @@ -1250,10 +1396,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
> -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 value @code{AT_FDCWD} denotes the
> +current directory.
>
> The @var{flags} argument is a combination of the following flags:
>
> @@ -2091,9 +2238,44 @@ function is available under the name @code{fstat} and so transparently
> replaces the interface for small files on 32-bit machines.
> @end deftypefun
>
> -@c fstatat will call alloca and snprintf if the syscall is not
> -@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
> +
> +When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
> +function is in fact @code{fstatat64} since the LFS interface transparently
> +replaces the normal implementation.
> +@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}.
> +
> +When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
> +function is available under the name @code{fstatat} and so transparently
> +replaces the interface for small files on 32-bit machines.
> +@end deftypefun
>
> @deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf})
> @standards{BSD, sys/stat.h}
> diff --git a/manual/llio.texi b/manual/llio.texi
> index ea84196abd..a035c3e20f 100644
> --- a/manual/llio.texi
> +++ b/manual/llio.texi
> @@ -181,6 +181,43 @@ 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
> +
> +When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
> +function is in fact @code{openat64} since the LFS interface transparently
> +replaces the normal implementation.
> +@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}.
> +
> +When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
> +function is actually available under the name @code{openat}. I.e., the
> +new, extended API using 64 bit file sizes and offsets transparently
> +replaces the old API.
> +@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{}}}
> @@ -3807,7 +3844,9 @@ contains it is still needed), and permissions are checked when the
> descriptor is used later on.
>
> For example, such descriptors can be used with the @code{fexecve}
> -function (@pxref{Executing a File}).
> +function (@pxref{Executing a File}). Other applications involve the
> +@samp{*at} function variants, along with the @code{AT_EMPTY_PATH} flag.
> +@xref{Descriptor-Relative Access}.
>
> This access mode is specific to Linux. On @gnuhurdsystems{}, it is
> possible to use @code{O_EXEC} explicitly, or specify no access modes
> diff --git a/manual/startup.texi b/manual/startup.texi
> index 747beed4d9..8ac3b97eed 100644
> --- a/manual/startup.texi
> +++ b/manual/startup.texi
> @@ -664,8 +664,12 @@ basis there may be information that is not available any other way.
> 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}.
> +returned; if the entry is not found, zero is returned and @code{errno}
> +is set to @code{ENOENT}.
> +
> +@strong{Note:} There is no relationship between the @samp{AT_} contants
> +defined in @file{elf.h} and the file name lookup flags in
> +@file{fcntl.h}. @xref{Descriptor-Relative Access}.
> @end deftypefun
>
> For some platforms, the key @code{AT_HWCAP} is the easiest way to inquire
>
> base-commit: d7eca2714f0da98894baa15e4c4735297ecd738d
>
@@ -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,151 @@ 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 a 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 such
+functions also accept an additional flags argument which changes the
+behavior of the file name lookup based on the passed @code{AT_@dots{}}
+flags.
+
+There are several reasons to use descriptor-relative access:
+
+@itemize @bullet
+@item
+The working directory is a process-wide resource, so individual threads
+cannot change it without affecting other threads in the process.
+Explicitly specifying the directory against which relative paths are
+resolved can be a thread-safe alternative to changing the working
+directory.
+
+@item
+If a progrem wishes to access a directory tree which is being modified
+concurrently, perhaps even by a different user on the system, the
+program must avoid looking up file names with multiple components, in
+order to detect symbolic links, using the @code{O_NOFOLLOW} flag
+(@pxref{Open-time Flags}) or the @code{AT_SYMLINK_FOLLOW} flag
+(described below). Without directory-relative access, it is necessary
+to use the @code{fchdir} function to change the working directory
+(@pxref{Working Directory}), which is not thread-safe.
+
+@item
+Listing directory contents using the @code{readdir} or @code{readdir64}
+functions (@pxref{Reading/Closing Directory}) does not provide full file
+name paths. Using @code{@dots{}at} functions, it is possible to use the
+file names directly, without having to construct such full paths.
+
+@item
+Additional flags available with some of the @code{@dots{}at} functions
+provide access to functionality which is not available otherwise.
+@end itemize
+
+The file descriptor used by these @code{@dots{}at} functions has the
+following uses:
+
+@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
+implicitly 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 relative to
+directory referred to by the file descriptor, just as if that 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. It is possible to use @code{"."} to
+refer to the directory itself. Also see @code{AT_EMPTY_PATH} below.
+
+@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 component of the file name are still followed.
+@end vtable
+
+@strong{Note:} There is no relationship between these flags and the type
+argument to the @code{getauxval} function (with @code{AT_@dots{}}
+constants defined in @file{elf.h}). @xref{Auxiliary Vector}.
@node Accessing Directories
@section Accessing Directories
@@ -1250,10 +1396,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
-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 value @code{AT_FDCWD} denotes the
+current directory.
The @var{flags} argument is a combination of the following flags:
@@ -2091,9 +2238,44 @@ function is available under the name @code{fstat} and so transparently
replaces the interface for small files on 32-bit machines.
@end deftypefun
-@c fstatat will call alloca and snprintf if the syscall is not
-@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
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{fstatat64} since the LFS interface transparently
+replaces the normal implementation.
+@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}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{fstatat} and so transparently
+replaces the interface for small files on 32-bit machines.
+@end deftypefun
@deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf})
@standards{BSD, sys/stat.h}
@@ -181,6 +181,43 @@ 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
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{openat64} since the LFS interface transparently
+replaces the normal implementation.
+@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}.
+
+When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
+function is actually available under the name @code{openat}. I.e., the
+new, extended API using 64 bit file sizes and offsets transparently
+replaces the old API.
+@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{}}}
@@ -3807,7 +3844,9 @@ contains it is still needed), and permissions are checked when the
descriptor is used later on.
For example, such descriptors can be used with the @code{fexecve}
-function (@pxref{Executing a File}).
+function (@pxref{Executing a File}). Other applications involve the
+@samp{*at} function variants, along with the @code{AT_EMPTY_PATH} flag.
+@xref{Descriptor-Relative Access}.
This access mode is specific to Linux. On @gnuhurdsystems{}, it is
possible to use @code{O_EXEC} explicitly, or specify no access modes
@@ -664,8 +664,12 @@ basis there may be information that is not available any other way.
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}.
+returned; if the entry is not found, zero is returned and @code{errno}
+is set to @code{ENOENT}.
+
+@strong{Note:} There is no relationship between the @samp{AT_} contants
+defined in @file{elf.h} and the file name lookup flags in
+@file{fcntl.h}. @xref{Descriptor-Relative Access}.
@end deftypefun
For some platforms, the key @code{AT_HWCAP} is the easiest way to inquire