From c6e49bb8c78b4c4e2cdd1f58c3a246cc1faf4e84 Mon Sep 17 00:00:00 2001 From: Arjun Shankar Date: Thu, 5 Jun 2025 19:14:40 +0200 Subject: [PATCH] manual: Document several *at file system interface functions (RHEL-50546) Resolves: RHEL-50546 --- glibc-RHEL-50546-1.patch | 67 +++++++++++++++++++++++++++ glibc-RHEL-50546-2.patch | 50 +++++++++++++++++++++ glibc-RHEL-50546-3.patch | 38 ++++++++++++++++ glibc-RHEL-50546-4.patch | 38 ++++++++++++++++ glibc-RHEL-50546-5.patch | 51 +++++++++++++++++++++ glibc-RHEL-50546-6.patch | 97 ++++++++++++++++++++++++++++++++++++++++ glibc.spec | 11 ++++- 7 files changed, 351 insertions(+), 1 deletion(-) create mode 100644 glibc-RHEL-50546-1.patch create mode 100644 glibc-RHEL-50546-2.patch create mode 100644 glibc-RHEL-50546-3.patch create mode 100644 glibc-RHEL-50546-4.patch create mode 100644 glibc-RHEL-50546-5.patch create mode 100644 glibc-RHEL-50546-6.patch diff --git a/glibc-RHEL-50546-1.patch b/glibc-RHEL-50546-1.patch new file mode 100644 index 0000000..2f53691 --- /dev/null +++ b/glibc-RHEL-50546-1.patch @@ -0,0 +1,67 @@ +commit 3b21166c4d34ee032093bcf599ffac42ad8a4371 +Author: Arjun Shankar +Date: Wed Jun 4 13:08:53 2025 +0200 + + manual: Expand Descriptor-Relative Access section + + Improve the clarity of the paragraphs describing common flags and add a + list of common error conditions for descriptor-relative functions. + Reviewed-by: Florian Weimer + +diff --git a/manual/filesys.texi b/manual/filesys.texi +index 450d175e614d8834..28d38f23fc58c51f 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 +@@ -353,6 +358,28 @@ a non-final component of the file name are still followed. + argument to the @code{getauxval} function (with @code{AT_@dots{}} + constants defined in @file{elf.h}). @xref{Auxiliary Vector}. + ++@cindex common errors in descriptor-relative functions ++@cindex common errors in @code{@dots{}at} functions ++ ++The @code{@dots{}at} functions have some common error conditions due to the ++nature of descriptor-relative access. A list of common errors and their ++descriptions follows. Errors specific to a function are described alongside ++the function itself. ++ ++@table @code ++@item EBADF ++The file name argument is a relative path but the descriptor argument ++is neither @code{AT_FDCWD} nor a valid file descriptor. ++ ++@item EINVAL ++If the function accepts a @var{flags} argument, the flag combination passed ++is not valid for the function. ++ ++@item ENOTDIR ++The file name argument is a relative file name but the descriptor ++argument is associated with a file that is not a directory. ++@end table ++ + @node Accessing Directories + @section Accessing Directories + @cindex accessing directories diff --git a/glibc-RHEL-50546-2.patch b/glibc-RHEL-50546-2.patch new file mode 100644 index 0000000..1fc1bb8 --- /dev/null +++ b/glibc-RHEL-50546-2.patch @@ -0,0 +1,50 @@ +commit 941157dbcdf1c410960bde991206bfb6d9bb292f +Author: Arjun Shankar +Date: Wed Jun 4 13:08:54 2025 +0200 + + manual: Document faccessat + + Reviewed-by: Florian Weimer + +diff --git a/manual/filesys.texi b/manual/filesys.texi +index 28d38f23fc58c51f..17c15b54037e719d 100644 +--- a/manual/filesys.texi ++++ b/manual/filesys.texi +@@ -3069,6 +3069,29 @@ 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}, some additional error conditions can occur. ++@xref{Descriptor-Relative Access}. ++ ++This function may not work correctly on older kernels missing the ++@code{faccessat2} system call. ++@end deftypefun ++ + @node File Times + @subsection File Times + +@@ -3849,7 +3872,6 @@ creation always works like @code{open} with @code{O_EXCL}. + The @code{mkdtemp} function comes from OpenBSD. + + @c FIXME these are undocumented: +-@c faccessat + @c fchmodat + @c fchownat + @c futimesat diff --git a/glibc-RHEL-50546-3.patch b/glibc-RHEL-50546-3.patch new file mode 100644 index 0000000..cd96eb5 --- /dev/null +++ b/glibc-RHEL-50546-3.patch @@ -0,0 +1,38 @@ +commit 49766eb1a5b93d093bd0fada55ca7a42dfdb10d6 +Author: Arjun Shankar +Date: Wed Jun 4 13:08:55 2025 +0200 + + manual: Document mkdirat + + Reviewed-by: Florian Weimer + +diff --git a/manual/filesys.texi b/manual/filesys.texi +index 17c15b54037e719d..d8f362f3beda9b28 100644 +--- a/manual/filesys.texi ++++ b/manual/filesys.texi +@@ -1964,6 +1964,17 @@ To use this function, your program should include the header file + @pindex sys/stat.h + @end deftypefun + ++@deftypefun int mkdirat (int @var{filedes}, const char *@var{filename}, mode_t @var{mode}) ++@standards{POSIX.1-2008, sys/stat.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{mkdir} ++function above. @xref{Descriptor-Relative Access}. ++ ++Compared to @code{mkdir}, some additional error conditions can occur. ++@xref{Descriptor-Relative Access}. ++@end deftypefun ++ + @node File Attributes + @section File Attributes + +@@ -3877,7 +3888,6 @@ The @code{mkdtemp} function comes from OpenBSD. + @c futimesat + @c fstatat (there's a commented-out safety assessment for this one) + @c statx +-@c mkdirat + @c mkfifoat + @c name_to_handle_at + @c openat diff --git a/glibc-RHEL-50546-4.patch b/glibc-RHEL-50546-4.patch new file mode 100644 index 0000000..6fc1c7b --- /dev/null +++ b/glibc-RHEL-50546-4.patch @@ -0,0 +1,38 @@ +commit 60f86c9cd062882cbeb04b2944c3dfb7457ee5c5 +Author: Arjun Shankar +Date: Wed Jun 4 13:08:56 2025 +0200 + + manual: Document renameat + + Reviewed-by: Florian Weimer + +diff --git a/manual/filesys.texi b/manual/filesys.texi +index d8f362f3beda9b28..8a173c562fa71f83 100644 +--- a/manual/filesys.texi ++++ b/manual/filesys.texi +@@ -1910,6 +1910,17 @@ file systems. + @end table + @end deftypefun + ++@deftypefun int renameat (int @var{oldfiledes}, const char *@var{oldname}, int @var{newfiledes}, const char *@var{newname}) ++@standards{POSIX.1-2008, stdio.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{rename} ++function above. @xref{Descriptor-Relative Access}. ++ ++Compared to @code{rename}, some additional error conditions can occur. ++@xref{Descriptor-Relative Access}. ++@end deftypefun ++ + @node Creating Directories + @section Creating Directories + @cindex creating a directory +@@ -3893,7 +3904,6 @@ The @code{mkdtemp} function comes from OpenBSD. + @c openat + @c open_by_handle_at + @c readlinkat +-@c renameat + @c renameat2 + @c scandirat + @c symlinkat diff --git a/glibc-RHEL-50546-5.patch b/glibc-RHEL-50546-5.patch new file mode 100644 index 0000000..cf770e4 --- /dev/null +++ b/glibc-RHEL-50546-5.patch @@ -0,0 +1,51 @@ +commit 75b725717ff23d0ae38fc7f4a0361cb1bdffbe2e +Author: Arjun Shankar +Date: Wed Jun 4 13:08:57 2025 +0200 + + manual: Document unlinkat + + Reviewed-by: Florian Weimer + +diff --git a/manual/filesys.texi b/manual/filesys.texi +index 8a173c562fa71f83..396d68c32925c501 100644 +--- a/manual/filesys.texi ++++ b/manual/filesys.texi +@@ -1779,6 +1779,31 @@ file system and can't be modified. + @end table + @end deftypefun + ++@deftypefun int unlinkat (int @var{filedes}, const char *@var{filename}, 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{unlink} ++function above. @xref{Descriptor-Relative Access}. The @var{flags} ++argument may either be @code{0} or contain the flag @code{AT_REMOVEDIR}: ++ ++@table @code ++@item AT_REMOVEDIR ++This flag causes @code{unlinkat} to perform an @code{rmdir} operation on ++@code{filename} instead of performing the equivalent of @code{unlink}. ++@end table ++ ++Compared to @code{unlink}, some additional error conditions can occur due to ++descriptor-relative access. @xref{Descriptor-Relative Access}. In ++addition to this, the following other errors can also occur: ++ ++@table @code ++@item EISDIR ++The effective final path derived from @var{filename} and @var{filedes} is a ++directory but @code{AT_REMOVEDIR} was not passed in @code{flags}. ++@end table ++@end deftypefun ++ + @deftypefun int rmdir (const char *@var{filename}) + @standards{POSIX.1, unistd.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@@ -3907,6 +3932,5 @@ The @code{mkdtemp} function comes from OpenBSD. + @c renameat2 + @c scandirat + @c symlinkat +-@c unlinkat + @c utimensat + @c mknodat diff --git a/glibc-RHEL-50546-6.patch b/glibc-RHEL-50546-6.patch new file mode 100644 index 0000000..fa83a4c --- /dev/null +++ b/glibc-RHEL-50546-6.patch @@ -0,0 +1,97 @@ +commit 25f1d945766a3a757d9b54eb48fe7c3c48c0f791 +Author: Arjun Shankar +Date: Wed Jun 4 13:08:58 2025 +0200 + + manual: Document futimens and utimensat + + Document futimens and utimensat. Also document the EINVAL error + condition for futimes. It is inherited by futimens and utimensat as + well. + Reviewed-by: Florian Weimer + +diff --git a/manual/filesys.texi b/manual/filesys.texi +index 396d68c32925c501..f21f21804251e480 100644 +--- a/manual/filesys.texi ++++ b/manual/filesys.texi +@@ -3307,6 +3307,10 @@ permission for the file, or be a privileged user. + @item EBADF + The @var{filedes} argument is not a valid file descriptor. + ++@item EINVAL ++At least one of the fields in the @code{tvp} array passed has an invalid ++value. ++ + @item EPERM + If the @var{times} argument is not a null pointer, you must either be + the owner of the file or be a privileged user. +@@ -3316,6 +3320,64 @@ The file lives on a read-only file system. + @end table + @end deftypefun + ++@deftypefun int futimens (int @var{filedes}, const struct timespec @var{tsp}@t{[2]}) ++@standards{POSIX.1-2008, sys/stat.h} ++@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default ++@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} ++This function is like @code{futimes}, except that it sets the file access ++and modification timestamps with nanosecond precision. The argument ++@code{tsp} is used similarly to @code{futimes}' @code{tvp}, but has a ++@code{const struct timespec} type that can express calendar time with ++nanosecond precision. @xref{Time Types}. ++@end deftypefun ++ ++@deftypefun int utimensat (int @var{filedes}, const char *@var{filename}, const struct timespec @var{tsp}@t{[2]}, int @var{flags}) ++@standards{POSIX.1-2008, sys/stat.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{futimens} ++function above. @xref{Descriptor-Relative Access}. The @var{flags} ++argument can contain a combination of the flags @code{AT_EMPTY_PATH}, and ++@code{AT_SYMLINK_NOFOLLOW}. The call: ++ ++@smallexample ++futimens (@var{filedes}, @var{tsp}) ++@end smallexample ++ ++is equivalent to: ++ ++@smallexample ++utimensat (@var{filedes}, @code{NULL}, @var{tsp}, 0) ++@end smallexample ++ ++Compared to @code{futimens}, some additional error conditions can occur due ++to descriptor-relative access. @xref{Descriptor-Relative Access}. In ++addition to this, the following other errors can also occur: ++ ++@table @code ++@item EINVAL ++The @var{filename} argument is NULL, @var{filedes} is not @code{AT_FDCWD}, ++and @var{flags} is not @code{0}. ++ ++@item ELOOP ++There are too many levels of indirection. This can be the result of ++circular symbolic links to directories. ++ ++@item ENAMETOOLONG ++The resulting path is too long. This error only occurs on systems which ++have a limit on the file name length. ++ ++@item ENOENT ++The @var{filename} argument is an empty string and @var{flags} does not ++contain @code{AT_EMPTY_PATH}, or @var{filename} does not refer to an ++existing file. ++ ++@item ESRCH ++Search permission was denied for one of the prefix components of the the ++@var{filename} argument. ++@end table ++@end deftypefun ++ + @node File Size + @subsection File Size + +@@ -3932,5 +3994,4 @@ The @code{mkdtemp} function comes from OpenBSD. + @c renameat2 + @c scandirat + @c symlinkat +-@c utimensat + @c mknodat diff --git a/glibc.spec b/glibc.spec index 718ac21..e2c7b47 100644 --- a/glibc.spec +++ b/glibc.spec @@ -157,7 +157,7 @@ end \ Summary: The GNU libc libraries Name: glibc Version: %{glibcversion} -Release: 202%{?dist} +Release: 203%{?dist} # In general, GPLv2+ is used by programs, LGPLv2+ is used for # libraries. @@ -1226,6 +1226,12 @@ Patch917: glibc-RHEL-57671-2.patch Patch918: glibc-RHEL-57671-3.patch Patch919: glibc-RHEL-94634.patch Patch920: glibc-RHEL-71584.patch +Patch921: glibc-RHEL-50546-1.patch +Patch922: glibc-RHEL-50546-2.patch +Patch923: glibc-RHEL-50546-3.patch +Patch924: glibc-RHEL-50546-4.patch +Patch925: glibc-RHEL-50546-5.patch +Patch926: glibc-RHEL-50546-6.patch ############################################################################## # Continued list of core "glibc" package information: @@ -3219,6 +3225,9 @@ update_gconv_modules_cache () %endif %changelog +* Thu Jun 05 2025 Arjun Shankar - 2.34-203 +- manual: Document several *at file system interface functions (RHEL-50546) + * Wed Jun 04 2025 Frédéric Bérat - 2.34-202 - x86: Avoid integer truncation with large cache sizes (RHEL-71584)