rpms/glibc
6
0
Fork 2
Code Issues Pull Requests Releases Activity

manual: Document several *at file system interface functions (RHEL-50546)

Browse Source 
Resolves: RHEL-50546
This commit is contained in:
Arjun Shankar 2025-06-05 19:14:40 +02:00
parent 89ce8a7589
commit c6e49bb8c7
7 changed files with 351 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
glibc-RHEL-50546-1.patch Normal file
View File

@ -0,0 +1,67 @@
commit 3b21166c4d34ee032093bcf599ffac42ad8a4371
Author: Arjun Shankar <arjun@redhat.com>
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 <fweimer@redhat.com>
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

50
glibc-RHEL-50546-2.patch Normal file
View File

@ -0,0 +1,50 @@
commit 941157dbcdf1c410960bde991206bfb6d9bb292f
Author: Arjun Shankar <arjun@redhat.com>
Date: Wed Jun 4 13:08:54 2025 +0200
manual: Document faccessat
Reviewed-by: Florian Weimer <fweimer@redhat.com>
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

38
glibc-RHEL-50546-3.patch Normal file
View File

@ -0,0 +1,38 @@
commit 49766eb1a5b93d093bd0fada55ca7a42dfdb10d6
Author: Arjun Shankar <arjun@redhat.com>
Date: Wed Jun 4 13:08:55 2025 +0200
manual: Document mkdirat
Reviewed-by: Florian Weimer <fweimer@redhat.com>
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

38
glibc-RHEL-50546-4.patch Normal file
View File

@ -0,0 +1,38 @@
commit 60f86c9cd062882cbeb04b2944c3dfb7457ee5c5
Author: Arjun Shankar <arjun@redhat.com>
Date: Wed Jun 4 13:08:56 2025 +0200
manual: Document renameat
Reviewed-by: Florian Weimer <fweimer@redhat.com>
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

51
glibc-RHEL-50546-5.patch Normal file
View File

@ -0,0 +1,51 @@
commit 75b725717ff23d0ae38fc7f4a0361cb1bdffbe2e
Author: Arjun Shankar <arjun@redhat.com>
Date: Wed Jun 4 13:08:57 2025 +0200
manual: Document unlinkat
Reviewed-by: Florian Weimer <fweimer@redhat.com>
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

97
glibc-RHEL-50546-6.patch Normal file
View File

@ -0,0 +1,97 @@
commit 25f1d945766a3a757d9b54eb48fe7c3c48c0f791
Author: Arjun Shankar <arjun@redhat.com>
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 <fweimer@redhat.com>
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

11
glibc.spec
View File

@ -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 <arjun@redhat.com> - 2.34-203
- manual: Document several *at file system interface functions (RHEL-50546)
* Wed Jun 04 2025 Frédéric Bérat <fberat@redhat.com> - 2.34-202
- x86: Avoid integer truncation with large cache sizes (RHEL-71584)