From ca8e2eea5041e7ba1e533fb6fa2a81a6864c8f97 Mon Sep 17 00:00:00 2001 From: Arjun Shankar Date: Thu, 14 Aug 2025 11:21:59 +0200 Subject: [PATCH] Various updates to the manual from upstream (RHEL-108974) Resolves: RHEL-108974 --- glibc-RHEL-108974-1.patch | 41 + glibc-RHEL-108974-10.patch | 70 ++ glibc-RHEL-108974-11.patch | 146 +++ glibc-RHEL-108974-12.patch | 83 ++ glibc-RHEL-108974-13.patch | 220 +++++ glibc-RHEL-108974-14.patch | 111 +++ glibc-RHEL-108974-15.patch | 31 + glibc-RHEL-108974-16.patch | 94 ++ glibc-RHEL-108974-17.patch | 86 ++ glibc-RHEL-108974-18.patch | 60 ++ glibc-RHEL-108974-19.patch | 65 ++ glibc-RHEL-108974-2.patch | 1893 ++++++++++++++++++++++++++++++++++++ glibc-RHEL-108974-20.patch | 144 +++ glibc-RHEL-108974-21.patch | 67 ++ glibc-RHEL-108974-22.patch | 36 + glibc-RHEL-108974-23.patch | 23 + glibc-RHEL-108974-24.patch | 121 +++ glibc-RHEL-108974-25.patch | 74 ++ glibc-RHEL-108974-26.patch | 47 + glibc-RHEL-108974-27.patch | 39 + glibc-RHEL-108974-28.patch | 33 + glibc-RHEL-108974-29.patch | 67 ++ glibc-RHEL-108974-3.patch | 206 ++++ glibc-RHEL-108974-30.patch | 50 + glibc-RHEL-108974-31.patch | 38 + glibc-RHEL-108974-32.patch | 38 + glibc-RHEL-108974-33.patch | 51 + glibc-RHEL-108974-34.patch | 97 ++ glibc-RHEL-108974-4.patch | 44 + glibc-RHEL-108974-5.patch | 53 + glibc-RHEL-108974-6.patch | 321 ++++++ glibc-RHEL-108974-7.patch | 31 + glibc-RHEL-108974-8.patch | 387 ++++++++ glibc-RHEL-108974-9.patch | 58 ++ glibc.spec | 39 +- 35 files changed, 4963 insertions(+), 1 deletion(-) create mode 100644 glibc-RHEL-108974-1.patch create mode 100644 glibc-RHEL-108974-10.patch create mode 100644 glibc-RHEL-108974-11.patch create mode 100644 glibc-RHEL-108974-12.patch create mode 100644 glibc-RHEL-108974-13.patch create mode 100644 glibc-RHEL-108974-14.patch create mode 100644 glibc-RHEL-108974-15.patch create mode 100644 glibc-RHEL-108974-16.patch create mode 100644 glibc-RHEL-108974-17.patch create mode 100644 glibc-RHEL-108974-18.patch create mode 100644 glibc-RHEL-108974-19.patch create mode 100644 glibc-RHEL-108974-2.patch create mode 100644 glibc-RHEL-108974-20.patch create mode 100644 glibc-RHEL-108974-21.patch create mode 100644 glibc-RHEL-108974-22.patch create mode 100644 glibc-RHEL-108974-23.patch create mode 100644 glibc-RHEL-108974-24.patch create mode 100644 glibc-RHEL-108974-25.patch create mode 100644 glibc-RHEL-108974-26.patch create mode 100644 glibc-RHEL-108974-27.patch create mode 100644 glibc-RHEL-108974-28.patch create mode 100644 glibc-RHEL-108974-29.patch create mode 100644 glibc-RHEL-108974-3.patch create mode 100644 glibc-RHEL-108974-30.patch create mode 100644 glibc-RHEL-108974-31.patch create mode 100644 glibc-RHEL-108974-32.patch create mode 100644 glibc-RHEL-108974-33.patch create mode 100644 glibc-RHEL-108974-34.patch create mode 100644 glibc-RHEL-108974-4.patch create mode 100644 glibc-RHEL-108974-5.patch create mode 100644 glibc-RHEL-108974-6.patch create mode 100644 glibc-RHEL-108974-7.patch create mode 100644 glibc-RHEL-108974-8.patch create mode 100644 glibc-RHEL-108974-9.patch diff --git a/glibc-RHEL-108974-1.patch b/glibc-RHEL-108974-1.patch new file mode 100644 index 0000000..5608e8e --- /dev/null +++ b/glibc-RHEL-108974-1.patch @@ -0,0 +1,41 @@ +commit 400bdb5c85af5a52b3f5653357c9fca87f036bd3 +Author: Paul Eggert +Date: Tue May 28 10:07:47 2024 -0700 + + Improve doc for time_t range (BZ 31808) + +diff --git a/manual/time.texi b/manual/time.texi +index 7d9efc7c6f5b8a43..2e029975b952ac29 100644 +--- a/manual/time.texi ++++ b/manual/time.texi +@@ -123,7 +123,7 @@ The number of clock ticks per second is system-specific. + @code{time_t} is the simplest data type used to represent simple + calendar time. + +-In ISO C, @code{time_t} can be either an integer or a floating-point ++In ISO C, @code{time_t} can be either an integer or a real floating + type, and the meaning of @code{time_t} values is not specified. The + only things a strictly conforming program can do with @code{time_t} + values are: pass them to @code{difftime} to get the elapsed time +@@ -134,11 +134,21 @@ and pass them to the functions that convert them to broken-down time + On POSIX-conformant systems, @code{time_t} is an integer type and its + values represent the number of seconds elapsed since the @dfn{epoch}, + which is 00:00:00 on January 1, 1970, Coordinated Universal Time. ++The count of seconds ignores leap seconds. + + @Theglibc{} additionally guarantees that @code{time_t} is a signed + type, and that all of its functions operate correctly on negative + @code{time_t} values, which are interpreted as times before the epoch. ++Functions like @code{localtime} assume the Gregorian calendar even ++though this is historically inaccurate for timestamps before the ++calendar was introduced or after the calendar will become obsolete. + @cindex epoch ++@Theglibc{} also supports leap seconds as an option, in which case ++@code{time_t} counts leap seconds instead of ignoring them. ++Currently the @code{time_t} type is 64 bits wide on all platforms ++supported by @theglibc{}, except that it is 32 bits wide on a few ++older platforms unless you define @code{_TIME_BITS} to 64. ++@xref{Feature Test Macros}. + @end deftp + + @deftp {Data Type} {struct timespec} diff --git a/glibc-RHEL-108974-10.patch b/glibc-RHEL-108974-10.patch new file mode 100644 index 0000000..700841f --- /dev/null +++ b/glibc-RHEL-108974-10.patch @@ -0,0 +1,70 @@ +commit 7fe1fde499507126f7de10ebf12fecaf77ae6602 +Author: Joseph Myers +Date: Mon Oct 28 22:22:26 2024 +0000 + + Document further requirement on mixing streams / file descriptors + + The gilbc manual has some documentation in llio.texi of requirements + for moving between I/O on FILE * streams and file descriptors on the + same open file description. + + The documentation of what must be done on a FILE * stream to move from + it to either a file descriptor or another FILE * for the same open + file description seems to match POSIX. However, there is an + additional requirement in POSIX on the *second* of the two handles + being moved between, which is not mentioned in the glibc manual: "If + any previous active handle has been used by a function that explicitly + changed the file offset, except as required above for the first + handle, the application shall perform an lseek() or fseek() (as + appropriate to the type of handle) to an appropriate location.". + + Document this requirement on seeking in the glibc manual, limited to + the case that seems relevant to glibc (the new channel is a previously + active stream, on which the seeking previously occurred). Note that + I'm not sure what the "except as required above for the first handle" + is meant to be about, so I haven't documented anything for it. As far + as I can tell, nothing specified for moving from the first handle + actually list calling a seek function as one of the steps to be done. + (Current POSIX doesn't seem to have any relevant rationale for this + section. The rationale in the 1996 edition says "In requiring the + seek to an appropriate location for the new handle, the application is + required to know what it is doing if it is passing streams with seeks + involved. If the required seek is not done, the results are undefined + (and in fact the program probably will not work on many common + implementations)." - which also doesn't help in understanding the + purpose of "except as required above for the first handle".) + + Tested with "make info" and "make pdf". + +diff --git a/manual/llio.texi b/manual/llio.texi +index 850d09205a604589..7121a513a6d6d41b 100644 +--- a/manual/llio.texi ++++ b/manual/llio.texi +@@ -1097,6 +1097,27 @@ streams persist in other processes, their file positions become + undefined as a result. To prevent this, you must clean up the streams + before destroying them. + ++In addition to cleaning up a stream before doing I/O using another ++linked channel, additional precautions are needed to ensure a ++well-defined file position indicator in some cases. If both the ++following conditions hold, you must set the file position indicator on ++the new channel (a stream) using a function such as @code{fseek}. ++ ++@itemize @bullet ++@item ++The new linked channel is a stream that was previously active. ++ ++@item ++The file position indicator was previously set on that channel (while ++it was previously active) with a function such as @code{fseek}. ++@end itemize ++ ++POSIX requires such precautions in more cases: if either the old or ++the new linked channel is a stream (whether or not previously active) ++and the file position indicator was previously set on any channel ++linked to those channels with a function such as @code{fseek} or ++@code{lseek}. ++ + @node Independent Channels + @subsection Independent Channels + @cindex independent channels diff --git a/glibc-RHEL-108974-11.patch b/glibc-RHEL-108974-11.patch new file mode 100644 index 0000000..e9e4d11 --- /dev/null +++ b/glibc-RHEL-108974-11.patch @@ -0,0 +1,146 @@ +commit b7d4de086ce7fcc531cdd67a61dc27b5b3eff482 +Author: Florian Weimer +Date: Mon Aug 5 16:01:12 2024 +0200 + + manual: Describe struct link_map, support link maps with dlinfo + + This does not describe how to use RTLD_DI_ORIGIN and l_name + to reconstruct a full path for the an object. The reason + is that I think we should not recommend further use of + RTLD_DI_ORIGIN due to its buffer overflow potential (bug 24298). + This should be covered by another dlinfo extension. It would + also obsolete the need for the dladdr approach to obtain + the file name for the main executable. + + Obtaining the lowest address from load segments in program + headers is quite clumsy and should be provided directly + via dlinfo. + + Reviewed-by: Carlos O'Donell + +diff --git a/manual/dynlink.texi b/manual/dynlink.texi +index d71f7a30d6f46808..ead5455e30c10a61 100644 +--- a/manual/dynlink.texi ++++ b/manual/dynlink.texi +@@ -351,16 +351,119 @@ support the XGETBV instruction. + @node Dynamic Linker Introspection + @section Dynamic Linker Introspection + +-@Theglibc{} provides various functions for querying information from the ++@Theglibc{} provides various facilities for querying information from the + dynamic linker. + ++@deftp {Data Type} {struct link_map} ++ ++@cindex link map ++A @dfn{link map} is associated with the main executable and each shared ++object. Some fields of the link map are accessible to applications and ++exposed through the @code{struct link_map}. Applications must not modify ++the link map directly. ++ ++Pointers to link maps can be obtained from the @code{_r_debug} variable, ++from the @code{RTLD_DI_LINKMAP} request for @code{dlinfo}, and from the ++@code{_dl_find_object} function. See below for details. ++ ++@table @code ++@item l_addr ++@cindex load address ++This field contains the @dfn{load address} of the object. This is the ++offset that needs to be applied to unrelocated addresses in the object ++image (as stored on disk) to form an address that can be used at run ++time for accessing data or running code. For position-dependent ++executables, the load address is typically zero, and no adjustment is ++required. For position-independent objects, the @code{l_addr} field ++usually contains the address of the object's ELF header in the process ++image. However, this correspondence is not guaranteed because the ELF ++header might not be mapped at all, and the ELF file as stored on disk ++might use zero as the lowest virtual address. Due to the second ++variable, values of the @code{l_addr} field do not necessarily uniquely ++identify a shared object. ++ ++On Linux, to obtain the lowest loaded address of the main program, use ++@code{getauxval} to obtain the @code{AT_PHDR} and @code{AT_PHNUM} values ++for the current process. Alternatively, call ++@samp{dlinfo (_r_debug.r_map, &@var{phdr})} ++to obtain the number of program headers, and the address of the program ++header array will be stored in @var{phdr} ++(of type @code{const ElfW(Phdr) *}, as explained below). ++These values allow processing the array of program headers and the ++address information in the @code{PT_LOAD} entries among them. ++This works even when the program was started with an explicit loader ++invocation. ++ ++@item l_name ++For a shared object, this field contains the file name that the ++@theglibc{} dynamic loader used when opening the object. This can be ++a relative path (relative to the current directory at process start, ++or if the object was loaded later, via @code{dlopen} or ++@code{dlmopen}). Symbolic links are not necessarily resolved. ++ ++For the main executable, @code{l_name} is @samp{""} (the empty string). ++(The main executable is not loaded by @theglibc{}, so its file name is ++not available.) On Linux, the main executable is available as ++@file{/proc/self/exe} (unless an explicit loader invocation was used to ++start the program). The file name @file{/proc/self/exe} continues to ++resolve to the same file even if it is moved within or deleted from the ++file system. Its current location can be read using @code{readlink}. ++@xref{Symbolic Links}. (Although @file{/proc/self/exe} is not actually ++a symbol link, it is only presented as one.) Note that @file{/proc} may ++not be mounted, in which case @file{/proc/self/exe} is not available. ++ ++If an explicit loader invocation is used (such as @samp{ld.so ++/usr/bin/emacs}), the @file{/proc/self/exe} approach does not work ++because the file name refers to the dynamic linker @code{ld.so}, and not ++the @code{/usr/bin/emacs} program. An approximation to the executable ++path is still available in the @code{@var{info}.dli_fname} member after ++calling @samp{dladdr (_r_debug.r_map->l_ld, &@var{info})}. Note that ++this could be a relative path, and it is supplied by the process that ++created the current process, not the kernel, so it could be inaccurate. ++ ++@item l_ld ++This is a pointer to the ELF dynamic segment, an array of tag/value ++pairs that provide various pieces of information that the dynamic ++linking process uses. On most architectures, addresses in the dynamic ++segment are relocated at run time, but on some architectures and in some ++run-time configurations, it is necessary to add the @code{l_addr} field ++value to obtain a proper address. ++ ++@item l_prev ++@itemx l_next ++These fields are used to maintain a double-linked linked list of all ++link maps within one @code{dlmopen} namespace. Note that there is ++currently no thread-safe way to iterate over this list. The ++callback-based @code{dl_iterate_phdr} interface can be used instead. ++@end table ++@end deftp ++ ++@strong{Portability note:} It is not possible to create a @code{struct ++link_map} object and pass a pointer to a function that expects a ++@code{struct link_map *} argument. Only link map pointers initially ++supplied by @theglibc{} are permitted as arguments. In current versions ++of @theglibc{}, handles returned by @code{dlopen} and @code{dlmopen} are ++pointers to link maps. However, this is not a portable assumption, and ++may even change in future versions of @theglibc{}. To obtain the link ++map associated with a handle, see @code{dlinfo} and ++@code{RTLD_DI_LINKMAP} below. If a function accepts both ++@code{dlopen}/@code{dlmopen} handles and @code{struct link_map} pointers ++in its @code{void *} argument, that is documented explicitly. ++ ++@subsection Querying information for loaded objects ++ ++The @code{dlinfo} function provides access to internal information ++associated with @code{dlopen}/@code{dlmopen} handles and link maps. ++ + @deftypefun {int} dlinfo (void *@var{handle}, int @var{request}, void *@var{arg}) + @safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} + @standards{GNU, dlfcn.h} + This function returns information about @var{handle} in the memory + location @var{arg}, based on @var{request}. The @var{handle} argument + must be a pointer returned by @code{dlopen} or @code{dlmopen}; it must +-not have been closed by @code{dlclose}. ++not have been closed by @code{dlclose}. Alternatively, @var{handle} ++can be a @code{struct link_map *} value for a link map of an object ++that has not been closed. + + On success, @code{dlinfo} returns 0 for most request types; exceptions + are noted below. If there is an error, the function returns @math{-1}, diff --git a/glibc-RHEL-108974-12.patch b/glibc-RHEL-108974-12.patch new file mode 100644 index 0000000..e504313 --- /dev/null +++ b/glibc-RHEL-108974-12.patch @@ -0,0 +1,83 @@ +commit 87cd94bba4091d22e24116298ade33b712ada235 +Author: DJ Delorie +Date: Tue Dec 10 17:07:21 2024 -0500 + + manual: Document more sigaction flags + + Adds documentation for three-argument handler + + Adds remainder of the SA_* flags + + Reviewed-by: Florian Weimer + +diff --git a/manual/signal.texi b/manual/signal.texi +index 5c2ba7dae6072926..2012980efe5e2ccc 100644 +--- a/manual/signal.texi ++++ b/manual/signal.texi +@@ -1141,6 +1141,15 @@ This is used in the same way as the @var{action} argument to the + @code{signal} function. The value can be @code{SIG_DFL}, + @code{SIG_IGN}, or a function pointer. @xref{Basic Signal Handling}. + ++@item void (*sa_sigaction) (int @var{signum}, siginfo_t *@var{info}, void *@var{ucontext}) ++This is an alternate to @code{sa_handler} that is used when the ++@code{sa_flags} includes the @code{flag SA_SIGINFO}. Note that this ++and @code{sa_handler} overlap; only ever set one at a time. ++ ++The contents of the @var{info} and @var{ucontext} structures are ++kernel and architecture dependent. Please see ++@manpageurl{sigaction,2} for details. ++ + @item sigset_t sa_mask + This specifies a set of signals to be blocked while the handler runs. + Blocking is explained in @ref{Blocking for Handler}. Note that the +@@ -1324,6 +1333,24 @@ delivered for both terminated children and stopped children. + Setting this flag for a signal other than @code{SIGCHLD} has no effect. + @end deftypevr + ++@deftypevr Macro int SA_NOCLDWAIT ++This flag is meaningful only for the @code{SIGCHLD} signal. When the ++flag is set, the terminated child will not wait for the parent to reap ++it, or become a zombie if not reaped. The child will instead be ++reaped by the kernel immediately on termination, similar to setting ++SIGCHLD to SIG_IGN. ++ ++Setting this flag for a signal other than @code{SIGCHLD} has no effect. ++@end deftypevr ++ ++@deftypevr Macro int SA_NODEFER ++Normally a signal is added to the signal mask while running its own ++handler; this negates that, so that the same signal can be received ++while it's handler is running. Note that if the signal is included in ++@code{sa_mask}, it is masked regardless of this flag. Only useful when ++assigning a function as a signal handler. ++@end deftypevr ++ + @deftypevr Macro int SA_ONSTACK + @standards{BSD, signal.h} + If this flag is set for a particular signal number, the system uses the +@@ -1332,6 +1359,12 @@ If a signal with this flag arrives and you have not set a signal stack, + the normal user stack is used instead, as if the flag had not been set. + @end deftypevr + ++@deftypevr Macro int SA_RESETHAND ++Resets the handler for a signal to SIG_DFL, at the moment specified ++handler function begins. I.e. the handler is called once, then the ++action resets. ++@end deftypevr ++ + @deftypevr Macro int SA_RESTART + @standards{BSD, signal.h} + This flag controls what happens when a signal is delivered during +@@ -1347,6 +1380,12 @@ clear, returning from a handler makes the function fail. + @xref{Interrupted Primitives}. + @end deftypevr + ++@deftypevr Macro int SA_SIGINFO ++Indicates that the @code{sa_sigaction} three-argument form of the ++handler should be used in setting up a handler instead of the ++one-argument @code{sa_handler} form. ++@end deftypevr ++ + @node Initial Signal Actions + @subsection Initial Signal Actions + @cindex initial signal actions diff --git a/glibc-RHEL-108974-13.patch b/glibc-RHEL-108974-13.patch new file mode 100644 index 0000000..73762e4 --- /dev/null +++ b/glibc-RHEL-108974-13.patch @@ -0,0 +1,220 @@ +commit a3a5634d9b0e193502d16488205452598dc4aa74 +Author: Arjun Shankar +Date: Tue Jan 14 02:52:09 2025 +0100 + + manual: Consolidate POSIX Semaphores docs in Threads chapter + + This commit moves the `sem_*' family of functions from the IPC chapter, + replacing them with a reference to their new location in the Threads + chapter. `sem_clockwait' is also moved out of the Non-POSIX Extensions + subsection since it is now included in the standard since Issue 8: + https://pubs.opengroup.org/onlinepubs/9799919799/functions/sem_clockwait.html + + Reviewed-by: Adhemerval Zanella + +diff --git a/manual/ipc.texi b/manual/ipc.texi +index 32c5ac066fb94579..f9c763835961ec32 100644 +--- a/manual/ipc.texi ++++ b/manual/ipc.texi +@@ -46,71 +46,6 @@ by @theglibc{}. + @end deftypefun + + @subsection POSIX Semaphores +- +-@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value}) +-@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +-@c Does not atomically update sem_t therefore AC-unsafe +-@c because it can leave sem_t partially initialized. +-@end deftypefun +- +-@deftypefun int sem_destroy (sem_t *@var{sem}) +-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +-@c Function does nothing and is therefore always safe. +-@end deftypefun +- +-@deftypefun {sem_t *} sem_open (const char *@var{name}, int @var{oflag}, ...) +-@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}} +-@c pthread_once asuinit +-@c +-@c We are AC-Unsafe because we use pthread_once to initialize +-@c a global variable that holds the location of the mounted +-@c shmfs on Linux. +-@end deftypefun +- +-@deftypefun int sem_close (sem_t *@var{sem}) +-@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +-@c lll_lock asulock aculock +-@c twalk mtsrace{:root} +-@c +-@c We are AS-unsafe because we take a non-recursive lock. +-@c We are AC-unsafe because several internal data structures +-@c are not updated atomically. +-@end deftypefun +- +-@deftypefun int sem_unlink (const char *@var{name}) +-@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}} +-@c pthread_once asuinit acucorrupt aculock +-@c mempcpy acucorrupt +-@end deftypefun +- +-@deftypefun int sem_wait (sem_t *@var{sem}) +-@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +-@c atomic_fetch_add_relaxed (nwaiters) acucorrupt +-@c +-@c Given the use atomic operations this function seems +-@c to be AS-safe. It is AC-unsafe because there is still +-@c a window between atomic_fetch_add_relaxed and the pthread_push +-@c of the handler that undoes that operation. A cancellation +-@c at that point would fail to remove the process from the +-@c waiters count. +-@end deftypefun +- +-@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime}) +-@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +-@c Same safety issues as sem_wait. +-@end deftypefun +- +-@deftypefun int sem_trywait (sem_t *@var{sem}) +-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +-@c All atomic operations are safe in all contexts. +-@end deftypefun +- +-@deftypefun int sem_post (sem_t *@var{sem}) +-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +-@c Same safety as sem_trywait. +-@end deftypefun +- +-@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval}) +-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +-@c Atomic write of a value is safe in all contexts. +-@end deftypefun ++@Theglibc{} provides POSIX semaphores as well. These functions' names begin ++with @code{sem_} and they are declared in @file{semaphore.h}. @xref{POSIX ++Semaphores}. +diff --git a/manual/threads.texi b/manual/threads.texi +index 9ea137cb9663b89c..806ab866c5231015 100644 +--- a/manual/threads.texi ++++ b/manual/threads.texi +@@ -554,6 +554,8 @@ This section describes the @glibcadj{} POSIX Threads implementation. + @menu + * Thread-specific Data:: Support for creating and + managing thread-specific data ++* POSIX Semaphores:: Support for process and thread ++ synchronization using semaphores + * Non-POSIX Extensions:: Additional functions to extend + POSIX Thread functionality + @end menu +@@ -615,6 +617,86 @@ Associate the thread-specific @var{value} with @var{key} in the calling thread. + @end deftypefun + + ++@node POSIX Semaphores ++@subsection POSIX Semaphores ++ ++@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value}) ++@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} ++@c Does not atomically update sem_t therefore AC-unsafe ++@c because it can leave sem_t partially initialized. ++@end deftypefun ++ ++@deftypefun int sem_destroy (sem_t *@var{sem}) ++@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} ++@c Function does nothing and is therefore always safe. ++@end deftypefun ++ ++@deftypefun {sem_t *} sem_open (const char *@var{name}, int @var{oflag}, ...) ++@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}} ++@c pthread_once asuinit ++@c ++@c We are AC-Unsafe because we use pthread_once to initialize ++@c a global variable that holds the location of the mounted ++@c shmfs on Linux. ++@end deftypefun ++ ++@deftypefun int sem_close (sem_t *@var{sem}) ++@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} ++@c lll_lock asulock aculock ++@c twalk mtsrace{:root} ++@c ++@c We are AS-unsafe because we take a non-recursive lock. ++@c We are AC-unsafe because several internal data structures ++@c are not updated atomically. ++@end deftypefun ++ ++@deftypefun int sem_unlink (const char *@var{name}) ++@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}} ++@c pthread_once asuinit acucorrupt aculock ++@c mempcpy acucorrupt ++@end deftypefun ++ ++@deftypefun int sem_wait (sem_t *@var{sem}) ++@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} ++@c atomic_fetch_add_relaxed (nwaiters) acucorrupt ++@c ++@c Given the use atomic operations this function seems ++@c to be AS-safe. It is AC-unsafe because there is still ++@c a window between atomic_fetch_add_relaxed and the pthread_push ++@c of the handler that undoes that operation. A cancellation ++@c at that point would fail to remove the process from the ++@c waiters count. ++@end deftypefun ++ ++@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime}) ++@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} ++@c Same safety issues as sem_wait. ++@end deftypefun ++ ++@deftypefun int sem_clockwait (sem_t *@var{sem}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) ++@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} ++Behaves like @code{sem_timedwait} except the time @var{abstime} is measured ++against the clock specified by @var{clockid} rather than ++@code{CLOCK_REALTIME}. Currently, @var{clockid} must be either ++@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}. ++@end deftypefun ++ ++@deftypefun int sem_trywait (sem_t *@var{sem}) ++@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} ++@c All atomic operations are safe in all contexts. ++@end deftypefun ++ ++@deftypefun int sem_post (sem_t *@var{sem}) ++@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} ++@c Same safety as sem_trywait. ++@end deftypefun ++ ++@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval}) ++@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} ++@c Atomic write of a value is safe in all contexts. ++@end deftypefun ++ ++ + @node Non-POSIX Extensions + @subsection Non-POSIX Extensions + +@@ -752,16 +834,6 @@ freed. + @Theglibc{} provides several waiting functions that expect an explicit + @code{clockid_t} argument. + +-@comment semaphore.h +-@comment POSIX-proposed +-@deftypefun int sem_clockwait (sem_t *@var{sem}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) +-@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +-Behaves like @code{sem_timedwait} except the time @var{abstime} is measured +-against the clock specified by @var{clockid} rather than +-@code{CLOCK_REALTIME}. Currently, @var{clockid} must be either +-@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}. +-@end deftypefun +- + @comment pthread.h + @comment POSIX-proposed + @deftypefun int pthread_cond_clockwait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) +@@ -835,6 +907,9 @@ Currently, @var{clockid} must be either @code{CLOCK_MONOTONIC} or + @code{CLOCK_REALTIME}. + @end deftypefun + ++The @code{sem_clockwait} function also works using a @code{clockid_t} ++argument. @xref{POSIX Semaphores}. ++ + @node Single-Threaded + @subsubsection Detecting Single-Threaded Execution + diff --git a/glibc-RHEL-108974-14.patch b/glibc-RHEL-108974-14.patch new file mode 100644 index 0000000..3ff468d --- /dev/null +++ b/glibc-RHEL-108974-14.patch @@ -0,0 +1,111 @@ +commit 47c4f4045caaaad1e6165cb638e45d633d6ca97f +Author: Arjun Shankar +Date: Tue Jan 14 02:52:10 2025 +0100 + + manual: Add links to POSIX Semaphores man-pages documentation + + The POSIX Semaphores functions are currently undocumented in our info + pages. This commit adds links to the man-pages documentation for all + the `sem_*' functions (except `sem_clockwait') so that they refer to + some useful documentation instead of just being stubs. `sem_clockwait' + isn't documented by man-pages but thankfully already has a small useful + blurb in our own docs. + + Reviewed-by: Adhemerval Zanella + +diff --git a/manual/threads.texi b/manual/threads.texi +index 806ab866c5231015..7b9c79636c9cc79c 100644 +--- a/manual/threads.texi ++++ b/manual/threads.texi +@@ -621,18 +621,24 @@ Associate the thread-specific @var{value} with @var{key} in the calling thread. + @subsection POSIX Semaphores + + @deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value}) ++@standards{POSIX.1-2008, semaphore.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} ++@manpagefunctionstub{sem_init,3} + @c Does not atomically update sem_t therefore AC-unsafe + @c because it can leave sem_t partially initialized. + @end deftypefun + + @deftypefun int sem_destroy (sem_t *@var{sem}) ++@standards{POSIX.1-2008, semaphore.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} ++@manpagefunctionstub{sem_destroy,3} + @c Function does nothing and is therefore always safe. + @end deftypefun + + @deftypefun {sem_t *} sem_open (const char *@var{name}, int @var{oflag}, ...) ++@standards{POSIX.1-2008, semaphore.h} + @safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}} ++@manpagefunctionstub{sem_open,3} + @c pthread_once asuinit + @c + @c We are AC-Unsafe because we use pthread_once to initialize +@@ -641,7 +647,9 @@ Associate the thread-specific @var{value} with @var{key} in the calling thread. + @end deftypefun + + @deftypefun int sem_close (sem_t *@var{sem}) ++@standards{POSIX.1-2008, semaphore.h} + @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} ++@manpagefunctionstub{sem_close,3} + @c lll_lock asulock aculock + @c twalk mtsrace{:root} + @c +@@ -651,13 +659,17 @@ Associate the thread-specific @var{value} with @var{key} in the calling thread. + @end deftypefun + + @deftypefun int sem_unlink (const char *@var{name}) ++@standards{POSIX.1-2008, semaphore.h} + @safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}} ++@manpagefunctionstub{sem_unlink,3} + @c pthread_once asuinit acucorrupt aculock + @c mempcpy acucorrupt + @end deftypefun + + @deftypefun int sem_wait (sem_t *@var{sem}) ++@standards{POSIX.1-2008, semaphore.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} ++@manpagefunctionstub{sem_wait,3} + @c atomic_fetch_add_relaxed (nwaiters) acucorrupt + @c + @c Given the use atomic operations this function seems +@@ -669,11 +681,14 @@ Associate the thread-specific @var{value} with @var{key} in the calling thread. + @end deftypefun + + @deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime}) ++@standards{POSIX.1-2008, semaphore.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} ++@manpagefunctionstub{sem_timedwait,3} + @c Same safety issues as sem_wait. + @end deftypefun + + @deftypefun int sem_clockwait (sem_t *@var{sem}, clockid_t @var{clockid}, const struct timespec *@var{abstime}) ++@standards{POSIX.1-2024, semaphore.h} + @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} + Behaves like @code{sem_timedwait} except the time @var{abstime} is measured + against the clock specified by @var{clockid} rather than +@@ -682,17 +697,23 @@ against the clock specified by @var{clockid} rather than + @end deftypefun + + @deftypefun int sem_trywait (sem_t *@var{sem}) ++@standards{POSIX.1-2008, semaphore.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} ++@manpagefunctionstub{sem_trywait,3} + @c All atomic operations are safe in all contexts. + @end deftypefun + + @deftypefun int sem_post (sem_t *@var{sem}) ++@standards{POSIX.1-2008, semaphore.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} ++@manpagefunctionstub{sem_post,3} + @c Same safety as sem_trywait. + @end deftypefun + + @deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval}) ++@standards{POSIX.1-2008, semaphore.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} ++@manpagefunctionstub{sem_getvalue,3} + @c Atomic write of a value is safe in all contexts. + @end deftypefun + diff --git a/glibc-RHEL-108974-15.patch b/glibc-RHEL-108974-15.patch new file mode 100644 index 0000000..ca629f2 --- /dev/null +++ b/glibc-RHEL-108974-15.patch @@ -0,0 +1,31 @@ +commit 1b29cb7b781ecf3f6dc4647c32861119bacbd5ef +Author: Tulio Magno Quites Machado Filho +Date: Tue Jan 28 15:31:01 2025 -0300 + + manual: Safety annotations for timespec_get and timespec_getres + + Add preliminary annotations that are consistent with clock_gettime and + clock_getres. + + Reviewed-by: Florian Weimer + +diff --git a/manual/time.texi b/manual/time.texi +index 6ccb07fcfc10449b..6abae3f43640e8ec 100644 +--- a/manual/time.texi ++++ b/manual/time.texi +@@ -595,6 +595,7 @@ Systems may support more than just this @w{ISO C} clock. + + @deftypefun int timespec_get (struct timespec *@var{ts}, int @var{base}) + @standards{ISO, time.h} ++@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + Store into @code{*@var{ts}} the current time according to the @w{ISO + C} time @var{base}. + +@@ -603,6 +604,7 @@ The return value is @var{base} on success and @code{0} on failure. + + @deftypefun int timespec_getres (struct timespec *@var{res}, int @var{base}) + @standards{ISO, time.h} ++@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + If @var{ts} is non-null, store into @code{*@var{ts}} the resolution of + the time provided by @code{timespec_get} function for the @w{ISO C} + time @var{base}. diff --git a/glibc-RHEL-108974-16.patch b/glibc-RHEL-108974-16.patch new file mode 100644 index 0000000..69d20b9 --- /dev/null +++ b/glibc-RHEL-108974-16.patch @@ -0,0 +1,94 @@ +commit 37a0933e1bf97346b45463bde0c4631be8abaa07 +Author: DJ Delorie +Date: Tue Dec 10 16:57:21 2024 -0500 + + manual: make @manpageurl more specific to each output + + Tweak the @manpageurl macro to customize the output for + each of html, info, and pdf output. HTML and PDF (at + least, these days) support clicking on the link title, + whereas info does not. Add text to the intro section + explaining which man pages are normative and which + aren't. + +diff --git a/manual/intro.texi b/manual/intro.texi +index 879c1b38d9b73a46..d95648468db6f224 100644 +--- a/manual/intro.texi ++++ b/manual/intro.texi +@@ -966,13 +966,25 @@ functionality is available on commercial systems. + + @Theglibc{} includes by reference the Linux man-pages + @value{man_pages_version} documentation to document the listed +-syscalls for the Linux kernel. For reference purposes only the latest ++syscalls for the Linux kernel. For reference purposes only, the latest + @uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project} + documentation can be accessed from the + @uref{https://www.kernel.org,Linux kernel} website. Where the syscall + has more specific documentation in this manual that more specific + documentation is considered authoritative. + ++Throughout this manual, when we refer to a man page, for example: ++@quotation ++@manpageurl{sendmsg,2} ++@end quotation ++@noindent ++we are referring primarily to the specific version noted above (the ++``normative'' version), typically accessed by running (for example) ++@code{man 2 sendmsg} on a system with that version installed. For ++convenience, we will also link to the online latest copy of the man ++pages, but keep in mind that version will almost always be newer than, ++and thus different than, the normative version noted above. ++ + Additional details on the Linux system call interface can be found in + @xref{System Calls}. + +diff --git a/manual/macros.texi b/manual/macros.texi +index f48dd4ec2282634f..2003ce2678054ae4 100644 +--- a/manual/macros.texi ++++ b/manual/macros.texi +@@ -282,14 +282,22 @@ cwd\comments\ + @macro standardsx {element, standard, header} + @end macro + ++@ifhtml + @macro manpageurl {func, sec} +-@url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html} ++@url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html,,\func\(\sec\)} ++@xref{Linux Kernel} + @end macro ++@end ifhtml ++@ifnothtml ++@macro manpageurl {func, sec} ++\func\(\sec\) (Latest, online: @url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html}) ++@xref{Linux Kernel} ++@end macro ++@end ifnothtml + + @macro manpagefunctionstub {func,sec} + This documentation is a stub. For additional information on this + function, consult the manual page @manpageurl{\func\,\sec\}. +-@xref{Linux Kernel}. + @end macro + + @end ifclear +diff --git a/manual/resource.texi b/manual/resource.texi +index 6729ada79402f0ad..23952a6b8b9f4f58 100644 +--- a/manual/resource.texi ++++ b/manual/resource.texi +@@ -966,7 +966,6 @@ scheduling policies. + + For additional information about scheduling policies, consult consult + the manual pages @manpageurl{sched,7} and @manpageurl{sched_setattr,2}. +-@xref{Linux Kernel}. + + @strong{Note:} Calling the @code{sched_setattr} function is incompatible + with support for @code{PTHREAD_PRIO_PROTECT} mutexes. +@@ -1000,7 +999,7 @@ Scheduling flags associated with the scheduling policy. + + In addition to the generic fields, policy-specific fields are available. + For additional information, consult the manual page +-@manpageurl{sched_setattr,2}. @xref{Linux Kernel}. ++@manpageurl{sched_setattr,2}. + @end deftp + + @deftypefun int sched_setattr (pid_t @var{tid}, struct sched_attr *@var{attr}, unsigned int flags) diff --git a/glibc-RHEL-108974-17.patch b/glibc-RHEL-108974-17.patch new file mode 100644 index 0000000..7e2532f --- /dev/null +++ b/glibc-RHEL-108974-17.patch @@ -0,0 +1,86 @@ +commit bb6496b96444dfd55d7105396780f6eba14b1cd9 +Author: DJ Delorie +Date: Fri Jan 17 17:34:02 2025 -0500 + + manual: Update signal descriptions + + Based on auditing all the signals and source trees for Hurd and + Linux... + + SIGSYS - This is not used for a bad system call (ENOSYS is used + for that). This is used by SECCOMP and some cases where an invalid + sub-function was requested. + + SIGSTKFLT - Note it used to be a coprocessor stack fault but is now + obsolete and available for general user use. + + SIGLOST - Hurd only now; note that its original purpose as an NFS + lock lost signal is obsolete. + + SIGPWR - Note this is for power lost *and* power restored, and is + more a user-mode signal than a kernel-generated signal. + + Reviewed-by: Florian Weimer + +diff --git a/manual/signal.texi b/manual/signal.texi +index 2012980efe5e2ccc..842b4e49a275bd3b 100644 +--- a/manual/signal.texi ++++ b/manual/signal.texi +@@ -427,9 +427,18 @@ failure to properly emulate them. + + @deftypevr Macro int SIGSYS + @standards{Unix, signal.h} +-Bad system call; that is to say, the instruction to trap to the +-operating system was executed, but the code number for the system call +-to perform was invalid. ++System call event. This signal may be generated by a valid system ++call which requested an invalid sub-function, and also by the SECCOMP ++filter when it filters or traps a system call. ++ ++If the system call itself is invalid or unsupported by the kernel, the ++call will not raise this signal, but will return @code{ENOSYS}. ++@end deftypevr ++ ++@deftypevr Macro int SIGSTKFLT ++Coprocessor stack fault. Obsolete, no longer generated. This signal ++may be used by applications in much the way @code{SIGUSR1} and ++@code{SIGUSR2} are. + @end deftypevr + + @node Termination Signals +@@ -752,12 +761,11 @@ that isn't connected. @xref{Sending Data}. + @deftypevr Macro int SIGLOST + @standards{GNU, signal.h} + @cindex lost resource signal +-Resource lost. This signal is generated when you have an advisory lock +-on an NFS file, and the NFS server reboots and forgets about your lock. +- +-On @gnuhurdsystems{}, @code{SIGLOST} is generated when any server program +-dies unexpectedly. It is usually fine to ignore the signal; whatever +-call was made to the server that died just returns an error. ++Resource lost. On @gnuhurdsystems{}, @code{SIGLOST} is generated when ++any server program dies unexpectedly. It is usually fine to ignore ++the signal; whatever call was made to the server that died just ++returns an error. This signal's original purpose of signalling a lost ++NFS lock is obsolete. + @end deftypevr + + @deftypevr Macro int SIGXCPU +@@ -817,6 +825,17 @@ to print some status information about the system and what the process + is doing. Otherwise the default is to do nothing. + @end deftypevr + ++@deftypevr Macro int SIGPWR ++@cindex power event signal ++Power lost or restored. On s390x Linux systems, this signal is ++generated when a machine check warning is issued, and is sent to the ++process designated to receive ctrl-alt-del notifications. Otherwise, ++it is up to userspace applications to generate this signal and manage ++notifications as to the type of power event that happened. ++ ++The default action is to terminate the process. ++@end deftypevr ++ + @node Signal Messages + @subsection Signal Messages + @cindex signal messages diff --git a/glibc-RHEL-108974-18.patch b/glibc-RHEL-108974-18.patch new file mode 100644 index 0000000..61b300e --- /dev/null +++ b/glibc-RHEL-108974-18.patch @@ -0,0 +1,60 @@ +commit 226476e32251b5688eead482a9338c04ce84d715 +Author: Siddhesh Poyarekar +Date: Thu Jan 30 10:05:17 2025 -0500 + + manual: Explain sched_yield semantics with different schedulers + + The manual entry for sched_yield mentions that the function call could + be a nop if there are no other tasks with the same absolute priority. + Expand the explanation to include example schedulers on Linux so that + it's clear that sched_yield may not always result in a different task + being scheduled. + + Signed-off-by: Siddhesh Poyarekar + Reviewed-by: Joseph Myers + +diff --git a/manual/resource.texi b/manual/resource.texi +index 23952a6b8b9f4f58..685ddd6defc57818 100644 +--- a/manual/resource.texi ++++ b/manual/resource.texi +@@ -929,18 +929,31 @@ function, so there are no specific @code{errno} values. + @c Direct syscall on Linux; alias to swtch on HURD. + + This function voluntarily gives up the task's claim on the CPU. +- +-Technically, @code{sched_yield} causes the calling task to be made +-immediately ready to run (as opposed to running, which is what it was +-before). This means that if it has absolute priority higher than 0, it +-gets pushed onto the tail of the queue of tasks that share its ++Depending on the scheduling policy in effect and the tasks ready to run ++on the system, another task may be scheduled to run instead. ++ ++A call to @code{sched_yield} does not guarantee that a different task ++from the calling task is scheduled as a result; it depends on the ++scheduling policy used on the target system. It is possible that the ++call may not result in any visible effect, i.e., the same task gets ++scheduled again. ++ ++For example on Linux systems, when a simple priority-based FIFO ++scheduling policy (@code{SCHED_FIFO}) is in effect, the calling task is ++made immediately ready to run (as opposed to running, which is what it ++was before). This means that if it has absolute priority higher than 0, ++it gets pushed onto the tail of the queue of tasks that share its + absolute priority and are ready to run, and it will run again when its + turn next arrives. If its absolute priority is 0, it is more + complicated, but still has the effect of yielding the CPU to other +-tasks. +- +-If there are no other tasks that share the calling task's absolute +-priority, this function doesn't have any effect. ++tasks. If there are no other tasks that share the calling task's ++absolute priority, it will be scheduled again as if @code{sched_yield} ++was never called. ++ ++Another example could be a time slice based preemptive round-robin ++policy, such as the @code{SCHED_RR} policy on Linux. It is possible ++with this policy that the calling task is scheduled again because it ++still has time left in its slice. + + To the extent that the containing program is oblivious to what other + processes in the system are doing and how fast it executes, this diff --git a/glibc-RHEL-108974-19.patch b/glibc-RHEL-108974-19.patch new file mode 100644 index 0000000..3475b31 --- /dev/null +++ b/glibc-RHEL-108974-19.patch @@ -0,0 +1,65 @@ +commit f451a02a8c3c0bc6b41dac5e9e6ad49dd1c9529c +Author: Joseph Myers +Date: Mon May 12 14:56:07 2025 +0000 + + Document all CLOCK_* values + + The manual documents CLOCK_REALTIME and CLOCK_MONOTONIC but not other + CLOCK_* values. Add documentation of the POSIX clocks + CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID, along with a + reference to the Linux man pages for the semantics of the + Linux-specific clocks supported (as with some other functionality + coming direct from the Linux kernel where the man pages can be + considered the main documentation). + + Note: CLOCK_MONOTONIC_RAW, CLOCK_REALTIME_COARSE and + CLOCK_MONOTONIC_COARSE are also defined in the toplevel bits/time.h, + as used for Hurd. Nevertheless, I see no sign that the Hurd code in + glibc actually has any support for those clocks, so I think it is + correct to document them as Linux-specific (and to refer only to the + Linux man pages for their semantics). + + Reviewed-by: Carlos O'Donell + +diff --git a/manual/time.texi b/manual/time.texi +index 6abae3f43640e8ec..4dde875dde4d8075 100644 +--- a/manual/time.texi ++++ b/manual/time.texi +@@ -528,7 +528,36 @@ Therefore, @code{CLOCK_MONOTONIC} cannot be used to measure + absolute time, only elapsed time. + @end deftypevr + +-Systems may support more than just these two POSIX clocks. ++The following clocks are defined by POSIX, but may not be supported by ++all POSIX systems: ++ ++@deftypevr Macro clockid_t CLOCK_PROCESS_CPUTIME_ID ++@standards{POSIX.1, time.h} ++This POSIX clock measures the amount of CPU time used by the calling ++process. ++@end deftypevr ++ ++@deftypevr Macro clockid_t CLOCK_THREAD_CPUTIME_ID ++@standards{POSIX.1, time.h} ++This POSIX clock measures the amount of CPU time used by the calling ++thread. ++@end deftypevr ++ ++The following clocks are Linux extensions: ++ ++@deftypevr Macro clockid_t CLOCK_MONOTONIC_RAW ++@deftypevrx Macro clockid_t CLOCK_REALTIME_COARSE ++@deftypevrx Macro clockid_t CLOCK_MONOTONIC_COARSE ++@deftypevrx Macro clockid_t CLOCK_BOOTTIME ++@deftypevrx Macro clockid_t CLOCK_REALTIME_ALARM ++@deftypevrx Macro clockid_t CLOCK_BOOTTIME_ALARM ++@deftypevrx Macro clockid_t CLOCK_TAI ++@standards{Linux, time.h} ++For details of these clocks, see the manual page ++@manpageurl{clock_gettime,2}. ++@end deftypevr ++ ++Systems may support additional clocks beyond those listed here. + + @deftypefun int clock_gettime (clockid_t @var{clock}, struct timespec *@var{ts}) + @standards{POSIX.1, time.h} diff --git a/glibc-RHEL-108974-2.patch b/glibc-RHEL-108974-2.patch new file mode 100644 index 0000000..093af88 --- /dev/null +++ b/glibc-RHEL-108974-2.patch @@ -0,0 +1,1893 @@ +commit ee768a30fe9099972dad04c49972c2508a208b9b +Author: Paul Eggert +Date: Sat Jun 8 09:48:25 2024 -0700 + + Modernize and fix doc’s “Date and Time” (BZ 31876) + + POSIX.1-2024 (now official) specifies tm_gmtoff and tm_zone. + This is a good time to update the manual’s “Date and Time” + chapter so I went through it, fixed some outdated + stuff that had been in there for decades, and improved it to match + POSIX.1-2024 better and to clarify some implementation-defined + behavior. Glibc already conforms to POSIX.1-2024 in these matters, so + this is merely a documentation change. + + * manual/examples/strftim.c: Use snprintf instead of now-deprecated + function asctime. Check for localtime failure. Simplify by using + puts instead of fputs. Prefer ‘buf, sizeof buf’ to less-obvious + ‘buffer, SIZE’. + + * manual/examples/timespec_subtract.c: Modernize to use struct + timespec not struct timeval, and rename from timeval_subtract.c. + All uses changed. Check for overflow. Do not check for negative + return value, which ought to be OK since negative time_t is OK. + Use GNU indenting style. + + * manual/time.texi: + + Document CLOCKS_PER_SEC, TIME_UTC, timespec_get, timespec_getres, + strftime_l. + + Document the storage lifetime of tm_zone and of tzname. + + Caution against use of tzname, timezone and daylight, saying that + these variables have unspecified values when TZ is geographic. + This is what glibc actually does (contrary to what the manual said + before this patch), and POSIX is planned to say the same thing + . + Also say that directly accessing the variables is not thread-safe. + + Say that localtime_r and ctime_r don’t necessarily set time zone + state. Similarly, in the tzset documentation, say that it is called + by ctime, localtime, mktime, strftime, not that it is called by all + time conversion functions that depend on the time zone. + + Say that tm_isdst is useful mostly just for mktime, and that + other uses should prefer tm_gmtoff and tm_zone instead. + + Do not say that strftime ignores tm_gmtoff and tm_zone, because + it doesn’t do that. + + Document what gmtime does to tm_gmtoff and tm_zone. + + Say that the asctime, asctime_r, ctime, and ctime_r are now deprecated + and/or obsolescent, and that behavior is undefined if the year is < + 1000 or > 9999. Document strftime before these now-obsolescent + functions, so that readers see the useful function first. + + Coin the terms “geographical format” and “proleptic format” for the + two main formats of TZ settings, to simplify exposition. Use this + wording consistently. + + Update top-level proleptic syntax to match POSIX.1-2024, which glibc + already implements. Document the angle-bracket quoted forms of time + zone abbreviations in proleptic TZ. Say that time zone abbreviations + can contain only ASCII alphanumerics, ‘+’, and ‘-’. + + Document what happens if the proleptic form specifies a DST + abbreviation and offset but omits the rules. POSIX says this is + implementation-defined so we need to document it. Although this + documentation mentions ‘posixrules’ tersely, we need to rethink + ‘posixrules’ since I think it stops working after 2038. + + Clarify wording about TZ settings beginning with ‘;’. + + Say that timegm is in ISO C (as of C23). + + Say that POSIX.1-2024 removed gettimeofday. + + Say that tm_gmtoff and tm_zone are extensions to ISO C, which is + clearer than saying they are invisible in a struct ISO C enviroment, + and gives us more wiggle room if we want to make them visible in + strict ISO C, something that ISO C allows. + + Drop mention of old standards like POSIX.1c and POSIX.2-1992 in the + text when the history is so old that it’s no longer useful in a + general-purpose manual. + + Define Coordinated Universal Time (UTC), time zone, time zone ruleset, + and POSIX Epoch, and use these phrases more consistently. + + Improve TZ examples to show more variety, and to reflect current + practice and timestamps. Remove obsolete example about Argentina. + Add an example for Ireland. + + Don’t rely on GCC extensions when explaining ctime_r. + + Do not say that difftime produces the mathematically correct result, + since it might be inexact. + + For clock_t don’t say “as in the example above” when there is no + such example, and don’t say that casting to double works “properly + and consistently no matter what”, as it suffers from rounding and + overflow. + + Don’t say broken-down time is not useful for calculations; it’s + merely painful. + + Say that UTC is not defined before 1960. + + Rename Time Zone Functions to Time Zone State. All uses changed. + + Update Internet RFC 822 → 5322, 1305 → 5905. Drop specific years of + ISO 8601 as they don’t matter. + + Minor style changes: @code{"..."} → @t{"..."} to avoid overquoting in + info files, @code → @env for environment variables, Daylight Saving + Time → daylight saving time, white space → whitespace, prime meridian + → Prime Meridian. + +diff --git a/benchtests/strcoll-inputs/filelist#en_US.UTF-8 b/benchtests/strcoll-inputs/filelist#en_US.UTF-8 +index 197700ec90c4cd17..0d8f1c722baae2d7 100644 +--- a/benchtests/strcoll-inputs/filelist#en_US.UTF-8 ++++ b/benchtests/strcoll-inputs/filelist#en_US.UTF-8 +@@ -14260,7 +14260,7 @@ sigusr.c + dir2.c + inetsrv.c + argp-ex3.c +-timeval_subtract.c ++timespec_subtract.c + popen.c + filecli.c + db.c +diff --git a/manual/conf.texi b/manual/conf.texi +index 158285dbf06c76ab..be680e0692b1d0e4 100644 +--- a/manual/conf.texi ++++ b/manual/conf.texi +@@ -89,7 +89,7 @@ process can have open simultaneously. @xref{Opening Streams}. + @deftypevr Macro int TZNAME_MAX + @standards{POSIX.1, limits.h} + If defined, the unvarying maximum length of a time zone abbreviation. +-@xref{Time Zone Functions}. ++@xref{TZ Variable}. + @end deftypevr + + These limit macros are always defined in @file{limits.h}. +diff --git a/manual/contrib.texi b/manual/contrib.texi +index 6f987aab227049d5..5b2710f0bad15f26 100644 +--- a/manual/contrib.texi ++++ b/manual/contrib.texi +@@ -630,7 +630,7 @@ a different license: + + @itemize @bullet + @item +-The timezone support code is derived from the public-domain timezone ++The time zone support code is derived from the public-domain time zone + package by Arthur David Olson and his many contributors. + + @item +diff --git a/manual/examples/strftim.c b/manual/examples/strftim.c +index 304981dfc35558d7..6e1e0474c74f0641 100644 +--- a/manual/examples/strftim.c ++++ b/manual/examples/strftim.c +@@ -18,30 +18,32 @@ + #include + #include + +-#define SIZE 256 +- + int + main (void) + { +- char buffer[SIZE]; +- time_t curtime; +- struct tm *loctime; ++ /* This buffer is big enough that the strftime calls ++ below cannot possibly exhaust it. */ ++ char buf[256]; + + /* Get the current time. */ +- curtime = time (NULL); ++ time_t curtime = time (NULL); + + /* Convert it to local time representation. */ +- loctime = localtime (&curtime); ++ struct tm *lt = localtime (&curtime); ++ if (!lt) ++ return 1; + +- /* Print out the date and time in the standard format. */ +- fputs (asctime (loctime), stdout); ++ /* Print the date and time in a simple format ++ that is independent of locale. */ ++ strftime (buf, sizeof buf, "%Y-%m-%d %H:%M:%S", lt); ++ puts (buf); + + /*@group*/ +- /* Print it out in a nice format. */ +- strftime (buffer, SIZE, "Today is %A, %B %d.\n", loctime); +- fputs (buffer, stdout); +- strftime (buffer, SIZE, "The time is %I:%M %p.\n", loctime); +- fputs (buffer, stdout); ++ /* Print it in a nicer English format. */ ++ strftime (buf, sizeof buf, "Today is %A, %B %d.", lt); ++ puts (buf); ++ strftime (buf, sizeof buf, "The time is %I:%M %p.", lt); ++ puts (buf); + + return 0; + } +diff --git a/manual/examples/timespec_subtract.c b/manual/examples/timespec_subtract.c +new file mode 100644 +index 0000000000000000..380d173aabb5b30a +--- /dev/null ++++ b/manual/examples/timespec_subtract.c +@@ -0,0 +1,36 @@ ++/* struct timespec subtraction. ++ Copyright (C) 1991-2024 Free Software Foundation, Inc. ++ ++ This program is free software; you can redistribute it and/or ++ modify it under the terms of the GNU General Public License ++ as published by the Free Software Foundation; either version 2 ++ of the License, or (at your option) any later version. ++ ++ This program is distributed in the hope that it will be useful, ++ but WITHOUT ANY WARRANTY; without even the implied warranty of ++ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ++ GNU General Public License for more details. ++ ++ You should have received a copy of the GNU General Public License ++ along with this program; if not, see . ++*/ ++#include ++#include ++ ++/* Put into *R the difference between X and Y. ++ Return true if overflow occurs, false otherwise. */ ++ ++bool ++timespec_subtract (struct timespec *r, ++ struct timespec x, struct timespec y) ++{ ++ /* Compute nanoseconds, setting @var{borrow} to 1, 0, or -1 ++ for propagation into seconds. */ ++ long int nsec_diff = x.tv_nsec - y.tv_nsec; ++ int borrow = (nsec_diff < 0) - ! (nsec_diff < 1000000000); ++ r->tv_nsec = nsec_diff + 1000000000 * borrow; ++ ++ /* Compute seconds, returning true if this overflows. */ ++ bool v = ckd_sub (&r->tv_sec, x.tv_sec, y.tv_sec); ++ return v ^ ckd_sub (&r->tv_sec, r->tv_sec, borrow); ++} +diff --git a/manual/examples/timeval_subtract.c b/manual/examples/timeval_subtract.c +deleted file mode 100644 +index 20c246320d06beb7..0000000000000000 +--- a/manual/examples/timeval_subtract.c ++++ /dev/null +@@ -1,44 +0,0 @@ +-/* struct timeval subtraction. +- Copyright (C) 1991-2024 Free Software Foundation, Inc. +- +- This program is free software; you can redistribute it and/or +- modify it under the terms of the GNU General Public License +- as published by the Free Software Foundation; either version 2 +- of the License, or (at your option) any later version. +- +- This program is distributed in the hope that it will be useful, +- but WITHOUT ANY WARRANTY; without even the implied warranty of +- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +- GNU General Public License for more details. +- +- You should have received a copy of the GNU General Public License +- along with this program; if not, see . +-*/ +- +-/* Subtract the `struct timeval' values X and Y, +- storing the result in RESULT. +- Return 1 if the difference is negative, otherwise 0. */ +- +-int +-timeval_subtract (struct timeval *result, struct timeval *x, struct timeval *y) +-{ +- /* Perform the carry for the later subtraction by updating @var{y}. */ +- if (x->tv_usec < y->tv_usec) { +- int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1; +- y->tv_usec -= 1000000 * nsec; +- y->tv_sec += nsec; +- } +- if (x->tv_usec - y->tv_usec > 1000000) { +- int nsec = (x->tv_usec - y->tv_usec) / 1000000; +- y->tv_usec += 1000000 * nsec; +- y->tv_sec -= nsec; +- } +- +- /* Compute the time remaining to wait. +- @code{tv_usec} is certainly positive. */ +- result->tv_sec = x->tv_sec - y->tv_sec; +- result->tv_usec = x->tv_usec - y->tv_usec; +- +- /* Return 1 if result is negative. */ +- return x->tv_sec < y->tv_sec; +-} +diff --git a/manual/install.texi b/manual/install.texi +index 7c445946176f0269..c5f159163ab07fa7 100644 +--- a/manual/install.texi ++++ b/manual/install.texi +@@ -206,7 +206,7 @@ This option hardcodes the newly built C library path in dynamic tests + so that they can be invoked directly. + + @item --disable-timezone-tools +-By default, timezone related utilities (@command{zic}, @command{zdump}, ++By default, time zone related utilities (@command{zic}, @command{zdump}, + and @command{tzselect}) are installed with @theglibc{}. If you are building + these independently (e.g. by using the @samp{tzcode} package), then this + option will allow disabling the install of these. +@@ -456,9 +456,9 @@ permissions on a pseudoterminal so it can be used by the calling process. + If you are using a Linux kernel with the @code{devpts} filesystem enabled + and mounted at @file{/dev/pts}, you don't need this program. + +-After installation you should configure the timezone and install locales +-for your system. The time zone configuration ensures that your system +-time matches the time for your current timezone. The locales ensure that ++After installation you should configure the time zone ruleset and install ++locales for your system. The time zone ruleset ensures that timestamps ++are processed correctly for your location. The locales ensure that + the display of information on your system matches the expectations of + your language and geographic region. + +@@ -481,12 +481,12 @@ as files in the default configured locale installation directory (derived from + root use @samp{DESTDIR} e.g.@: @samp{make localedata/install-locale-files + DESTDIR=/opt/glibc}, but note that this does not change the configured prefix. + +-To configure the locally used timezone, set the @code{TZ} environment ++To configure the time zone ruleset, set the @code{TZ} environment + variable. The script @code{tzselect} helps you to select the right value. + As an example, for Germany, @code{tzselect} would tell you to use + @samp{TZ='Europe/Berlin'}. For a system wide installation (the given + paths are for an installation with @samp{--prefix=/usr}), link the +-timezone file which is in @file{/usr/share/zoneinfo} to the file ++time zone file which is in @file{/usr/share/zoneinfo} to the file + @file{/etc/localtime}. For Germany, you might execute @samp{ln -s + /usr/share/zoneinfo/Europe/Berlin /etc/localtime}. + +diff --git a/manual/startup.texi b/manual/startup.texi +index 1426f5e1abfb2f51..c421563d16979c64 100644 +--- a/manual/startup.texi ++++ b/manual/startup.texi +@@ -567,8 +567,7 @@ Manual}) use the @code{TERM} environment variable, for example. + @item TZ + @cindex @code{TZ} environment variable + +-This specifies the time zone. @xref{TZ Variable}, for information about +-the format of this string and how it is used. ++This specifies the time zone ruleset. @xref{TZ Variable}. + + @item LANG + @cindex @code{LANG} environment variable +diff --git a/manual/time.texi b/manual/time.texi +index 2e029975b952ac29..ab5063be81cf0af9 100644 +--- a/manual/time.texi ++++ b/manual/time.texi +@@ -26,18 +26,22 @@ Discussing time in a technical manual can be difficult because the word + we use a rigorous terminology to avoid confusion, and the only thing we + use the simple word ``time'' for is to talk about the abstract concept. + +-A @dfn{calendar time} is a point in the time continuum, for example +-November 4, 1990, at 18:02.5 UTC. Sometimes this is called ``absolute +-time''. ++A @dfn{calendar time}, sometimes called ``absolute time'', ++is a point in the Earth's time continuum, for example ++June 9, 2024, at 13:50:06.5 Coordinated Universal Time (UTC)@. + @cindex calendar time ++UTC, formerly called Greenwich Mean Time, is the primary time ++standard on Earth, and is the basis for civil time and time zones. ++@cindex Coordinated Universal Time ++@cindex UTC + + We don't speak of a ``date'', because that is inherent in a calendar + time. + @cindex date + + An @dfn{interval} is a contiguous part of the time continuum between two +-calendar times, for example the hour between 9:00 and 10:00 on July 4, +-1980. ++calendar times, for example the hour on June 9, 2024, ++between 13:00 and 14:00 UTC. + @cindex interval + + An @dfn{elapsed time} is the length of an interval, for example, 35 +@@ -85,6 +89,16 @@ easier for people to understand, but more difficult to calculate with. + @cindex Gregorian calendar + @cindex calendar, Gregorian + ++A @dfn{time zone} is a single fixed offset from UTC, along with ++a @dfn{time zone abbreviation} that is a string of characters ++that can include ASCII alphanumerics, @samp{+}, and @samp{-}. ++For example, the current time zone in Japan is ++9 hours ahead (east) of the Prime Meridian with abbreviation @t{"JST"}. ++ ++A @dfn{time zone ruleset} maps each simple calendar time to a single ++time zone. For example, Paris's time zone ruleset might list over a ++dozen time zones that Paris has experienced during its history. ++ + @dfn{CPU time} measures the amount of time that a single process has + actively used a CPU to perform computations. It does not include the + time that process has spent waiting for external events. The system +@@ -132,16 +146,17 @@ and pass them to the functions that convert them to broken-down time + (@pxref{Broken-down Time}). + + On POSIX-conformant systems, @code{time_t} is an integer type and its +-values represent the number of seconds elapsed since the @dfn{epoch}, +-which is 00:00:00 on January 1, 1970, Coordinated Universal Time. ++values represent the number of seconds elapsed since the @dfn{POSIX Epoch}, ++which is January 1, 1970, at 00:00:00 Coordinated Universal Time (UTC)@. + The count of seconds ignores leap seconds. + + @Theglibc{} additionally guarantees that @code{time_t} is a signed + type, and that all of its functions operate correctly on negative +-@code{time_t} values, which are interpreted as times before the epoch. +-Functions like @code{localtime} assume the Gregorian calendar even +-though this is historically inaccurate for timestamps before the +-calendar was introduced or after the calendar will become obsolete. ++@code{time_t} values, which are interpreted as times before the POSIX Epoch. ++Functions like @code{localtime} assume the Gregorian calendar and UTC ++even though this is historically inaccurate for dates before 1582, ++for times before 1960, and for timestamps after the Gregorian calendar ++and UTC will become obsolete. + @cindex epoch + @Theglibc{} also supports leap seconds as an option, in which case + @code{time_t} counts leap seconds instead of ignoring them. +@@ -226,7 +241,7 @@ a value of type @code{double}. + + On POSIX-conformant systems, the advantage of using + @samp{difftime (@var{end}, @var{begin})} over @samp{@var{end} - @var{begin}} +-is that it will produce the mathematically correct result even if ++is that it will not overflow even if + @var{end} and @var{begin} are so far apart that a simple subtraction + would overflow. However, if they are so far apart that a @code{double} + cannot exactly represent the difference, the result will be inexact. +@@ -237,13 +252,13 @@ would be the only way to compute their difference. + @end deftypefun + + @Theglibc{} does not provide any functions for computing the +-difference between two values of type @w{@code{struct timeval}} or +-@w{@code{struct timespec}}. Here is the recommended way to do this +-calculation by hand. It works even on some peculiar operating systems ++difference between two values of type @w{@code{struct timespec}} or ++@w{@code{struct timeval}}. Here is one way to do this ++calculation by hand. It works even on peculiar operating systems + where the @code{tv_sec} member has an unsigned type. + + @smallexample +-@include timeval_subtract.c.texi ++@include timespec_subtract.c.texi + @end smallexample + + @node Processor And CPU Time +@@ -252,7 +267,7 @@ where the @code{tv_sec} member has an unsigned type. + If you're trying to optimize your program or measure its efficiency, + it's very useful to know how much processor time it uses. For that, + calendar time and elapsed times are useless because a process may spend +-time waiting for I/O or for other processes to use the CPU. However, ++time waiting for I/O or for other processes to use the CPU@. However, + you can get the information with the functions in this section. + + CPU time (@pxref{Time Basics}) is represented by the data type +@@ -267,12 +282,16 @@ time before and after the computation. + @cindex clock ticks + @cindex ticks, clock + ++@defvr Macro CLOCKS_PER_SEC ++@standards{ISO, time.h} ++The number of clock ticks per second. ++@end defvr ++ + On @gnulinuxhurdsystems{}, @code{clock_t} is equivalent to @code{long int} and + @code{CLOCKS_PER_SEC} is an integer value. But in other systems, both + @code{clock_t} and the macro @code{CLOCKS_PER_SEC} can be either integer +-or floating-point types. Casting CPU time values to @code{double}, as +-in the example above, makes sure that operations such as arithmetic and +-printing work properly and consistently no matter what the underlying ++or floating-point types. Converting CPU time values to @code{double} ++can help code be more portable no matter what the underlying + representation is. + + Note that the clock can wrap around. On a 32bit system with +@@ -434,8 +453,8 @@ manipulating calendar times. + * Formatting Calendar Time:: Converting times to strings. + * Parsing Date and Time:: Convert textual time and date information back + into broken-down time values. +-* TZ Variable:: How users specify the time zone. +-* Time Zone Functions:: Functions to examine or specify the time zone. ++* TZ Variable:: How users specify the time zone ruleset. ++* Time Zone State:: Time zone state variables. + * Time Functions Example:: An example program showing use of some of + the time functions. + @end menu +@@ -464,30 +483,30 @@ This function cannot fail. + + Some applications need more precise timekeeping than is possible with + a @code{time_t} alone. Some applications also need more control over +-what is meant by ``the current time.'' For these applications, POSIX +-provides a function @code{clock_gettime} that can retrieve the time ++what is meant by ``the current time.'' For these applications, ++POSIX and @w{ISO C} provide functions to retrieve the time + with up to nanosecond precision, from a variety of different clocks. + Clocks can be system-wide, measuring time the same for all processes; + or they can be per-process or per-thread, measuring CPU time consumed + by a particular process, or some other similar resource. Each clock +-has its own resolution and epoch. You can find the resolution of a +-clock with the function @code{clock_getres}. There is no function to ++has its own resolution and epoch. POSIX and @w{ISO C} also provide functions ++for finding the resolution of a clock. There is no function to + get the epoch for a clock; either it is fixed and documented, or the + clock is not meant to be used to measure absolute times. + + @deftp {Data Type} clockid_t + @standards{POSIX.1, time.h} + The type @code{clockid_t} is used for constants that indicate which of +-several system clocks one wishes to use. ++several POSIX system clocks one wishes to use. + @end deftp + +-All systems that support this family of functions will define at least ++All systems that support the POSIX functions will define at least + this clock constant: + + @deftypevr Macro clockid_t CLOCK_REALTIME + @standards{POSIX.1, time.h} +-This clock uses the POSIX epoch, 00:00:00 on January 1, 1970, Coordinated +-Universal Time. It is close to, but not necessarily in lock-step with, the ++This POSIX clock uses the POSIX Epoch, 1970-01-01 00:00:00 UTC@. ++It is close to, but not necessarily in lock-step with, the + clocks of @code{time} (above) and of @code{gettimeofday} (below). + @end deftypevr + +@@ -499,7 +518,7 @@ measurements are not affected by changes to the system clock. + + @deftypevr Macro clockid_t CLOCK_MONOTONIC + @standards{POSIX.1, time.h} +-System-wide clock that continuously measures the advancement of ++This system-wide POSIX clock continuously measures the advancement of + calendar time, ignoring discontinuous changes to the system's + setting for absolute calendar time. + +@@ -509,7 +528,7 @@ Therefore, @code{CLOCK_MONOTONIC} cannot be used to measure + absolute time, only elapsed time. + @end deftypevr + +-Systems may support more than just these two clocks. ++Systems may support more than just these two POSIX clocks. + + @deftypefun int clock_gettime (clockid_t @var{clock}, struct timespec *@var{ts}) + @standards{POSIX.1, time.h} +@@ -552,15 +571,45 @@ The clock identified by @var{clock} is not supported. + @end table + @end deftypefun + +-These functions, and the constants that identify particular clocks, +-are declared in @file{time.h}. +- + @strong{Portability Note:} On some systems, including systems that use + older versions of @theglibc{}, programs that use @code{clock_gettime} + or @code{clock_setres} must be linked with the @code{-lrt} library. + This has not been necessary with @theglibc{} since version 2.17. + +-@Theglibc{} also provides an older, but still widely used, function ++The following @w{ISO C} macros and functions for higher-resolution ++timestamps were standardized more recently than the POSIX functions, ++so they are less portable to older POSIX systems. However, the @w{ISO ++C} functions are portable to C platforms that do not support POSIX. ++ ++@deftypevr Macro int TIME_UTC ++@standards{ISO, time.h} ++This is a positive integer constant designating a simple calendar time base. ++In @theglibc{} and other POSIX systems, ++this is equivalent to the POSIX @code{CLOCK_REALTIME} clock. ++On non-POSIX systems, though, the epoch is implementation-defined. ++@end deftypevr ++ ++Systems may support more than just this @w{ISO C} clock. ++ ++@deftypefun int timespec_get (struct timespec *@var{ts}, int @var{base}) ++@standards{ISO, time.h} ++Store into @code{*@var{ts}} the current time according to the @w{ISO ++C} time @var{base}. ++ ++The return value is @var{base} on success and @code{0} on failure. ++@end deftypefun ++ ++@deftypefun int timespec_getres (struct timespec *@var{res}, int @var{base}) ++@standards{ISO, time.h} ++If @var{ts} is non-null, store into @code{*@var{ts}} the resolution of ++the time provided by @code{timespec_get} function for the @w{ISO C} ++time @var{base}. ++ ++The return value is @var{base} on success and @code{0} on failure. ++@end deftypefun ++ ++The previous functions, data types and constants are declared in @file{time.h}. ++@Theglibc{} also provides an older function + for getting the current time with a resolution of microseconds. This + function is declared in @file{sys/time.h}. + +@@ -577,15 +626,15 @@ On some historic systems, if @var{tzp} was not a null pointer, + information about a system-wide time zone would be written to + @code{*@var{tzp}}. This feature is obsolete and not supported on + @gnusystems{}. You should always supply a null pointer for this +-argument. Instead, use the facilities described in @ref{Time Zone +-Functions} and in @ref{Broken-down Time} for working with time zones. ++argument. Instead, use the facilities described in ++@ref{Broken-down Time} for working with time zones. + + This function cannot fail, and its return value is always @code{0}. + +-@strong{Portability Note:} As of the 2008 revision of POSIX, this +-function is considered obsolete. @Theglibc{} will continue to provide +-this function indefinitely, but new programs should use +-@code{clock_gettime} instead. ++@strong{Portability Note:} POSIX.1-2024 removed this function. ++Although @theglibc{} will continue to provide it indefinitely, ++portable programs should use @code{clock_gettime} or ++@code{timespec_get} instead. + @end deftypefun + + @node Setting and Adjusting the Time +@@ -613,7 +662,7 @@ privileges), but the @code{CLOCK_MONOTONIC} clock cannot. + Because simple calendar times are independent of time zone, this + function should not be used when the time zone changes (e.g.@: if the + computer is physically moved from one zone to another). Instead, use +-the facilities described in @ref{Time Zone Functions}. ++the facilities described in @ref{Time Zone State}. + + @code{clock_settime} causes the clock to jump forwards or backwards, + which can cause a variety of problems. Changing the +@@ -761,7 +810,7 @@ system clock. The value is expressed in microseconds. + + @item long int tolerance + This value represents the maximum frequency error of the system clock in +-scaled PPM. This value is used to increase the @code{maxerror} every ++scaled PPM@. This value is used to increase the @code{maxerror} every + second. + + @item struct timeval time +@@ -845,7 +894,7 @@ The process specified a settings update, but is not superuser. + + @end table + +-For more details see RFC1305 (Network Time Protocol, Version 3) and ++For more details see @w{RFC 5905} (Network Time Protocol, Version 4) and + related documents. + + @strong{Portability note:} Early versions of @theglibc{} did not +@@ -869,7 +918,7 @@ wait longer for the time to become correct. + The @var{delta} argument specifies a relative adjustment to be made to + the clock time. If negative, the system clock is slowed down for a + while until it has lost this much elapsed time. If positive, the system +-clock is speeded up for a while. ++clock is sped up for a while. + + If the @var{olddelta} argument is not a null pointer, the @code{adjtime} + function returns information about any previous time adjustment that +@@ -933,9 +982,9 @@ same as calling @w{@samp{clock_settime (CLOCK_REALTIME)}}, except that + the new time can only be set to a precision of one microsecond. + + When @var{tzp} is not a null pointer, the data it points to @emph{may} +-be used to set a system-wide idea of the current timezone. This ++be used to set a system-wide idea of the current time zone. This + feature is obsolete and not supported on @gnusystems{}. Instead, use +-the facilities described in @ref{Time Zone Functions} and in ++the facilities described in @ref{Time Zone State} and in + @ref{Broken-down Time} for working with time zones. + + The return value is @code{0} on success and @code{-1} on failure. The +@@ -966,8 +1015,8 @@ Simple calendar times represent absolute times as elapsed times since + an epoch. This is convenient for computation, but has no relation to + the way people normally think of calendar time. By contrast, + @dfn{broken-down time} is a binary representation of calendar time +-separated into year, month, day, and so on. Broken-down time values +-are not useful for calculations, but they are useful for printing ++separated into year, month, day, and so on. Although broken-down time ++values are painful to calculate with, they are useful for printing + human readable time information. + + A broken-down time value is always relative to a choice of time +@@ -1018,27 +1067,34 @@ This is the number of full days since the beginning of the year (in the + range @code{0} through @code{365}). + + @item int tm_isdst +-@cindex Daylight Saving Time ++@cindex daylight saving time + @cindex summer time +-This is a flag that indicates whether Daylight Saving Time is (or was, or ++This is a flag that indicates whether daylight saving time is (or was, or + will be) in effect at the time described. The value is positive if +-Daylight Saving Time is in effect, zero if it is not, and negative if the ++daylight saving time is in effect, zero if it is not, and negative if the + information is not available. ++Although this flag is useful when passing a broken-down time to the ++@code{mktime} function, for other uses this flag should be ignored and ++the @code{tm_gmtoff} and @code{tm_zone} fields should be inspected instead. + + @item long int tm_gmtoff + This field describes the time zone that was used to compute this + broken-down time value, including any adjustment for daylight saving; it + is the number of seconds that you must add to UTC to get local time. +-You can also think of this as the number of seconds east of UTC. For +-example, for U.S. Eastern Standard Time, the value is @code{-5*60*60}. +-The @code{tm_gmtoff} field is derived from BSD and is a GNU library +-extension; it is not visible in a strict @w{ISO C} environment. ++You can also think of this as the number of seconds east of the Prime Meridian. ++For example, for U.S. Eastern Standard Time, the value is @code{-5*60*60}. + + @item const char *tm_zone + This field is the abbreviation for the time zone that was used to compute this +-broken-down time value. Like @code{tm_gmtoff}, this field is a BSD and +-GNU extension, and is not visible in a strict @w{ISO C} environment. ++broken-down time value. + @end table ++ ++@strong{Portability note:} The @code{tm_gmtoff} and @code{tm_zone} fields ++are derived from BSD and are POSIX extensions to @w{ISO C}@. ++Code intended to be portable to operating systems that lack ++these fields can instead use time zone state variables, although ++those variables are unreliable when the @env{TZ} environment variable ++has a geographical format. @xref{Time Zone State}. + @end deftp + + +@@ -1053,21 +1109,24 @@ The @code{localtime} function converts the simple time pointed to by + user's specified time zone. + + The return value is a pointer to a static broken-down time structure, which +-might be overwritten by subsequent calls to @code{ctime}, @code{gmtime}, +-or @code{localtime}. (But no other library function overwrites the contents +-of this object.) ++might be overwritten by subsequent calls to @code{gmtime} ++or @code{localtime}. (No other library function overwrites the contents ++of this object.) In @theglibc{}, the structure's @code{tm_zone} ++points to a string with a storage lifetime that lasts indefinitely; ++on other platforms, the lifetime may expire when the @env{TZ} ++environment variable is changed. + + The return value is the null pointer if @var{time} cannot be represented + as a broken-down time; typically this is because the year cannot fit into + an @code{int}. + +-Calling @code{localtime} also sets the current time zone as if +-@code{tzset} were called. @xref{Time Zone Functions}. ++Calling @code{localtime} also sets the time zone state as if ++@code{tzset} were called. @xref{Time Zone State}. + @end deftypefun + + Using the @code{localtime} function is a big problem in multi-threaded + programs. The result is returned in a static buffer and this is used in +-all threads. POSIX.1c introduced a variant of this function. ++all threads. A variant function avoids this problem. + + @deftypefun {struct tm *} localtime_r (const time_t *@var{time}, struct tm *@var{resultp}) + @standards{POSIX.1c, time.h} +@@ -1158,7 +1217,8 @@ and converts it to the broken-down time format. + + But the result is not placed in a static buffer. Instead it is placed + in the object of type @code{struct tm} to which the parameter +-@var{resultp} points. ++@var{resultp} points. Also, the time zone state is not necessarily ++set as if @code{tzset} were called. + + If the conversion is successful the function returns a pointer to the + object the result was written into, i.e., it returns @var{resultp}. +@@ -1171,13 +1231,14 @@ object the result was written into, i.e., it returns @var{resultp}. + @c gmtime @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd + @c tz_convert dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd + This function is similar to @code{localtime}, except that the broken-down +-time is expressed as Coordinated Universal Time (UTC) (formerly called +-Greenwich Mean Time (GMT)) rather than relative to a local time zone. ++time is expressed as UTC rather than relative to a local time zone. ++The broken-down time's @code{tm_gmtoff} is 0, and its ++@code{tm_zone} is a string @t{"UTC"} with static storage duration. + + @end deftypefun + + As for the @code{localtime} function we have the problem that the result +-is placed in a static variable. POSIX.1c also provides a replacement for ++is placed in a static variable. A thread-safe replacement is also provided for + @code{gmtime}. + + @deftypefun {struct tm *} gmtime_r (const time_t *@var{time}, struct tm *@var{resultp}) +@@ -1192,7 +1253,7 @@ is placed in a static variable. POSIX.1c also provides a replacement for + @c gmtime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd + @c tz_convert(gmtime_r) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd + This function is similar to @code{localtime_r}, except that it converts +-just like @code{gmtime} the given time as Coordinated Universal Time. ++just like @code{gmtime} the given time as UTC. + + If the conversion is successful the function returns a pointer to the + object the result was written into, i.e., it returns @var{resultp}. +@@ -1242,10 +1303,10 @@ If the specified broken-down time cannot be represented as a simple time, + @code{mktime} returns a value of @code{(time_t)(-1)} and does not modify + the contents of @var{brokentime}. + +-Calling @code{mktime} also sets the current time zone as if ++Calling @code{mktime} also sets the time zone state as if + @code{tzset} were called; @code{mktime} uses this information instead + of @var{brokentime}'s initial @code{tm_gmtoff} and @code{tm_zone} +-members. @xref{Time Zone Functions}. ++members. @xref{Time Zone State}. + @end deftypefun + + @deftypefun time_t timelocal (struct tm *@var{brokentime}) +@@ -1263,7 +1324,7 @@ available. @code{timelocal} is rather rare. + @end deftypefun + + @deftypefun time_t timegm (struct tm *@var{brokentime}) +-@standards{???, time.h} ++@standards{ISO, time.h} + @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} + @c timegm @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd + @c gmtime_offset triggers the same caveats as localtime_offset in mktime. +@@ -1279,16 +1340,16 @@ available. @code{timelocal} is rather rare. + @c tzfile_compute(!use_localtime) ok + + @code{timegm} is functionally identical to @code{mktime} except it +-always takes the input values to be Coordinated Universal Time (UTC) ++always takes the input values to be UTC + regardless of any local time zone setting. + + Note that @code{timegm} is the inverse of @code{gmtime}. + + @strong{Portability note:} @code{mktime} is essentially universally +-available. @code{timegm} is rather rare. For the most portable +-conversion from a UTC broken-down time to a simple time, set +-the @code{TZ} environment variable to UTC, call @code{mktime}, then set +-@code{TZ} back. ++available. Although @code{timegm} is standardized by C23, some ++other systems lack it; to be portable to them, you can set ++the @env{TZ} environment variable to UTC, call @code{mktime}, then set ++@env{TZ} back. + + @end deftypefun + +@@ -1301,89 +1362,6 @@ The functions described in this section format calendar time values as + strings. These functions are declared in the header file @file{time.h}. + @pindex time.h + +-@deftypefun {char *} asctime (const struct tm *@var{brokentime}) +-@standards{ISO, time.h} +-@safety{@prelim{}@mtunsafe{@mtasurace{:asctime} @mtslocale{}}@asunsafe{}@acsafe{}} +-@c asctime @mtasurace:asctime @mtslocale +-@c Uses a static buffer. +-@c asctime_internal @mtslocale +-@c snprintf dup @mtslocale [no @acsuheap @acsmem] +-@c ab_day_name @mtslocale +-@c ab_month_name @mtslocale +-The @code{asctime} function converts the broken-down time value that +-@var{brokentime} points to into a string in a standard format: +- +-@smallexample +-"Tue May 21 13:46:22 1991\n" +-@end smallexample +- +-The abbreviations for the days of week are: @samp{Sun}, @samp{Mon}, +-@samp{Tue}, @samp{Wed}, @samp{Thu}, @samp{Fri}, and @samp{Sat}. +- +-The abbreviations for the months are: @samp{Jan}, @samp{Feb}, +-@samp{Mar}, @samp{Apr}, @samp{May}, @samp{Jun}, @samp{Jul}, @samp{Aug}, +-@samp{Sep}, @samp{Oct}, @samp{Nov}, and @samp{Dec}. +- +-The return value points to a statically allocated string, which might be +-overwritten by subsequent calls to @code{asctime} or @code{ctime}. +-(But no other library function overwrites the contents of this +-string.) +-@end deftypefun +- +-@deftypefun {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer}) +-@standards{POSIX.1c, time.h} +-@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +-@c asctime_r @mtslocale +-@c asctime_internal dup @mtslocale +-This function is similar to @code{asctime} but instead of placing the +-result in a static buffer it writes the string in the buffer pointed to +-by the parameter @var{buffer}. This buffer should have room +-for at least 26 bytes, including the terminating null. +- +-If no error occurred the function returns a pointer to the string the +-result was written into, i.e., it returns @var{buffer}. Otherwise +-it returns @code{NULL}. +-@end deftypefun +- +- +-@deftypefun {char *} ctime (const time_t *@var{time}) +-@standards{ISO, time.h} +-@safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtasurace{:asctime} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +-@c ctime @mtasurace:tmbuf @mtasurace:asctime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +-@c localtime dup @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +-@c asctime dup @mtasurace:asctime @mtslocale +-The @code{ctime} function is similar to @code{asctime}, except that you +-specify the calendar time argument as a @code{time_t} simple time value +-rather than in broken-down local time format. It is equivalent to +- +-@smallexample +-asctime (localtime (@var{time})) +-@end smallexample +- +-Calling @code{ctime} also sets the current time zone as if +-@code{tzset} were called. @xref{Time Zone Functions}. +-@end deftypefun +- +-@deftypefun {char *} ctime_r (const time_t *@var{time}, char *@var{buffer}) +-@standards{POSIX.1c, time.h} +-@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +-@c ctime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +-@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +-@c asctime_r dup @mtslocale +-This function is similar to @code{ctime}, but places the result in the +-string pointed to by @var{buffer}. It is equivalent to (written using +-gcc extensions, @pxref{Statement Exprs,,,gcc,Porting and Using gcc}): +- +-@smallexample +-(@{ struct tm tm; asctime_r (localtime_r (time, &tm), buf); @}) +-@end smallexample +- +-If no error occurred the function returns a pointer to the string the +-result was written into, i.e., it returns @var{buffer}. Otherwise +-it returns @code{NULL}. +-@end deftypefun +- +- + @deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime}) + @standards{ISO, time.h} + @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} +@@ -1445,10 +1423,10 @@ it returns @code{NULL}. + @c tm_diff ok + This function is similar to the @code{sprintf} function (@pxref{Formatted + Input}), but the conversion specifications that can appear in the format +-template @var{template} are specialized for printing components of the date +-and time @var{brokentime} according to the locale currently specified for ++template @var{template} are specialized for printing components of ++@var{brokentime} according to the locale currently specified for + time conversion (@pxref{Locales}) and the current time zone +-(@pxref{Time Zone Functions}). ++(@pxref{Time Zone State}). + + Ordinary characters appearing in the @var{template} are copied to the + output string @var{s}; this can include multibyte character sequences. +@@ -1484,8 +1462,7 @@ the result is written right adjusted and space padded to the given + size. + + An optional modifier can follow the optional flag and width +-specification. The modifiers, which were first standardized by +-POSIX.2-1992 and by @w{ISO C99}, are: ++specification. The modifiers are: + + @table @code + @item E +@@ -1553,51 +1530,36 @@ If the @code{E} modifier is specified (@code{%EC}), instead produces + the name of the period for the year (e.g.@: an era name) in the + locale's alternative calendar. + +-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. +- + @item %d + The day of the month as a decimal number (range @code{01} through @code{31}). + + @item %D + The date using the format @code{%m/%d/%y}. + +-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. +- + @item %e + The day of the month like with @code{%d}, but padded with spaces (range + @code{ 1} through @code{31}). + +-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. +- + @item %F + The date using the format @code{%Y-%m-%d}. This is the form specified + in the @w{ISO 8601} standard and is the preferred form for all uses. + +-This format was first standardized by @w{ISO C99} and by POSIX.1-2001. +- + @item %g + The year corresponding to the ISO week number, but without the century + (range @code{00} through @code{99}). This has the same format and value + as @code{%y}, except that if the ISO week number (see @code{%V}) belongs + to the previous or next year, that year is used instead. + +-This format was first standardized by @w{ISO C99} and by POSIX.1-2001. +- + @item %G + The year corresponding to the ISO week number. This has the same format + and value as @code{%Y}, except that if the ISO week number (see + @code{%V}) belongs to the previous or next year, that year is used + instead. + +-This format was first standardized by @w{ISO C99} and by POSIX.1-2001 +-but was previously available as a GNU extension. +- + @item %h + The abbreviated month name according to the current locale. The action + is the same as for @code{%b}. + +-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. +- + @item %H + The hour as a decimal number, using a 24-hour clock (range @code{00} through + @code{23}). +@@ -1630,13 +1592,11 @@ The minute as a decimal number (range @code{00} through @code{59}). + @item %n + A single @samp{\n} (newline) character. + +-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. +- + @item %p + Either @samp{AM} or @samp{PM}, according to the given time value; or the + corresponding strings for the current locale. Noon is treated as + @samp{PM} and midnight as @samp{AM}. In most locales +-@samp{AM}/@samp{PM} format is not supported, in such cases @code{"%p"} ++@samp{AM}/@samp{PM} format is not supported, in such cases @t{"%p"} + yields an empty string. + + @ignore +@@ -1648,24 +1608,21 @@ Either @samp{am} or @samp{pm}, according to the given time value; or the + corresponding strings for the current locale, printed in lowercase + characters. Noon is treated as @samp{pm} and midnight as @samp{am}. In + most locales @samp{AM}/@samp{PM} format is not supported, in such cases +-@code{"%P"} yields an empty string. ++@t{"%P"} yields an empty string. + + This format is a GNU extension. + + @item %r + The complete calendar time using the AM/PM format of the current locale. + +-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. + In the POSIX locale, this format is equivalent to @code{%I:%M:%S %p}. + + @item %R + The hour and minute in decimal numbers using the format @code{%H:%M}. + +-This format was first standardized by @w{ISO C99} and by POSIX.1-2001 +-but was previously available as a GNU extension. +- + @item %s +-The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. ++The number of seconds since the POSIX Epoch, ++i.e., since 1970-01-01 00:00:00 UTC@. + Leap seconds are not counted unless leap second support is available. + + This format is a GNU extension. +@@ -1676,19 +1633,13 @@ The seconds as a decimal number (range @code{00} through @code{60}). + @item %t + A single @samp{\t} (tabulator) character. + +-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. +- + @item %T + The time of day using decimal numbers using the format @code{%H:%M:%S}. + +-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. +- + @item %u + The day of the week as a decimal number (range @code{1} through + @code{7}), Monday being @code{1}. + +-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. +- + @item %U + The week number of the current year as a decimal number (range @code{00} + through @code{53}), starting with the first Sunday as the first day of +@@ -1696,7 +1647,7 @@ the first week. Days preceding the first Sunday in the year are + considered to be in week @code{00}. + + @item %V +-The @w{ISO 8601:1988} week number as a decimal number (range @code{01} ++The @w{ISO 8601} week number as a decimal number (range @code{01} + through @code{53}). ISO weeks start with Monday and end with Sunday. + Week @code{01} of a year is the first week which has the majority of its + days in that year; this is equivalent to the week containing the year's +@@ -1706,8 +1657,6 @@ The week before week @code{01} of a year is the last week (@code{52} or + @code{53}) of the previous year even if it contains days from the new + year. + +-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. +- + @item %w + The day of the week as a decimal number (range @code{0} through + @code{6}), Sunday being @code{0}. +@@ -1747,16 +1696,13 @@ extension, the formatting flags @code{_} or @code{-} may be used with + this conversion specifier; they affect how the year number is printed. + + @item %z +-@w{RFC 822}/@w{ISO 8601:1988} style numeric time zone (e.g., ++@w{RFC 5322}/@w{ISO 8601} style numeric time zone (e.g., + @code{-0600} or @code{+0100}), or nothing if no time zone is + determinable. + +-This format was first standardized by @w{ISO C99} and by POSIX.1-2001 +-but was previously available as a GNU extension. +- +-In the POSIX locale, a full @w{RFC 822} timestamp is generated by the format +-@w{@samp{"%a, %d %b %Y %H:%M:%S %z"}} (or the equivalent +-@w{@samp{"%a, %d %b %Y %T %z"}}). ++In the POSIX locale, a full @w{RFC 5322} timestamp is generated by the format ++@w{@t{"%a, %d %b %Y %H:%M:%S %z"}} (or the equivalent ++@w{@t{"%a, %d %b %Y %T %z"}}). + + @item %Z + The time zone abbreviation (empty if the time zone can't be determined). +@@ -1779,7 +1725,7 @@ format strings and certain locales the output really can be the empty + string and this cannot be discovered by testing the return value only. + E.g., in most locales the AM/PM time format is not supported (most of + the world uses the 24 hour time representation). In such locales +-@code{"%p"} will return the empty string, i.e., the return value is ++@t{"%p"} will return the empty string, i.e., the return value is + zero. To detect situations like this something similar to the following + code should be used: + +@@ -1796,16 +1742,22 @@ if (len == 0 && buf[0] != '\0') + If @var{s} is a null pointer, @code{strftime} does not actually write + anything, but instead returns the number of characters it would have written. + +-Calling @code{strftime} also sets the current time zone as if +-@code{tzset} were called; @code{strftime} uses this information +-instead of @var{brokentime}'s @code{tm_gmtoff} and @code{tm_zone} +-members. @xref{Time Zone Functions}. ++Calling @code{strftime} also sets the time zone state as if ++@code{tzset} were called. @xref{Time Zone State}. + + For an example of @code{strftime}, see @ref{Time Functions Example}. + @end deftypefun + ++@deftypefun size_t strftime_l (char *restrict @var{s}, size_t @var{size}, const char *restrict @var{template}, const struct tm *@var{brokentime}, locale_t @var{locale}) ++@standards{POSIX.1, time.h} ++@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} ++The @code{strftime_l} function is equivalent to the @code{strftime} ++function except that it operates in @var{locale} rather than in ++the current locale. ++@end deftypefun ++ + @deftypefun size_t wcsftime (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, const struct tm *@var{brokentime}) +-@standards{ISO/Amend1, time.h} ++@standards{ISO, time.h} + @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} + @c wcsftime @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd + @c wcsftime_l @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@@ -1875,6 +1827,114 @@ can be placed in the buffer @var{s} the return value is zero, with the + same problems indicated in the @code{strftime} documentation. + @end deftypefun + ++@deftypefun {Deprecated function} {char *} asctime (const struct tm *@var{brokentime}) ++@standards{ISO, time.h} ++@safety{@prelim{}@mtunsafe{@mtasurace{:asctime} @mtslocale{}}@asunsafe{}@acsafe{}} ++@c asctime @mtasurace:asctime @mtslocale ++@c Uses a static buffer. ++@c asctime_internal @mtslocale ++@c snprintf dup @mtslocale [no @acsuheap @acsmem] ++@c ab_day_name @mtslocale ++@c ab_month_name @mtslocale ++The @code{asctime} function converts the broken-down time value that ++@var{brokentime} points to into a string in a standard format: ++ ++@smallexample ++"Tue May 21 13:46:22 1991\n" ++@end smallexample ++ ++The abbreviations for the days of week are: @samp{Sun}, @samp{Mon}, ++@samp{Tue}, @samp{Wed}, @samp{Thu}, @samp{Fri}, and @samp{Sat}. ++ ++The abbreviations for the months are: @samp{Jan}, @samp{Feb}, ++@samp{Mar}, @samp{Apr}, @samp{May}, @samp{Jun}, @samp{Jul}, @samp{Aug}, ++@samp{Sep}, @samp{Oct}, @samp{Nov}, and @samp{Dec}. ++ ++Behavior is undefined if the calculated year would be less than 1000 ++or greater than 9999. ++ ++The return value points to a statically allocated string, which might be ++overwritten by subsequent calls to @code{asctime} or @code{ctime}. ++(No other library function overwrites the contents of this ++string.) ++ ++@strong{Portability note:} ++This obsolescent function is deprecated in C23. ++Programs should instead use @code{strftime} or even @code{sprintf}. ++@end deftypefun ++ ++@deftypefun {Deprecated function} {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer}) ++@standards{???, time.h} ++@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} ++@c asctime_r @mtslocale ++@c asctime_internal dup @mtslocale ++This function is similar to @code{asctime} but instead of placing the ++result in a static buffer it writes the string in the buffer pointed to ++by the parameter @var{buffer}. This buffer should have room ++for at least 26 bytes, including the terminating null. ++Behavior is undefined if the calculated year would be less than 1000 ++or greater than 9999. ++ ++If no error occurred the function returns a pointer to the string the ++result was written into, i.e., it returns @var{buffer}. Otherwise ++it returns @code{NULL}. ++ ++@strong{Portability Note:} ++POSIX.1-2024 removed this obsolescent function. ++Programs should instead use @code{strftime} or even @code{sprintf}. ++@end deftypefun ++ ++@deftypefun {Deprecated function} {char *} ctime (const time_t *@var{time}) ++@standards{ISO, time.h} ++@safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtasurace{:asctime} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} ++@c ctime @mtasurace:tmbuf @mtasurace:asctime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd ++@c localtime dup @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd ++@c asctime dup @mtasurace:asctime @mtslocale ++The @code{ctime} function is similar to @code{asctime}, except that you ++specify the calendar time argument as a @code{time_t} simple time value ++rather than in broken-down local time format. It is equivalent to ++ ++@smallexample ++asctime (localtime (@var{time})) ++@end smallexample ++ ++Behavior is undefined if the calculated year would be less than 1000 ++or greater than 9999. ++ ++Calling @code{ctime} also sets the time zone state as if ++@code{tzset} were called. @xref{Time Zone State}. ++ ++@strong{Portability note:} ++This obsolescent function is deprecated in C23. ++Programs should instead use @code{strftime} or even @code{sprintf}. ++@end deftypefun ++ ++@deftypefun {Deprecated function} {char *} ctime_r (const time_t *@var{time}, char *@var{buffer}) ++@standards{???, time.h} ++@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} ++@c ctime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd ++@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd ++@c asctime_r dup @mtslocale ++This function is similar to @code{ctime}, but places the result in the ++string pointed to by @var{buffer}, and the time zone state is not ++necessarily set as if @code{tzset} were called. It is equivalent to: ++ ++@smallexample ++asctime_r (localtime_r (@var{time}, &(struct tm) @{0@}), @var{buffer}) ++@end smallexample ++ ++Behavior is undefined if the calculated year would be less than 1000 ++or greater than 9999. ++ ++If no error occurred the function returns a pointer to the string the ++result was written into, i.e., it returns @var{buffer}. Otherwise ++it returns @code{NULL}. ++ ++@strong{Portability Note:} ++POSIX.1-2024 removed this obsolescent function. ++Programs should instead use @code{strftime} or even @code{sprintf}. ++@end deftypefun ++ + @node Parsing Date and Time + @subsection Convert textual time and date information back + +@@ -1934,13 +1994,13 @@ structure @var{tp}. + + The input string could be generated by a @code{strftime} call or + obtained any other way. It does not need to be in a human-recognizable +-format; e.g. a date passed as @code{"02:1999:9"} is acceptable, even ++format; e.g. a date passed as @t{"02:1999:9"} is acceptable, even + though it is ambiguous without context. As long as the format string + @var{fmt} matches the input string the function will succeed. + + The user has to make sure, though, that the input can be parsed in a +-unambiguous way. The string @code{"1999112"} can be parsed using the +-format @code{"%Y%m%d"} as 1999-1-12, 1999-11-2, or even 19991-1-2. It ++unambiguous way. The string @t{"1999112"} can be parsed using the ++format @t{"%Y%m%d"} as 1999-1-12, 1999-11-2, or even 19991-1-2. It + is necessary to add appropriate separators to reliably get results. + + The format string consists of the same components as the format string +@@ -2074,7 +2134,7 @@ Same as @code{%M} but using the locale's alternative numeric symbols. + + @item %n + @itemx %t +-Matches any white space. ++Matches any whitespace. + + @item %p + @item %P +@@ -2098,7 +2158,8 @@ The hour and minute in decimal numbers using the format @code{%H:%M}. + @code{%R} is a GNU extension following a GNU extension to @code{strftime}. + + @item %s +-The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. ++The number of seconds since the POSIX Epoch, ++i.e., since 1970-01-01 00:00:00 UTC@. + Leap seconds are not counted unless leap second support is available. + + @code{%s} is a GNU extension following a GNU extension to @code{strftime}. +@@ -2138,7 +2199,7 @@ Leading zeroes are permitted but not required. + Same as @code{%U} but using the locale's alternative numeric symbols. + + @item %V +-The @w{ISO 8601:1988} week number as a decimal number (range @code{1} ++The @w{ISO 8601} week number as a decimal number (range @code{1} + through @code{53}). + + Leading zeroes are permitted but not required. +@@ -2212,7 +2273,7 @@ The year as a decimal number, using the Gregorian calendar. + The full alternative year representation. + + @item %z +-The offset from GMT in @w{ISO 8601}/RFC822 format. ++The offset from UTC in @w{ISO 8601}/@w{RFC 5322} format. + + @item %Z + The time zone abbreviation. +@@ -2225,7 +2286,7 @@ A literal @samp{%} character. + @end table + + All other characters in the format string must have a matching character +-in the input string. Exceptions are white spaces in the input string ++in the input string. Exceptions are whitespace characters in the input string + which can match zero or more whitespace characters in the format string. + + @strong{Portability Note:} The XPG standard advises applications to use +@@ -2233,10 +2294,10 @@ at least one whitespace character (as specified by @code{isspace}) or + other non-alphanumeric characters between any two conversion + specifications. @Theglibc{} does not have this limitation but + other libraries might have trouble parsing formats like +-@code{"%d%m%Y%H%M%S"}. ++@t{"%d%m%Y%H%M%S"}. + + The @code{strptime} function processes the input string from right to +-left. Each of the three possible input elements (white space, literal, ++left. Each of the three possible input elements (whitespace, literal, + or format) are handled one after the other. If the input cannot be + matched to the format string the function stops. The remainder of the + format and input strings are not processed. +@@ -2312,8 +2373,8 @@ The Unix standard defines another function for parsing date strings. + The interface is weird, but if the function happens to suit your + application it is just fine. It is problematic to use this function + in multi-threaded programs or libraries, since it returns a pointer to +-a static variable, and uses a global variable and global state (an +-environment variable). ++a static variable, and uses a global variable and global state based ++on an environment variable. + + @defvar getdate_err + @standards{Unix98, time.h} +@@ -2322,9 +2383,9 @@ unsuccessful call to @code{getdate}. Defined values are: + + @table @math + @item 1 +-The environment variable @code{DATEMSK} is not defined or null. ++The environment variable @env{DATEMSK} is not defined or null. + @item 2 +-The template file denoted by the @code{DATEMSK} environment variable ++The template file denoted by the @env{DATEMSK} environment variable + cannot be opened. + @item 3 + Information about the template file cannot retrieved. +@@ -2355,7 +2416,7 @@ string and the result is returned in a statically-allocated variable. + The details about how the string is processed are hidden from the user. + In fact, they can be outside the control of the program. Which formats + are recognized is controlled by the file named by the environment +-variable @code{DATEMSK}. This file should contain ++variable @env{DATEMSK}. This file should contain + lines of valid format strings which could be passed to @code{strptime}. + + The @code{getdate} function reads these format strings one after the +@@ -2372,7 +2433,7 @@ extensions to the @code{strptime} behavior: + @itemize @bullet + @item + If the @code{%Z} format is given the broken-down time is based on the +-current time of the timezone matched, not of the current timezone of the ++current time of the time zone matched, not of the current time zone of the + runtime environment. + + @emph{Note}: This is not implemented (currently). The problem is that +@@ -2451,7 +2512,7 @@ description above for a list of the possible error values. + + @emph{Warning:} The @code{getdate} function should @emph{never} be + used in SUID-programs. The reason is obvious: using the +-@code{DATEMSK} environment variable you can get the function to open ++@env{DATEMSK} environment variable you can get the function to open + any arbitrary file and chances are high that with some bogus input + (such as a binary file) the program will crash. + @end deftypefun +@@ -2500,71 +2561,174 @@ The warning against using @code{getdate} in SUID-programs applies to + @end deftypefun + + @node TZ Variable +-@subsection Specifying the Time Zone with @code{TZ} ++@subsection Specifying the Time Zone with @env{TZ} + + In POSIX systems, a user can specify the time zone by means of the +-@code{TZ} environment variable. For information about how to set ++@env{TZ} environment variable. For information about how to set + environment variables, see @ref{Environment Variables}. The functions + for accessing the time zone are declared in @file{time.h}. + @pindex time.h + @cindex time zone + +-You should not normally need to set @code{TZ}. If the system is ++You should not normally need to set @env{TZ}. If the system is + configured properly, the default time zone will be correct. You might +-set @code{TZ} if you are using a computer over a network from a ++set @env{TZ} if you are using a computer over a network from a + different time zone, and would like times reported to you in the time + zone local to you, rather than what is local to the computer. + +-In POSIX.1 systems the value of the @code{TZ} variable can be in one of +-three formats. With @theglibc{}, the most common format is the +-last one, which can specify a selection from a large database of time +-zone information for many regions of the world. The first two formats +-are used to describe the time zone information directly, which is both +-more cumbersome and less precise. But the POSIX.1 standard only +-specifies the details of the first two formats, so it is good to be +-familiar with them in case you come across a POSIX.1 system that doesn't +-support a time zone information database. ++The value of @env{TZ} can be in one of the following formats: + +-The first format is used when there is no Daylight Saving Time (or +-summer time) in the local time zone: ++@itemize ++@item ++The @dfn{geographical format} specifies a location that stands for ++the past and future time zones observed in that location. ++@xref{Geographical TZ}. ++Here are some examples: + + @smallexample +-@r{@var{std} @var{offset}} ++Asia/Tokyo ++America/New_York ++/usr/share/zoneinfo/America/Nuuk + @end smallexample + +-The @var{std} string specifies the time zone abbreviation. It must be +-three or more characters long and must not contain a leading colon, +-embedded digits, commas, nor plus and minus signs. There is no space ++@item ++The @dfn{proleptic format} represents a time zone that has always ++been and always will be the same offset from UTC, ++optionally with a simple daylight saving scheme that has always been ++(and always will be) used every year. ++@xref{Proleptic TZ}. ++Here are some examples: ++ ++@smallexample ++JST-9 ++EST+5EDT,M3.2.0/2,M11.1.0/2 ++<-02>+2<-01>,M3.5.0/-1,M10.5.0/0 ++@end smallexample ++ ++@item ++The @dfn{colon format} begins with @samp{:}. Here is an example. ++ ++@smallexample ++:/etc/localtime ++@end smallexample ++ ++@noindent ++Each operating system can interpret this format differently; ++in @theglibc{}, the @samp{:} is ignored and @var{characters} ++are treated as if they specified the geographical or proleptic format. ++ ++@item ++As an extension to POSIX, when the value of @env{TZ} is the empty string, ++@theglibc{} uses UTC. ++@end itemize ++ ++@pindex /etc/localtime ++@pindex localtime ++If the @env{TZ} environment variable does not have a value, the ++implementation chooses a time zone by default. In @theglibc{}, the ++default time zone is like the specification @samp{TZ=/etc/localtime} ++(or @samp{TZ=/usr/local/etc/localtime}, depending on how @theglibc{} ++was configured; @pxref{Installation}). Other C libraries use their own ++rule for choosing the default time zone, so there is little we can say ++about them. ++ ++@menu ++* Geographical TZ:: @env{TZ} settings like @samp{America/New_York}. ++* Proleptic TZ:: @env{TZ} settings like @samp{EST+5EDT,M3.2.0/2,M11.1.0/2}. ++@end menu ++ ++@node Geographical TZ ++@subsubsection Geographical Format for @env{TZ} ++ ++The geographical format names a time zone ruleset maintained by the ++@url{http://www.iana.org/time-zones, ++Time Zone Database} of time zone and daylight saving time ++information for most regions of the world. ++This public-domain database is maintained by a community of volunteers. ++@cindex time zone database ++@pindex /usr/share/zoneinfo ++@pindex zoneinfo ++ ++If the format's @var{characters} begin with @samp{/} ++it is an absolute file name; ++otherwise the library looks for the file ++@w{@file{/usr/share/zoneinfo/@var{characters}}}. The @file{zoneinfo} ++directory contains data files describing time zone rulesets in many ++different parts of the world. The names represent major cities, with ++subdirectories for geographical areas; for example, ++@file{America/New_York}, @file{Europe/London}, @file{Asia/Tokyo}. ++These data files are installed by the system administrator, who also ++sets @file{/etc/localtime} to point to the data file for the local time ++zone ruleset. ++ ++If the file corresponding to @var{characters} cannot be read or has ++invalid data, and @var{characters} are not in the proleptic format, ++then @theglibc{} silently defaults to UTC@. However, applications ++should not depend on this, as @env{TZ} formats may be extended in the ++future. ++ ++@node Proleptic TZ ++@subsubsection Proleptic Format for @env{TZ} ++ ++Although the proleptic format is cumbersome and inaccurate for old timestamps, ++POSIX.1-2017 and earlier specified details only for the proleptic format, ++and you may need to use it on small systems that lack a time zone ++information database. ++ ++The proleptic format is: ++ ++@smallexample ++@r{@var{std}@var{offset}[@var{dst}[@var{offset}][@t{,}@var{start}[@t{/}@var{time}]@t{,}@var{end}[@t{/}@var{time}]]]} ++@end smallexample ++ ++The @var{std} string specifies the time zone abbreviation, ++which must be at least three bytes long, ++and which can appear in unquoted or quoted form. ++The unquoted form can contain only ASCII alphabetic characters. ++The quoted form can also contain ASCII digits, @samp{+}, and @samp{-}; ++it is quoted by surrounding it by @samp{<} and @samp{>}, ++which are not part of the abbreviation. There is no space + character separating the time zone abbreviation from the @var{offset}, so these + restrictions are necessary to parse the specification correctly. + + The @var{offset} specifies the time value you must add to the local time +-to get a Coordinated Universal Time value. It has syntax like +-[@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]]. This +-is positive if the local time zone is west of the Prime Meridian and +-negative if it is east. The hour must be between @code{0} and +-@code{24}, and the minute and seconds between @code{0} and @code{59}. +- +-For example, here is how we would specify Eastern Standard Time, but +-without any Daylight Saving Time alternative: ++to get a UTC value. It has syntax like: + + @smallexample +-EST+5 ++[@t{+}|@t{-}]@var{hh}[@t{:}@var{mm}[@t{:}@var{ss}]] + @end smallexample + +-The second format is used when there is Daylight Saving Time: ++@noindent ++This ++is positive if the local time zone is west of the Prime Meridian and ++negative if it is east; this is opposite from the usual convention ++that positive time zone offsets are east of the Prime Meridian. ++The hour @var{hh} must be between 0 and 24 ++and may be a single digit, and the minutes @var{mm} and seconds ++@var{ss}, if present, must be between 0 and 59. ++ ++For example, to specify time in Panama, which is Eastern Standard Time ++without any daylight saving time alternative: + + @smallexample +-@r{@var{std} @var{offset} @var{dst} [@var{offset}]@code{,}@var{start}[@code{/}@var{time}]@code{,}@var{end}[@code{/}@var{time}]} ++EST+5 + @end smallexample + ++When daylight saving time is used, the proleptic format is more complicated. + The initial @var{std} and @var{offset} specify the standard time zone, as + described above. The @var{dst} string and @var{offset} are the abbreviation +-and offset for the corresponding Daylight Saving Time zone; if the ++and offset for the corresponding daylight saving time zone; if the + @var{offset} is omitted, it defaults to one hour ahead of standard time. + +-The remainder of the specification describes when Daylight Saving Time is +-in effect. The @var{start} field is when Daylight Saving Time goes into ++The remainder of the proleptic format, which starts with the first comma, ++describes when daylight saving time is in effect. This remainder is ++optional and if omitted, @theglibc{} defaults to the daylight saving ++rules that would be used if @env{TZ} had the value @t{"posixrules"}. ++However, other POSIX implementations default to different daylight ++saving rules, so portable @env{TZ} settings should not omit the ++remainder. ++ ++In the remainder, the @var{start} field is when daylight saving time goes into + effect and the @var{end} field is when the change is made back to standard + time. The following formats are recognized for these fields: + +@@ -2587,132 +2751,67 @@ between @code{1} and @code{12}. + @end table + + The @var{time} fields specify when, in the local time currently in +-effect, the change to the other time occurs. If omitted, the default is +-@code{02:00:00}. The hours part of the time fields can range from +-@minus{}167 through 167; this is an extension to POSIX.1, which allows +-only the range 0 through 24. +- +-Here are some example @code{TZ} values, including the appropriate +-Daylight Saving Time and its dates of applicability. In North +-American Eastern Standard Time (EST) and Eastern Daylight Time (EDT), ++effect, the change to the other time occurs. They have the same ++format as @var{offset} except the hours part can range from ++@minus{}167 through 167; for example, @code{-22:30} stands for 01:30 ++the previous day and @code{25:30} stands for 01:30 the next day. If ++omitted, @var{time} defaults to @code{02:00:00}. ++ ++Here are example @env{TZ} values with daylight saving time rules. ++ ++@table @samp ++@item EST+5EDT,M3.2.0/2,M11.1.0/2 ++In North American Eastern Standard Time (EST) and Eastern Daylight Time (EDT), + the normal offset from UTC is 5 hours; since this is +-west of the prime meridian, the sign is positive. Summer time begins on ++west of the Prime Meridian, the sign is positive. Summer time begins on + March's second Sunday at 2:00am, and ends on November's first Sunday + at 2:00am. + +-@smallexample +-EST+5EDT,M3.2.0/2,M11.1.0/2 +-@end smallexample +- ++@item IST-2IDT,M3.4.4/26,M10.5.0 + Israel Standard Time (IST) and Israel Daylight Time (IDT) are 2 hours + ahead of the prime meridian in winter, springing forward an hour on + March's fourth Thursday at 26:00 (i.e., 02:00 on the first Friday on or + after March 23), and falling back on October's last Sunday at 02:00. + +-@smallexample +-IST-2IDT,M3.4.4/26,M10.5.0 +-@end smallexample +- +-Western Argentina Summer Time (WARST) is 3 hours behind the prime +-meridian all year. There is a dummy fall-back transition on December +-31 at 25:00 daylight saving time (i.e., 24:00 standard time, +-equivalent to January 1 at 00:00 standard time), and a simultaneous +-spring-forward transition on January 1 at 00:00 standard time, so +-daylight saving time is in effect all year and the initial @code{WART} +-is a placeholder. ++@item IST-1GMT0,M10.5.0,M3.5.0/1 ++Irish Standard Time (IST) is 1 hour behind the Prime Meridian in ++summer, falling forward to Greenwich Mean Time (GMT, the Prime ++Meridian's time), on October's last Sunday at 00:00 and springing back ++on March's last Sunday at 01:00. This is an example of ``negative ++daylight saving''; here, daylight saving time is one hour west of ++standard time instead of the more usual one hour east. + +-@smallexample +-WART4WARST,J1/0,J365/25 +-@end smallexample +- +-Western Greenland Time (WGT) and Western Greenland Summer Time (WGST) +-are 3 hours behind UTC in the winter. Its clocks follow the European ++@item <-02>+2<-01>,M3.5.0/-1,M10.5.0/0 ++Most of Greenland is 2 hours behind UTC in winter. Clocks follow the European + Union rules of springing forward by one hour on March's last Sunday at +-01:00 UTC (@minus{}02:00 local time) and falling back on October's +-last Sunday at 01:00 UTC (@minus{}01:00 local time). +- +-@smallexample +-WGT3WGST,M3.5.0/-2,M10.5.0/-1 +-@end smallexample ++01:00 UTC (@minus{}01:00 local time) and falling back on October's ++last Sunday at 01:00 UTC (00:00 local time). ++The numeric abbreviations @samp{-02} and @samp{-01} stand ++for standard and daylight saving time, respectively. ++@end table + +-The schedule of Daylight Saving Time in any particular jurisdiction has ++The schedule of daylight saving time in any particular jurisdiction has + changed over the years. To be strictly correct, the conversion of dates + and times in the past should be based on the schedule that was in effect +-then. However, this format has no facilities to let you specify how the ++then. However, the proleptic format does not let you specify how the + schedule has changed from year to year. The most you can do is specify + one particular schedule---usually the present day schedule---and this is + used to convert any date, no matter when. For precise time zone +-specifications, it is best to use the time zone information database +-(see below). +- +-The third format looks like this: +- +-@smallexample +-:@var{characters} +-@end smallexample +- +-Each operating system interprets this format differently; in +-@theglibc{}, @var{characters} is the name of a file which describes the time +-zone. +- +-@pindex /etc/localtime +-@pindex localtime +-If the @code{TZ} environment variable does not have a value, the +-operation chooses a time zone by default. In @theglibc{}, the +-default time zone is like the specification @samp{TZ=:/etc/localtime} +-(or @samp{TZ=:/usr/local/etc/localtime}, depending on how @theglibc{} +-was configured; @pxref{Installation}). Other C libraries use their own +-rule for choosing the default time zone, so there is little we can say +-about them. +- +-@cindex time zone database +-@pindex /usr/share/zoneinfo +-@pindex zoneinfo +-If @var{characters} begins with a slash, it is an absolute file name; +-otherwise the library looks for the file +-@w{@file{/usr/share/zoneinfo/@var{characters}}}. The @file{zoneinfo} +-directory contains data files describing local time zones in many +-different parts of the world. The names represent major cities, with +-subdirectories for geographical areas; for example, +-@file{America/New_York}, @file{Europe/London}, @file{Asia/Hong_Kong}. +-These data files are installed by the system administrator, who also +-sets @file{/etc/localtime} to point to the data file for the local time +-zone. The files typically come from the @url{http://www.iana.org/time-zones, +-Time Zone Database} of time zone and daylight saving time +-information for most regions of the world, which is maintained by a +-community of volunteers and put in the public domain. +- +-@node Time Zone Functions +-@subsection Functions and Variables for Time Zones +- +-@deftypevar {char *} tzname [2] +-@standards{POSIX.1, time.h} +-The array @code{tzname} contains two strings, which are the standard +-abbreviations of the pair of time zones (standard and Daylight +-Saving) that the user has selected. @code{tzname[0]} abbreviates +-the standard time zone (for example, @code{"EST"}), and @code{tzname[1]} +-abbreviates the time zone when Daylight Saving Time is in use (for +-example, @code{"EDT"}). These correspond to the @var{std} and @var{dst} +-strings (respectively) from the @code{TZ} environment variable. If +-Daylight Saving Time is never used, @code{tzname[1]} is the empty string. +- +-The @code{tzname} array is initialized from the @code{TZ} environment +-variable whenever @code{tzset}, @code{ctime}, @code{strftime}, +-@code{mktime}, or @code{localtime} is called. If multiple abbreviations +-have been used (e.g. @code{"EWT"} and @code{"EDT"} for U.S. Eastern War +-Time and Eastern Daylight Time), the array contains the most recent +-abbreviation. +- +-The @code{tzname} array is required for POSIX.1 compatibility, but in +-GNU programs it is better to use the @code{tm_zone} member of the +-broken-down time structure, since @code{tm_zone} reports the correct +-abbreviation even when it is not the latest one. +- +-Though the strings are declared as @code{char *} the user must refrain +-from modifying these strings. Modifying the strings will almost certainly +-lead to trouble. +- +-@end deftypevar ++specifications, it is best to use the geographical format. ++@xref{Geographical TZ}. ++ ++@node Time Zone State ++@subsection State Variables for Time Zones ++ ++For compatibility with POSIX, @theglibc{} defines global state ++variables that depend on time zone rules specified by the @env{TZ} ++environment variable. However, these state variables are obsolescent ++and are planned to be removed in a future version of POSIX, ++and programs generally should avoid them because they are not ++thread-safe and their values are specified only when @env{TZ} uses the ++proleptic format. @xref{TZ Variable}. ++Programs should instead use the @code{tm_gmtoff} and ++@code{tm_zone} members of @code{struct tm}. @xref{Broken-down Time}. + + @deftypefun void tzset (void) + @standards{POSIX.1, time.h} +@@ -2721,34 +2820,64 @@ lead to trouble. + @c libc_lock_lock dup @asulock @aculock + @c tzset_internal dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd + @c libc_lock_unlock dup @aculock +-The @code{tzset} function initializes the @code{tzname} variable from +-the value of the @code{TZ} environment variable. It is not usually +-necessary for your program to call this function, because it is called +-automatically when you use the other time conversion functions that +-depend on the time zone. ++The @code{tzset} function initializes the state variables from ++the value of the @env{TZ} environment variable. ++It is not usually necessary for your program to call this function, ++partly because your program should not use the state variables, ++and partly because this function is called automatically ++when you use the time conversion functions @code{localtime}, ++@code{mktime}, @code{strftime}, @code{strftime_l}, and ++@code{wcsftime}, or the deprecated function @code{ctime}. ++Behavior is undefined if one thread accesses any of these variables directly ++while another thread is calling @code{tzset} or any other function ++that is required or allowed to behave as if it called @code{tzset}. + @end deftypefun + +-The following variables are defined for compatibility with System V +-Unix. Like @code{tzname}, these variables are set by calling +-@code{tzset} or the other time conversion functions. ++@deftypevar {char *} tzname [2] ++@standards{POSIX.1, time.h} ++The array @code{tzname} contains two strings, which are ++abbreviations of time zones (standard and Daylight ++Saving) that the user has selected. @code{tzname[0]} abbreviates ++a standard time zone (for example, @t{"EST"}), and @code{tzname[1]} ++abbreviates a time zone when daylight saving time is in use (for ++example, @t{"EDT"}). These correspond to the @var{std} and @var{dst} ++strings (respectively) when the @env{TZ} environment variable ++uses the proleptic format. ++The string values are unspecified if @env{TZ} uses the geographical format, ++so it is generally better to use the broken-down time structure's ++@code{tm_zone} member instead. ++ ++In @theglibc{}, the strings have a storage lifetime that lasts indefinitely; ++on some other platforms, the lifetime lasts only until @env{TZ} is changed. ++ ++The @code{tzname} array is initialized by @code{tzset}. ++Though the strings are declared as @code{char *} ++the user must refrain from modifying them. ++Modifying the strings will almost certainly lead to trouble. ++ ++@end deftypevar + + @deftypevar {long int} timezone +-@standards{SVID, time.h} +-This contains the difference between UTC and the latest local standard +-time, in seconds west of UTC. For example, in the U.S. Eastern time ++@standards{POSIX.1, time.h} ++This contains the difference between UTC and local standard ++time, in seconds west of the Prime Meridian. ++For example, in the U.S. Eastern time + zone, the value is @code{5*60*60}. Unlike the @code{tm_gmtoff} member + of the broken-down time structure, this value is not adjusted for +-daylight saving, and its sign is reversed. In GNU programs it is better +-to use @code{tm_gmtoff}, since it contains the correct offset even when +-it is not the latest one. ++daylight saving, and its sign is reversed. ++The value is unspecified if @env{TZ} uses the geographical format, ++so it is generally better to use the broken-down time structure's ++@code{tm_gmtoff} member instead. + @end deftypevar + + @deftypevar int daylight +-@standards{SVID, time.h} +-This variable has a nonzero value if Daylight Saving Time rules apply. +-A nonzero value does not necessarily mean that Daylight Saving Time is +-now in effect; it means only that Daylight Saving Time is sometimes in +-effect. ++@standards{POSIX.1, time.h} ++ ++This variable is nonzero if daylight saving time rules apply. ++A nonzero value does not necessarily mean that daylight saving time is ++now in effect; it means only that daylight saving time is sometimes in effect. ++This variable has little or no practical use; ++it is present for POSIX compatibility. + @end deftypevar + + @node Time Functions Example +@@ -2764,9 +2893,9 @@ functions. + It produces output like this: + + @smallexample +-Wed Jul 31 13:02:36 1991 +-Today is Wednesday, July 31. +-The time is 01:02 PM. ++2024-06-09 13:50:06 ++Today is Sunday, June 09. ++The time is 01:50 PM. + @end smallexample + + +@@ -2955,7 +3084,7 @@ amount of delay involved. + + @strong{Portability Note:} The @code{setitimer} and @code{getitimer} + functions are derived from BSD Unix, while the @code{alarm} function is +-specified by the POSIX.1 standard. @code{setitimer} is more powerful than ++specified by POSIX@. @code{setitimer} is more powerful than + @code{alarm}, but @code{alarm} is more widely used. + + @node Sleeping +diff --git a/time/localtime.c b/time/localtime.c +index 8bf916fd6ddbe92c..77d19ff5e718fdc7 100644 +--- a/time/localtime.c ++++ b/time/localtime.c +@@ -18,7 +18,10 @@ + + #include + +-/* The C Standard says that localtime and gmtime return the same pointer. */ ++/* C89 says that localtime and gmtime return the same pointer. ++ Although C99 and later relax this to let localtime and gmtime ++ return different pointers, POSIX and glibc currently follow C89's stricter ++ requirement even though this can cause naive programs to misbehave. */ + struct tm _tmbuf; + + diff --git a/glibc-RHEL-108974-20.patch b/glibc-RHEL-108974-20.patch new file mode 100644 index 0000000..f94124f --- /dev/null +++ b/glibc-RHEL-108974-20.patch @@ -0,0 +1,144 @@ +commit 6c9bb270d6a624f82a38443545e3d99f5b1e07e1 +Author: Florian Weimer +Date: Fri May 16 16:47:02 2025 +0200 + + manual: Clarifications for listing directories + + Support for seeking is limited. Using the d_off and d_reclen members + of struct dirent is discouraged, especially with readdir. Concurrent + modification of directories during iteration may result in duplicate + or missing etnries. + +diff --git a/manual/filesys.texi b/manual/filesys.texi +index aabb68385b6b9732..450d175e614d8834 100644 +--- a/manual/filesys.texi ++++ b/manual/filesys.texi +@@ -409,18 +409,41 @@ entries. It contains the following fields: + This is the null-terminated file name component. This is the only + field you can count on in all POSIX systems. + ++While this field is defined with a specified length, functions such as ++@code{readdir} may return a pointer to a @code{struct dirent} where the ++@code{d_name} extends beyond the end of the struct. ++ + @item ino_t d_fileno + This is the file serial number. For BSD compatibility, you can also + refer to this member as @code{d_ino}. On @gnulinuxhurdsystems{} and most POSIX + systems, for most files this the same as the @code{st_ino} member that + @code{stat} will return for the file. @xref{File Attributes}. + ++@item off_t d_off ++This value contains the offset of the next directory entry (after this ++entry) in the directory stream. The value may not be compatible with ++@code{lseek} or @code{seekdir}, especially if the width of @code{d_off} ++is less than 64 bits. Directory entries are not ordered by offset, and ++the @code{d_off} and @code{d_reclen} values are unrelated. Seeking on ++directory streams is not recommended. The symbol ++@code{_DIRENT_HAVE_D_OFF} is defined if the @code{d_ino} member is ++available. ++ + @item unsigned char d_namlen + This is the length of the file name, not including the terminating + null character. Its type is @code{unsigned char} because that is the + integer type of the appropriate size. This member is a BSD extension. + The symbol @code{_DIRENT_HAVE_D_NAMLEN} is defined if this member is +-available. ++available. (It is not available on Linux.) ++ ++@item unsigned short int d_reclen ++This is the length of the entire directory record. When iterating ++through a buffer filled by @code{getdents64} (@pxref{Low-level Directory ++Access}), this value needs to be added to the offset of the current ++directory entry to obtain the offset of the next entry. When using ++@code{readdir} and related functions, the value of @code{d_reclen} is ++undefined and should not be accessed. The symbol ++@code{_DIRENT_HAVE_D_RECLEN} is defined if this member is available. + + @item unsigned char d_type + This is the type of the file, possibly unknown. The following constants +@@ -457,7 +480,7 @@ This member is a BSD extension. The symbol @code{_DIRENT_HAVE_D_TYPE} + is defined if this member is available. On systems where it is used, it + corresponds to the file type bits in the @code{st_mode} member of + @code{struct stat}. If the value cannot be determined the member +-value is DT_UNKNOWN. These two macros convert between @code{d_type} ++value is @code{DT_UNKNOWN}. These two macros convert between @code{d_type} + values and @code{st_mode} values: + + @deftypefun int IFTODT (mode_t @var{mode}) +@@ -632,6 +655,20 @@ and can be rewritten by a subsequent call. + return entries for @file{.} and @file{..}, even though these are always + valid file names in any directory. @xref{File Name Resolution}. + ++If a directory is modified between a call to @code{readdir} and after ++the directory stream was created or @code{rewinddir} was last called on ++it, it is unspecified according to POSIX whether newly created or ++removed entries appear among the entries returned by repeated ++@code{readdir} calls before the end of the directory is reached. ++However, due to practical implementation constraints, it is possible ++that entries (including unrelated, unmodified entries) appear multiple ++times or do not appear at all if the directory is modified while listing ++it. If the application intends to create files in the directory, it may ++be necessary to complete the iteration first and create a copy of the ++information obtained before creating any new files. (See below for ++instructions regarding copying of @code{d_name}.) The iteration can be ++restarted using @code{rewinddir}. @xref{Random Access Directory}. ++ + If there are no more entries in the directory or an error is detected, + @code{readdir} returns a null pointer. The following @code{errno} error + conditions are defined for this function: +@@ -812,6 +849,10 @@ directory since it was opened with @code{opendir}. (Entries for these + files might or might not be returned by @code{readdir} if they were + added or removed since you last called @code{opendir} or + @code{rewinddir}.) ++ ++For example, it is recommended to call @code{rewinddir} followed by ++@code{readdir} to check if a directory is empty after listing it with ++@code{readdir} and deleting all encountered files from it. + @end deftypefun + + @deftypefun {long int} telldir (DIR *@var{dirstream}) +@@ -823,6 +864,13 @@ added or removed since you last called @code{opendir} or + The @code{telldir} function returns the file position of the directory + stream @var{dirstream}. You can use this value with @code{seekdir} to + restore the directory stream to that position. ++ ++Using the the @code{telldir} function is not recommended. ++ ++The value returned by @code{telldir} may not be compatible with the ++@code{d_off} field in @code{struct dirent}, and cannot be used with the ++@code{lseek} function. The returned value may not unambiguously ++identify the position in the directory stream. + @end deftypefun + + @deftypefun void seekdir (DIR *@var{dirstream}, long int @var{pos}) +@@ -836,6 +884,9 @@ stream @var{dirstream} to @var{pos}. The value @var{pos} must be the + result of a previous call to @code{telldir} on this particular stream; + closing and reopening the directory can invalidate values returned by + @code{telldir}. ++ ++Using the the @code{seekdir} function is not recommended. To seek to ++the beginning of the directory stream, use @code{rewinddir}. + @end deftypefun + + +@@ -1007,9 +1058,20 @@ Note that some file systems support file names longer than + @code{NAME_MAX} bytes (e.g., because they support up to 255 Unicode + characters), so a buffer size of at least 1024 is recommended. + ++If the directory has been modified since the first call to ++@code{getdents64} on the directory (opening the descriptor or seeking to ++offset zero), it is possible that the buffer contains entries that have ++been encountered before. Likewise, it is possible that files that are ++still present are not reported before the end of the directory is ++encountered (and @code{getdents64} returns zero). ++ + This function is specific to Linux. + @end deftypefun + ++Systems that support @code{getdents64} support seeking on directory ++streams. @xref{File Position Primitive}. However, the only offset that ++works reliably is offset zero, indicating that reading the directory ++should start from the beginning. + + @node Working with Directory Trees + @section Working with Directory Trees diff --git a/glibc-RHEL-108974-21.patch b/glibc-RHEL-108974-21.patch new file mode 100644 index 0000000..cbcf694 --- /dev/null +++ b/glibc-RHEL-108974-21.patch @@ -0,0 +1,67 @@ +commit 43afae31e0d7579deef13536c4c3704afaa017da +Author: Maciej W. Rozycki +Date: Thu May 29 22:11:38 2025 +0100 + + manual: Document error codes missing for 'socket' + + Add missing EAFNOSUPPORT, ESOCKTNOSUPPORT, EPROTOTYPE, EINVAL, EPERM, + and ENOMEM error codes, and adjust existing descriptions accordingly. + + On Linux either ENOBUFS or ENOMEM is returned in the case of a memory + allocation failure, depending on the namespace requested, e.g. AF_INET + returns ENOMEM while AF_INET6 returns ENOBUFS, so document these codes + as alternatives. + + Similarly EPERM is returned rather than EACCES on Linux, so document + these codes as alternatives as well. We might want to convert EPERM to + EACCES for POSIX compliance, but it is beyond the scope of this change, + and software has to expect either anyway, owing to the long-established + practice. + + Finally ESOCKTNOSUPPORT is returned rather than EPROTONOSUPPORT for an + unsupported style except for the AF_QIPCRTR namespace where EPROTOTYPE + is used, so document these codes as alternatives too. + + Reviewed-by: Florian Weimer + +diff --git a/manual/socket.texi b/manual/socket.texi +index 8708cbb07ca02b5c..ed24cd5bd41ce8c0 100644 +--- a/manual/socket.texi ++++ b/manual/socket.texi +@@ -2205,9 +2205,19 @@ socket, or @code{-1} in case of error. The following @code{errno} error + conditions are defined for this function: + + @table @code ++@item EAFNOSUPPORT ++The @var{namespace} requested is not supported. ++ ++@item ESOCKTNOSUPPORT ++@itemx EPROTONOSUPPORT ++@itemx EPROTOTYPE ++The @var{style} is not supported by the @var{namespace} specified. ++ + @item EPROTONOSUPPORT +-The @var{protocol} or @var{style} is not supported by the +-@var{namespace} specified. ++The @var{protocol} is not supported by the @var{namespace} specified. ++ ++@item EINVAL ++The @var{style} or @var{protocol} requested is not valid. + + @item EMFILE + The process already has too many file descriptors open. +@@ -2216,11 +2226,13 @@ The process already has too many file descriptors open. + The system already has too many file descriptors open. + + @item EACCES ++@itemx EPERM + The process does not have the privilege to create a socket of the specified + @var{style} or @var{protocol}. + + @item ENOBUFS +-The system ran out of internal buffer space. ++@itemx ENOMEM ++Insufficient memory was available. + @end table + + The file descriptor returned by the @code{socket} function supports both diff --git a/glibc-RHEL-108974-22.patch b/glibc-RHEL-108974-22.patch new file mode 100644 index 0000000..8fac712 --- /dev/null +++ b/glibc-RHEL-108974-22.patch @@ -0,0 +1,36 @@ +commit 79b5febd762d6735ba8e878086a50ea04993e340 +Author: Maciej W. Rozycki +Date: Thu May 29 22:11:38 2025 +0100 + + manual: Document error codes missing for 'inet_ntop' + + Add documentation for EAFNOSUPPORT and ENOSPC error codes returned, and + the return value on failure. + + Reviewed-by: Florian Weimer + +diff --git a/manual/socket.texi b/manual/socket.texi +index ed24cd5bd41ce8c0..2f0e7509e92974d1 100644 +--- a/manual/socket.texi ++++ b/manual/socket.texi +@@ -1211,7 +1211,19 @@ network (binary) to presentation (textual) form. @var{af} should be + either @code{AF_INET} or @code{AF_INET6}, as appropriate. @var{cp} is a + pointer to the address to be converted. @var{buf} should be a pointer + to a buffer to hold the result, and @var{len} is the length of this +-buffer. The return value from the function will be this buffer address. ++buffer. ++ ++The return value is @var{buf} on success. On failure, the function's ++return value is a null pointer and @code{errno} is set accordingly. ++The following @code{errno} values are specific to this function: ++ ++@table @code ++@item EAFNOSUPPORT ++The address family requested is neither @code{AF_INET} nor @code{AF_INET6}. ++ ++@item ENOSPC ++Insufficient space available for the result in the buffer provided. ++@end table + @end deftypefun + + @node Host Names diff --git a/glibc-RHEL-108974-23.patch b/glibc-RHEL-108974-23.patch new file mode 100644 index 0000000..fac9b8c --- /dev/null +++ b/glibc-RHEL-108974-23.patch @@ -0,0 +1,23 @@ +commit 9a743032cd59c59167bf615d8ab4acc96b2bf47e +Author: Maciej W. Rozycki +Date: Fri May 30 15:01:51 2025 +0100 + + manual: Fix invalid 'illegal' usage with 'nanosleep' + + The GNU Coding Standards demand that 'illegal' only be used to refer to + activities prohibited by law. Replace it with 'invalid' accordingly in + the description of the EINVAL error condition for 'nanosleep'. + +diff --git a/manual/time.texi b/manual/time.texi +index 4dde875dde4d8075..e754d3a7e7f5c52d 100644 +--- a/manual/time.texi ++++ b/manual/time.texi +@@ -3212,7 +3212,7 @@ elapsed time. + + @item EINVAL + The nanosecond value in the @var{requested_time} parameter contains an +-illegal value. Either the value is negative or greater than or equal to ++invalid value. Either the value is negative or greater than or equal to + 1000 million. + @end table + diff --git a/glibc-RHEL-108974-24.patch b/glibc-RHEL-108974-24.patch new file mode 100644 index 0000000..834d182 --- /dev/null +++ b/glibc-RHEL-108974-24.patch @@ -0,0 +1,121 @@ +commit 1a3d8f2201d4d613401ce5be9a283f4f28c43093 +Author: Arjun Shankar +Date: Fri May 30 02:09:50 2025 +0200 + + manual: Document clock_nanosleep + + Make minor clarifications in the documentation for 'nanosleep' and add + an entry for 'clock_nanosleep' as a generalized variant of the former + function that allows clock selection. + Reviewed-by: Maciej W. Rozycki + +diff --git a/manual/time.texi b/manual/time.texi +index e754d3a7e7f5c52d..60e4d4b6fab1482b 100644 +--- a/manual/time.texi ++++ b/manual/time.texi +@@ -3179,12 +3179,12 @@ On @gnusystems{}, it is safe to use @code{sleep} and @code{SIGALRM} in + the same program, because @code{sleep} does not work by means of + @code{SIGALRM}. + +-@deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining}) ++@deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining_time}) + @standards{POSIX.1, time.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + @c On Linux, it's a syscall. On Mach, it calls gettimeofday and uses + @c ports. +-If resolution to seconds is not enough the @code{nanosleep} function can ++If resolution to seconds is not enough, the @code{nanosleep} function can + be used. As the name suggests the sleep interval can be specified in + nanoseconds. The actual elapsed time of the sleep interval might be + longer since the system rounds the elapsed time you request up to the +@@ -3193,21 +3193,22 @@ next integer multiple of the actual resolution the system can deliver. + @code{*@var{requested_time}} is the elapsed time of the interval you + want to sleep. + +-The function returns as @code{*@var{remaining}} the elapsed time left +-in the interval for which you requested to sleep. If the interval +-completed without getting interrupted by a signal, this is zero. ++If @var{remaining_time} is not the null pointer, the function returns as ++@code{*@var{remaining_time}} the elapsed time left in the interval for which ++you requested to sleep. If the interval completed without getting ++interrupted by a signal, this is zero. + + @code{struct timespec} is described in @ref{Time Types}. + +-If the function returns because the interval is over the return value is +-zero. If the function returns @math{-1} the global variable @code{errno} ++If the function returns because the interval is over, the return value is ++zero. If the function returns @math{-1}, the global variable @code{errno} + is set to the following values: + + @table @code + @item EINTR + The call was interrupted because a signal was delivered to the thread. +-If the @var{remaining} parameter is not the null pointer the structure +-pointed to by @var{remaining} is updated to contain the remaining ++If the @var{remaining_time} parameter is not the null pointer, the structure ++pointed to by @var{remaining_time} is updated to contain the remaining + elapsed time. + + @item EINVAL +@@ -3219,10 +3220,58 @@ invalid value. Either the value is negative or greater than or equal to + This function is a cancellation point in multi-threaded programs. This + is a problem if the thread allocates some resources (like memory, file + descriptors, semaphores or whatever) at the time @code{nanosleep} is +-called. If the thread gets canceled these resources stay allocated +-until the program ends. To avoid this calls to @code{nanosleep} should ++called. If the thread gets canceled, these resources stay allocated ++until the program ends. To avoid this, calls to @code{nanosleep} should + be protected using cancellation handlers. + @c ref pthread_cleanup_push / pthread_cleanup_pop + + The @code{nanosleep} function is declared in @file{time.h}. + @end deftypefun ++ ++@deftypefun int clock_nanosleep (clockid_t @var{clock}, int @var{flags}, const struct timespec *@var{requested_time}, struct timespec *@var{remaining_time}) ++@standards{POSIX.1-2001, time.h} ++@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} ++This function is a generalized variant of @code{nanosleep}, providing the ++caller with a way to specify the clock to be used to measure elapsed time ++and express the sleep interval in absolute or relative terms. The call: ++ ++@smallexample ++nanosleep (@var{requested_time}, @var{remaining_time}) ++@end smallexample ++ ++is equivalent to: ++ ++@smallexample ++clock_nanosleep (CLOCK_REALTIME, 0, @var{requested_time}, @var{remaining_time}) ++@end smallexample ++ ++The @var{clock} argument specifies the clock to use. ++@xref{Getting the Time}, for the @code{clockid_t} type and possible values ++of @var{clock}. Not all clocks listed are supported for use with ++@code{clock_nanosleep}. For details, see the manual page ++@manpageurl{clock_nanosleep,2}. ++ ++The @var{flags} argument is either @code{0} or @code{TIMER_ABSTIME}. If ++@var{flags} is @code{0}, then @code{clock_nanosleep} interprets ++@var{requested_time} as an interval relative to the current time specified ++by @var{clock}. If it is @code{TIMER_ABSTIME} instead, @var{requested_time} ++specifies an absolute time measured by @var{clock}; if at the time of the ++call the value requested is less than or equal to the clock specified, then ++the function returns right away. When @var{flags} is @code{TIMER_ABSTIME}, ++@var{remaining_time} is not updated. ++ ++The return values and error conditions for @code{clock_nanosleep} are the ++same as for @code{nanosleep}, with the following conditions additionally ++defined: ++ ++@table @code ++@item EINVAL ++The @var{clock} argument is not a valid clock. ++ ++@item EOPNOTSUPP ++The @var{clock} argument is not supported by the kernel for ++@code{clock_nanosleep}. ++@end table ++ ++The @code{clock_nanosleep} function is declared in @file{time.h}. ++@end deftypefun diff --git a/glibc-RHEL-108974-25.patch b/glibc-RHEL-108974-25.patch new file mode 100644 index 0000000..54b66c9 --- /dev/null +++ b/glibc-RHEL-108974-25.patch @@ -0,0 +1,74 @@ +commit 591283a68965fe61a7186c9c81f7812e71b282b4 +Author: Arjun Shankar +Date: Mon Jun 2 10:41:02 2025 +0200 + + manual: Correct return value description of 'clock_nanosleep' + + Commit 1a3d8f2201d4d613401ce5be9a283f4f28c43093 incorrectly described + 'clock_nanosleep' as having the same return values as 'nanosleep'. Fix + this, clarifying that 'clock_nanosleep' returns a positive error number + upon failure instead of setting 'errno'. Also clarify that 'nanosleep' + returns '-1' upon error. + + Fixes: 1a3d8f2201d4d613401ce5be9a283f4f28c43093 + Reported-by: Mark Harris + Reviewed-by: Mark Harris + +diff --git a/manual/time.texi b/manual/time.texi +index 60e4d4b6fab1482b..a7c276e1e4f074a6 100644 +--- a/manual/time.texi ++++ b/manual/time.texi +@@ -3200,9 +3200,9 @@ interrupted by a signal, this is zero. + + @code{struct timespec} is described in @ref{Time Types}. + +-If the function returns because the interval is over, the return value is +-zero. If the function returns @math{-1}, the global variable @code{errno} +-is set to the following values: ++If the function returns because the interval is over, it returns zero. ++Otherwise it returns @math{-1} and sets the global variable @code{errno} to ++one of the following values: + + @table @code + @item EINTR +@@ -3231,19 +3231,14 @@ The @code{nanosleep} function is declared in @file{time.h}. + @deftypefun int clock_nanosleep (clockid_t @var{clock}, int @var{flags}, const struct timespec *@var{requested_time}, struct timespec *@var{remaining_time}) + @standards{POSIX.1-2001, time.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +-This function is a generalized variant of @code{nanosleep}, providing the +-caller with a way to specify the clock to be used to measure elapsed time +-and express the sleep interval in absolute or relative terms. The call: +- +-@smallexample +-nanosleep (@var{requested_time}, @var{remaining_time}) +-@end smallexample +- +-is equivalent to: +- +-@smallexample +-clock_nanosleep (CLOCK_REALTIME, 0, @var{requested_time}, @var{remaining_time}) +-@end smallexample ++This function is similar to @code{nanosleep} while additionally providing ++the caller with a way to specify the clock to be used to measure elapsed ++time and express the sleep interval in absolute or relative terms. It ++returns zero when returning because the interval is over, and a positive ++error number corresponding to the error encountered otherwise. This is ++different from @code{nanosleep}, which returns @math{-1} upon failure and ++sets the global variable @code{errno} according to the error encountered ++instead. + + The @var{clock} argument specifies the clock to use. + @xref{Getting the Time}, for the @code{clockid_t} type and possible values +@@ -3260,9 +3255,9 @@ call the value requested is less than or equal to the clock specified, then + the function returns right away. When @var{flags} is @code{TIMER_ABSTIME}, + @var{remaining_time} is not updated. + +-The return values and error conditions for @code{clock_nanosleep} are the +-same as for @code{nanosleep}, with the following conditions additionally +-defined: ++The @code{clock_nanosleep} function returns error codes as positive return ++values. The error conditions for @code{clock_nanosleep} are the same as for ++@code{nanosleep}, with the following conditions additionally defined: + + @table @code + @item EINVAL diff --git a/glibc-RHEL-108974-26.patch b/glibc-RHEL-108974-26.patch new file mode 100644 index 0000000..e2d1a64 --- /dev/null +++ b/glibc-RHEL-108974-26.patch @@ -0,0 +1,47 @@ +commit 46acdf46cc1948187d6540cdf4abee5053cd8bcc +Author: Maciej W. Rozycki +Date: Wed Jun 4 16:27:20 2025 +0100 + + manual: Document error codes missing for 'if_indextoname' + + Add documentation for ENXIO error code returned and refer to 'socket' + for further possible codes from the underlying function call. + + While changing the text clarify the description by mentioning 'ifname' + and replace @code tags with @var ones where referring to a function + parameter. + + Reviewed-by: Florian Weimer + +diff --git a/manual/socket.texi b/manual/socket.texi +index 2f0e7509e92974d1..a6fb6b1b7e2b0473 100644 +--- a/manual/socket.texi ++++ b/manual/socket.texi +@@ -505,11 +505,22 @@ name. If no interface exists with the name given, it returns 0. + @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} + @c It opens a socket with opensock to use ioctl on the fd to get the + @c name from the index. +-This function maps an interface index to its corresponding name. The +-returned name is placed in the buffer pointed to by @code{ifname}, which +-must be at least @code{IFNAMSIZ} bytes in length. If the index was +-invalid, the function's return value is a null pointer, otherwise it is +-@code{ifname}. ++This function maps an interface index @var{ifindex} to its corresponding ++name. The returned name is placed in the buffer pointed to by @var{ifname}, ++which must be at least @code{IFNAMSIZ} bytes in length. ++ ++The return value is @var{ifname} on success. On failure, the function's ++return value is a null pointer and @code{errno} is set accordingly. The ++following @code{errno} values are specific to this function: ++ ++@table @code ++@item ENXIO ++There is no interface at the index requested. ++@end table ++ ++Additionally, since @code{if_indextoname} invokes @code{socket} ++internally, @code{errno} may also be set to a value listed for the ++@code{socket} function (@pxref{Creating a Socket}). + @end deftypefun + + @deftp {Data Type} {struct if_nameindex} diff --git a/glibc-RHEL-108974-27.patch b/glibc-RHEL-108974-27.patch new file mode 100644 index 0000000..665ff17 --- /dev/null +++ b/glibc-RHEL-108974-27.patch @@ -0,0 +1,39 @@ +commit 5a9020eeb27eee88e7839ff5e9cea94892ec90ff +Author: Maciej W. Rozycki +Date: Wed Jun 4 16:27:20 2025 +0100 + + manual: Document error codes missing for 'if_nametoindex' + + Add documentation for ENODEV error code returned and refer to 'socket' + for further possible codes from the underlying function call. + + While changing the text clarify the description by mentioning 'ifname'. + + Reviewed-by: Florian Weimer + +diff --git a/manual/socket.texi b/manual/socket.texi +index a6fb6b1b7e2b0473..e8285b9200bbfc6d 100644 +--- a/manual/socket.texi ++++ b/manual/socket.texi +@@ -497,7 +497,20 @@ interface name, including its terminating zero byte. + @c takes a lock, which makes all callers AS- and AC-Unsafe. + @c opensock @asulock @aculock @acsfd + This function yields the interface index corresponding to a particular +-name. If no interface exists with the name given, it returns 0. ++name specified with @var{ifname}. ++ ++The return value is the interface index on success. On failure, the ++function's return value is zero and @code{errno} is set accordingly. ++The following @code{errno} values are specific to this function: ++ ++@table @code ++@item ENODEV ++There is no interface by the name requested. ++@end table ++ ++Additionally, since @code{if_nametoindex} invokes @code{socket} ++internally, @code{errno} may also be set to a value listed for the ++@code{socket} function (@pxref{Creating a Socket}). + @end deftypefun + + @deftypefun {char *} if_indextoname (unsigned int @var{ifindex}, char *@var{ifname}) diff --git a/glibc-RHEL-108974-28.patch b/glibc-RHEL-108974-28.patch new file mode 100644 index 0000000..cf8f209 --- /dev/null +++ b/glibc-RHEL-108974-28.patch @@ -0,0 +1,33 @@ +commit 140b20e9716b51659a5223b182dcf07ac62b3f77 +Author: Maciej W. Rozycki +Date: Wed Jun 4 16:27:20 2025 +0100 + + manual: Document error codes missing for 'inet_pton' + + Add documentation for EAFNOSUPPORT error code returned, and the possible + return values on non-success. + + Reviewed-by: Florian Weimer + +diff --git a/manual/socket.texi b/manual/socket.texi +index e8285b9200bbfc6d..d804c7a48b91b403 100644 +--- a/manual/socket.texi ++++ b/manual/socket.texi +@@ -1216,6 +1216,17 @@ either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of + address being converted. @var{cp} is a pointer to the input string, and + @var{buf} is a pointer to a buffer for the result. It is the caller's + responsibility to make sure the buffer is large enough. ++ ++The return value is @code{1} on success and @code{0} if @var{cp} does not ++point to a valid address string for the address family @var{af} requested. ++On failure, the function's return value is @code{-1} and @code{errno} is ++set accordingly. The following @code{errno} values are specific to this ++function: ++ ++@table @code ++@item EAFNOSUPPORT ++The address family requested is neither @code{AF_INET} nor @code{AF_INET6}. ++@end table + @end deftypefun + + @deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, socklen_t @var{len}) diff --git a/glibc-RHEL-108974-29.patch b/glibc-RHEL-108974-29.patch new file mode 100644 index 0000000..2f53691 --- /dev/null +++ b/glibc-RHEL-108974-29.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-108974-3.patch b/glibc-RHEL-108974-3.patch new file mode 100644 index 0000000..aea3b56 --- /dev/null +++ b/glibc-RHEL-108974-3.patch @@ -0,0 +1,206 @@ +commit dce754b1553b86fc6352636f1fa490a85b7cf0ff +Author: DJ Delorie +Date: Fri May 10 14:52:09 2024 -0400 + + Update mmap() flags and errors lists + + Extend the list of MAP_* macros to include all macros available + to the average program (gcc -E -dM | grep MAP_*) + + Extend the list of errno codes. + + Reviewed-by: Florian Weimer + +diff --git a/manual/llio.texi b/manual/llio.texi +index a8ed72c5db6ecba9..be55dca1b7c9ebcd 100644 +--- a/manual/llio.texi ++++ b/manual/llio.texi +@@ -1574,10 +1574,15 @@ permitted. They include @code{PROT_READ}, @code{PROT_WRITE}, and + of address space for future use. The @code{mprotect} function can be + used to change the protection flags. @xref{Memory Protection}. + +-@var{flags} contains flags that control the nature of the map. +-One of @code{MAP_SHARED} or @code{MAP_PRIVATE} must be specified. ++The @var{flags} parameter contains flags that control the nature of ++the map. One of @code{MAP_SHARED}, @code{MAP_SHARED_VALIDATE}, or ++@code{MAP_PRIVATE} must be specified. Additional flags may be bitwise ++OR'd to further define the mapping. + +-They include: ++Note that, aside from @code{MAP_PRIVATE} and @code{MAP_SHARED}, not ++all flags are supported on all versions of all operating systems. ++Consult the kernel-specific documentation for details. The flags ++include: + + @vtable @code + @item MAP_PRIVATE +@@ -1599,9 +1604,19 @@ Note that actual writing may take place at any time. You need to use + @code{msync}, described below, if it is important that other processes + using conventional I/O get a consistent view of the file. + ++@item MAP_SHARED_VALIDATE ++Similar to @code{MAP_SHARED} except that additional flags will be ++validated by the kernel, and the call will fail if an unrecognized ++flag is provided. With @code{MAP_SHARED} using a flag on a kernel ++that doesn't support it causes the flag to be ignored. ++@code{MAP_SHARED_VALIDATE} should be used when the behavior of all ++flags is required. ++ + @item MAP_FIXED + This forces the system to use the exact mapping address specified in +-@var{address} and fail if it can't. ++@var{address} and fail if it can't. Note that if the new mapping ++would overlap an existing mapping, the overlapping portion of the ++existing map is unmapped. + + @c One of these is official - the other is obviously an obsolete synonym + @c Which is which? +@@ -1642,10 +1657,73 @@ The @code{MAP_HUGETLB} flag is specific to Linux. + @c There is a mechanism to select different hugepage sizes; see + @c include/uapi/asm-generic/hugetlb_encode.h in the kernel sources. + +-@c Linux has some other MAP_ options, which I have not discussed here. +-@c MAP_DENYWRITE, MAP_EXECUTABLE and MAP_GROWSDOWN don't seem applicable to +-@c user programs (and I don't understand the last two). MAP_LOCKED does +-@c not appear to be implemented. ++@item MAP_32BIT ++Require addresses that can be accessed with a signed 32 bit pointer, ++i.e., within the first 2 GiB. Ignored if MAP_FIXED is specified. ++ ++@item MAP_DENYWRITE ++@itemx MAP_EXECUTABLE ++@itemx MAP_FILE ++ ++Provided for compatibility. Ignored by the Linux kernel. ++ ++@item MAP_FIXED_NOREPLACE ++Similar to @code{MAP_FIXED} except the call will fail with ++@code{EEXIST} if the new mapping would overwrite an existing mapping. ++To test for support for this flag, specify MAP_FIXED_NOREPLACE without ++MAP_FIXED, and (if the call was successful) check the actual address ++returned. If it does not match the address passed, then this flag is ++not supported. ++ ++@item MAP_GROWSDOWN ++This flag is used to make stacks, and is typically only needed inside ++the program loader to set up the main stack for the running process. ++The mapping is created according to the other flags, except an ++additional page just prior to the mapping is marked as a ``guard ++page''. If a write is attempted inside this guard page, that page is ++mapped, the mapping is extended, and a new guard page is created. ++Thus, the mapping continues to grow towards lower addresses until it ++encounters some other mapping. ++ ++Note that accessing memory beyond the guard page will not trigger this ++feature. In gcc, use @code{-fstack-clash-protection} to ensure the ++guard page is always touched. ++ ++@item MAP_LOCKED ++A hint that requests that mapped pages are locked in memory (i.e. not ++paged out). Note that this is a request and not a requirement; use ++@code{mlock} if locking is required. ++ ++@item MAP_POPULATE ++@itemx MAP_NONBLOCK ++@code{MAP_POPULATE} is a hint that requests that the kernel read-ahead ++a file-backed mapping, causing pages to be mapped before they're ++needed. @code{MAP_NONBLOCK} is a hint that requests that the kernel ++@emph{not} attempt such except for pages are already in memory. Note ++that neither of these hints affects future paging activity, use ++@code{mlock} if such needs to be controlled. ++ ++@item MAP_NORESERVE ++Asks the kernel to not reserve physical backing (i.e. space in a swap ++device) for a mapping. This would be useful for, for example, a very ++large but sparsely used mapping which need not be limited in total ++length by available RAM, but with very few mapped pages. Note that ++writes to such a mapping may cause a @code{SIGSEGV} if the system is ++unable to map a page due to lack of resources. ++ ++On Linux, this flag's behavior may be overwridden by ++@file{/proc/sys/vm/overcommit_memory} as documented in the proc(5) man ++page. ++ ++@item MAP_STACK ++Ensures that the resulting mapping is suitable for use as a program ++stack. For example, the use of huge pages might be precluded. ++ ++@item MAP_SYNC ++This is a special flag for DAX devices, which tells the kernel to ++write dirty metadata out whenever dirty data is written out. Unlike ++most other flags, this one will fail unless @code{MAP_SHARED_VALIDATE} ++is also given. + + @item MAP_DROPPABLE + Request the page to be never written out to swap, it will be zeroed +@@ -1665,6 +1743,24 @@ Possible errors include: + + @table @code + ++@item EACCES ++ ++@var{filedes} was not open for the type of access specified in @var{protect}. ++ ++@item EAGAIN ++ ++The system has temporarily run out of resources. ++ ++@item EBADF ++ ++The @var{fd} passed is invalid, and a valid file descriptor is ++required (i.e. MAP_ANONYMOUS was not specified). ++ ++@item EEXIST ++ ++@code{MAP_FIXED_NOREPLACE} was specified and an existing mapping was ++found overlapping the requested address range. ++ + @item EINVAL + + Either @var{address} was unusable (because it is not a multiple of the +@@ -1673,23 +1769,37 @@ applicable page size), or inconsistent @var{flags} were given. + If @code{MAP_HUGETLB} was specified, the file or system does not support + large page sizes. + +-@item EACCES ++@item ENODEV + +-@var{filedes} was not open for the type of access specified in @var{protect}. ++This file is of a type that doesn't support mapping, the process has ++exceeded its data space limit, or the map request would exceed the ++process's virtual address space. + + @item ENOMEM + +-Either there is not enough memory for the operation, or the process is +-out of address space. +- +-@item ENODEV +- +-This file is of a type that doesn't support mapping. ++There is not enough memory for the operation, the process is out of ++address space, or there are too many mappings. On Linux, the maximum ++number of mappings can be controlled via ++@file{/proc/sys/vm/max_map_count} or, if your OS supports it, via ++the @code{vm.max_map_count} @code{sysctl} setting. + + @item ENOEXEC + + The file is on a filesystem that doesn't support mapping. + ++@item EPERM ++ ++@code{PROT_EXEC} was requested but the file is on a filesystem that ++was mounted with execution denied, a file seal prevented the mapping, ++or the caller set MAP_HUDETLB but does not have the required ++priviledges. ++ ++@item EOVERFLOW ++ ++Either the offset into the file plus the length of the mapping causes ++internal page counts to overflow, or the offset requested exceeds the ++length of the file. ++ + @c On Linux, EAGAIN will appear if the file has a conflicting mandatory lock. + @c However mandatory locks are not discussed in this manual. + @c diff --git a/glibc-RHEL-108974-30.patch b/glibc-RHEL-108974-30.patch new file mode 100644 index 0000000..1fc1bb8 --- /dev/null +++ b/glibc-RHEL-108974-30.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-108974-31.patch b/glibc-RHEL-108974-31.patch new file mode 100644 index 0000000..cd96eb5 --- /dev/null +++ b/glibc-RHEL-108974-31.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-108974-32.patch b/glibc-RHEL-108974-32.patch new file mode 100644 index 0000000..6fc1c7b --- /dev/null +++ b/glibc-RHEL-108974-32.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-108974-33.patch b/glibc-RHEL-108974-33.patch new file mode 100644 index 0000000..cf770e4 --- /dev/null +++ b/glibc-RHEL-108974-33.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-108974-34.patch b/glibc-RHEL-108974-34.patch new file mode 100644 index 0000000..fa83a4c --- /dev/null +++ b/glibc-RHEL-108974-34.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-RHEL-108974-4.patch b/glibc-RHEL-108974-4.patch new file mode 100644 index 0000000..cbb1d58 --- /dev/null +++ b/glibc-RHEL-108974-4.patch @@ -0,0 +1,44 @@ +commit 0e16db440cc73d2cdd94e439c0efa1ec43d92b2a +Author: Florian Weimer +Date: Tue Aug 13 15:52:34 2024 +0200 + + manual: Document generic printf error codes + + Describe EOVERFLOW, ENOMEN, EILSEQ. + + Reviewed-by: Carlos O'Donell + +diff --git a/manual/stdio.texi b/manual/stdio.texi +index 393ed9c665792609..19b4a53299410ca6 100644 +--- a/manual/stdio.texi ++++ b/manual/stdio.texi +@@ -2354,6 +2354,29 @@ the easiest way to make sure you have all the right prototypes is to + just include @file{stdio.h}. + @pindex stdio.h + ++The @code{printf} family shares the error codes listed below. ++Individual functions may report additional @code{errno} values if they ++fail. ++ ++@table @code ++@item EOVERFLOW ++The number of written bytes would have exceeded @code{INT_MAX}, and thus ++could not be represented in the return type @code{int}. ++ ++@item ENOMEM ++The function could not allocate memory during processing. Long argument ++lists and certain floating point conversions may require memory ++allocation, as does initialization of an output stream upon first use. ++ ++@item EILSEQ ++POSIX specifies this error code should be used if a wide character is ++encountered that does not have a matching valid character. @Theglibc{} ++always performs transliteration, using a replacement character if ++necessary, so this error condition cannot occur on output. However, ++@theglibc{} uses @code{EILSEQ} to indicate that an input character ++sequence (wide or multi-byte) could not be converted successfully. ++@end table ++ + @deftypefun int printf (const char *@var{template}, @dots{}) + @standards{ISO, stdio.h} + @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} diff --git a/glibc-RHEL-108974-5.patch b/glibc-RHEL-108974-5.patch new file mode 100644 index 0000000..1ef6c35 --- /dev/null +++ b/glibc-RHEL-108974-5.patch @@ -0,0 +1,53 @@ +commit 2be0572f3a41d5d5a8bb3b2b04244b7c01ac0f58 +Author: Florian Weimer +Date: Tue Aug 13 15:52:34 2024 +0200 + + manual: Document dprintf and vdprintf + + Reviewed-by: Carlos O'Donell + +diff --git a/manual/stdio.texi b/manual/stdio.texi +index 19b4a53299410ca6..3f837fa99c3c6574 100644 +--- a/manual/stdio.texi ++++ b/manual/stdio.texi +@@ -2523,6 +2523,26 @@ store the result in which case @code{-1} is returned. This was + changed in order to comply with the @w{ISO C99} standard. + @end deftypefun + ++@deftypefun dprintf (int @var{fd}, @var{template}, ...) ++@standards{POSIX, stdio.h} ++@safety{@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} ++This function formats its arguments according to @var{template} and ++writes the result to the file descriptor @var{fd}, using the ++@code{write} function. It returns the number of bytes written, or a ++negative value if there was an error. In the error case, @code{errno} ++is set appropriately. The possible @code{errno} values depend on the ++type of the file descriptor @var{fd}, in addition to the general ++@code{printf} error codes. ++ ++The number of calls to @code{write} is unspecified, and some @code{write} ++calls may have happened even if @code{dprintf} returns with an error. ++ ++@strong{Portability Note:} POSIX does not require that this function is ++async-signal-safe, and @theglibc{} implementation is not. However, some ++other systems offer this function as an async-signal-safe alternative to ++@code{fprintf}. @xref{POSIX Safety Concepts}. ++@end deftypefun ++ + @node Dynamic Output + @subsection Dynamically Allocating Formatted Output + +@@ -2736,6 +2756,13 @@ The @code{obstack_vprintf} function is the equivalent of + as for @code{vprintf}. + @end deftypefun + ++@deftypefun int vdprintf (int @var{fd}, const char *@var{template}, va_list @var{ap}) ++@standards{POSIX, stdio.h} ++@safety{@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} ++The @code{vdprintf} is the equivalent of @code{dprintf}, but processes ++an argument list. ++@end deftypefun ++ + Here's an example showing how you might use @code{vfprintf}. This is a + function that prints error messages to the stream @code{stderr}, along + with a prefix indicating the name of the program diff --git a/glibc-RHEL-108974-6.patch b/glibc-RHEL-108974-6.patch new file mode 100644 index 0000000..0d5ec50 --- /dev/null +++ b/glibc-RHEL-108974-6.patch @@ -0,0 +1,321 @@ +commit 3de73f974fab55430177c811c9c9ba3f251d5747 +Author: Florian Weimer +Date: Wed Aug 7 14:57:41 2024 +0200 + + manual: Add Descriptor-Relative Access section + + 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.) + + Reviewed-by: Adhemerval Zanella + +diff --git a/manual/filesys.texi b/manual/filesys.texi +index 47d929744eea75dd..aabb68385b6b9732 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 program 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} +diff --git a/manual/llio.texi b/manual/llio.texi +index be55dca1b7c9ebcd..05ab44c6e7a5d4fd 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{}}} +@@ -3816,7 +3853,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 c421563d16979c64..c1a3683d584cb914 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 diff --git a/glibc-RHEL-108974-7.patch b/glibc-RHEL-108974-7.patch new file mode 100644 index 0000000..7606d74 --- /dev/null +++ b/glibc-RHEL-108974-7.patch @@ -0,0 +1,31 @@ +commit 6efd6cd46bf2257e674be4933a034542d80944eb +Author: Florian Weimer +Date: Fri Sep 6 14:07:00 2024 +0200 + + manual: Safety annotations for clock_gettime, clock_getres + + The annotations are preliminary, for consistency with existing + annotations on gettimeofday etc. + + Reviewed-by: Carlos O'Donell + +diff --git a/manual/time.texi b/manual/time.texi +index ab5063be81cf0af9..d292e269ebb2f975 100644 +--- a/manual/time.texi ++++ b/manual/time.texi +@@ -532,6 +532,7 @@ Systems may support more than just these two POSIX clocks. + + @deftypefun int clock_gettime (clockid_t @var{clock}, struct timespec *@var{ts}) + @standards{POSIX.1, time.h} ++@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + Get the current time according to the clock identified by @var{clock}, + storing it as seconds and nanoseconds in @code{*@var{ts}}. + @xref{Time Types}, for a description of @code{struct timespec}. +@@ -553,6 +554,7 @@ clock: + + @deftypefun int clock_getres (clockid_t @var{clock}, struct timespec *@var{res}) + @standards{POSIX.1, time.h} ++@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + Get the actual resolution of the clock identified by @var{clock}, + storing it in @code{*@var{ts}}. + diff --git a/glibc-RHEL-108974-8.patch b/glibc-RHEL-108974-8.patch new file mode 100644 index 0000000..96e2962 --- /dev/null +++ b/glibc-RHEL-108974-8.patch @@ -0,0 +1,387 @@ +commit 83a1cc3bc3d28c97d1af6c0957b11fe39fd786d8 +Author: Carlos O'Donell +Date: Wed Oct 9 18:32:26 2024 -0400 + + manual: Fix and test @deftypef* function formatting + + The manual contained several instances of incorrect formatting + that were correct texinfo but produced incorrectly rendered manuals + or incorrect behaviour from the tooling. + + The most important was incorrect quoting of function returns + by failing to use {} to quote the return. The impact of this + mistake means that 'info libc func' does not jump to the function + in question but instead to the introductory page under the assumption + that func doesn't exist. The function returns are now correctly + quoted. + + The second issue was the use of a category specifier with + @deftypefun which doesn't accept a category specifier. If a category + specifier is required then @deftypefn needs to be used. This is + corrected by changing the command to @deftypefn for such functions + that used {Deprecated function} as a category. + + The last issue is a missing space between the function name and the + arguments which results in odd function names like "epoll_wait(int" + instead of "epoll_wait". This also impacts the use of 'info libc' + and is corrected. + + We additionally remove ';' from the end of function arguments and + add an 'int' return type for dprintf. + + Lastly we add a new test check-deftype.sh which verifies the expected + formatting of @deftypefun, @deftypefunx, @deftypefn, and + @deftypefnx. The new test is also run as the summary file is + generated to ensure we don't generate incorrect results. + + The existing check-safety.sh is also run directly as a test to increase + coverage since the existing tests only ran on manual install. + + The new tests now run as part of the standard "make check" that + pre-commit CI runs and developers should run. + + No regressions on x86_64. + + HTML and PDF rendering reviewed and looks correct for all changes. + + Reviewed-by: H.J. Lu + +diff --git a/manual/Makefile b/manual/Makefile +index a6c05db540d6c1da..6a4cfbeb765265f3 100644 +--- a/manual/Makefile ++++ b/manual/Makefile +@@ -69,6 +69,11 @@ chapters.% top-menu.%: libc-texinfo.sh $(texis-path) Makefile + '$(chapters)' \ + '$(appendices) $(licenses)' + ++# Verify validity of texinfo sources against project rules. ++tests-special += \ ++ $(objpfx)check-deftype.out \ ++ $(objpfx)check-safety.out \ ++ # tests-special + + $(objpfx)libc.dvi $(objpfx)libc.pdf $(objpfx)libc.info: \ + $(addprefix $(objpfx),$(libc-texi-generated)) +@@ -83,10 +88,19 @@ $(objpfx)summary.texi: $(objpfx)stamp-summary ; + $(objpfx)stamp-summary: summary.pl $(filter-out $(objpfx)summary.texi, \ + $(texis-path)) + $(SHELL) ./check-safety.sh $(filter-out $(objpfx)%, $(texis-path)) ++ $(SHELL) ./check-deftype.sh $(filter-out $(objpfx)%, $(texis-path)) + LC_ALL=C $(PERL) $^ > $(objpfx)summary-tmp + $(move-if-change) $(objpfx)summary-tmp $(objpfx)summary.texi + touch $@ + ++$(objpfx)check-safety.out: check-safety.sh ++ $(SHELL) $< > $@ ; \ ++ $(evaluate-test) ++ ++$(objpfx)check-deftype.out: check-deftype.sh ++ $(SHELL) $< > $@ ; \ ++ $(evaluate-test) ++ + # Generate a file which can be added to the `dir' content to provide direct + # access to the documentation of the function, variables, and other + # definitions. +@@ -152,10 +166,19 @@ $(objpfx)%.pdf: %.texinfo + + + # Distribution. +-minimal-dist = summary.pl texis.awk tsort.awk libc-texinfo.sh libc.texinfo \ +- libm-err.texi stamp-libm-err check-safety.sh \ +- $(filter-out summary.texi, $(nonexamples)) \ +- $(patsubst %.c.texi,examples/%.c, $(examples)) ++minimal-dist = \ ++ $(filter-out summary.texi, $(nonexamples)) \ ++ $(patsubst %.c.texi,examples/%.c, $(examples)) \ ++ check-deftype.sh \ ++ check-safety.sh \ ++ libc-texinfo.sh \ ++ libc.texinfo \ ++ libm-err.texi \ ++ stamp-libm-err \ ++ summary.pl \ ++ texis.awk \ ++ tsort.awk \ ++ # minimal-dist + + indices = cp fn pg tp vr ky + generated-dirs += libc +diff --git a/manual/check-deftype.sh b/manual/check-deftype.sh +new file mode 100644 +index 0000000000000000..395c99af6afe1fdd +--- /dev/null ++++ b/manual/check-deftype.sh +@@ -0,0 +1,50 @@ ++#!/bin/sh ++ ++# Copyright 2024 Free Software Foundation, Inc. ++# This file is part of the GNU C Library. ++ ++# The GNU C Library is free software; you can redistribute it and/or ++# modify it under the terms of the GNU Lesser General Public ++# License as published by the Free Software Foundation; either ++# version 2.1 of the License, or (at your option) any later version. ++ ++# The GNU C Library is distributed in the hope that it will be useful, ++# but WITHOUT ANY WARRANTY; without even the implied warranty of ++# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ++# Lesser General Public License for more details. ++ ++# You should have received a copy of the GNU Lesser General Public ++# License along with the GNU C Library; if not, see ++# . ++ ++# Check that the @deftypefun command is called with the expected ++# arguments and includes checking for common mistakes including ++# failure to include a space after the function name, or incorrect ++# quoting. ++ ++success=: ++ ++# If no arguments are given, take all *.texi files in the current directory. ++test $# != 0 || set *.texi ++ ++# We search for all @deftypefun and @deftypefunx command uses. ++# Then we remove all of those that match our expectations. ++# A @deftypefun or @deftypefunx command takes 3 arguments: ++# - return type ++# - name ++# - arguments ++# This is different from @deftypefn which includes an additional ++# category which is implicit here. ++grep -n -r '^@deftypefun' "$@" | ++grep -v '^.*@deftypefunx\?'\ ++' \({\?[a-zA-Z0-9_ *]*}\?\) \([a-zA-Z0-9_]*\) (.*)$' && ++success=false ++ ++# We search for all @deftypefn and @deftypefnx command uses. ++# We have 4 arguments in the command including the category. ++grep -n -r '^@deftypefn' "$@" | ++grep -v '^.*@deftypefnx\?'\ ++' {\?[a-zA-Z ]*}\? \({\?[a-zA-Z0-9@{}_ *]*}\?\) \([a-zA-Z0-9_]*\) (.*)$' && ++success=false ++ ++$success +diff --git a/manual/ipc.texi b/manual/ipc.texi +index 6a6e5ad410c14387..32c5ac066fb94579 100644 +--- a/manual/ipc.texi ++++ b/manual/ipc.texi +@@ -20,7 +20,7 @@ by @theglibc{}. + @c Need descriptions for all of these functions. + + @subsection System V Semaphores +-@deftypefun int semctl (int @var{semid}, int @var{semnum}, int @var{cmd}); ++@deftypefun int semctl (int @var{semid}, int @var{semnum}, int @var{cmd}) + @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{/linux}}} + @c syscall(ipc) ok + @c +@@ -30,35 +30,35 @@ by @theglibc{}. + @c semid_ds. + @end deftypefun + +-@deftypefun int semget (key_t @var{key}, int @var{nsems}, int @var{semflg}); ++@deftypefun int semget (key_t @var{key}, int @var{nsems}, int @var{semflg}) + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + @c syscall(ipc) ok + @end deftypefun + +-@deftypefun int semop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}); ++@deftypefun int semop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}) + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + @c syscall(ipc) ok + @end deftypefun + +-@deftypefun int semtimedop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}, const struct timespec *@var{timeout}); ++@deftypefun int semtimedop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}, const struct timespec *@var{timeout}) + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + @c syscall(ipc) ok + @end deftypefun + + @subsection POSIX Semaphores + +-@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value}); ++@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value}) + @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} + @c Does not atomically update sem_t therefore AC-unsafe + @c because it can leave sem_t partially initialized. + @end deftypefun + +-@deftypefun int sem_destroy (sem_t *@var{sem}); ++@deftypefun int sem_destroy (sem_t *@var{sem}) + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + @c Function does nothing and is therefore always safe. + @end deftypefun + +-@deftypefun sem_t *sem_open (const char *@var{name}, int @var{oflag}, ...); ++@deftypefun {sem_t *} sem_open (const char *@var{name}, int @var{oflag}, ...) + @safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}} + @c pthread_once asuinit + @c +@@ -67,7 +67,7 @@ by @theglibc{}. + @c shmfs on Linux. + @end deftypefun + +-@deftypefun int sem_close (sem_t *@var{sem}); ++@deftypefun int sem_close (sem_t *@var{sem}) + @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} + @c lll_lock asulock aculock + @c twalk mtsrace{:root} +@@ -77,13 +77,13 @@ by @theglibc{}. + @c are not updated atomically. + @end deftypefun + +-@deftypefun int sem_unlink (const char *@var{name}); ++@deftypefun int sem_unlink (const char *@var{name}) + @safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}} + @c pthread_once asuinit acucorrupt aculock + @c mempcpy acucorrupt + @end deftypefun + +-@deftypefun int sem_wait (sem_t *@var{sem}); ++@deftypefun int sem_wait (sem_t *@var{sem}) + @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} + @c atomic_fetch_add_relaxed (nwaiters) acucorrupt + @c +@@ -95,22 +95,22 @@ by @theglibc{}. + @c waiters count. + @end deftypefun + +-@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime}); ++@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime}) + @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} + @c Same safety issues as sem_wait. + @end deftypefun + +-@deftypefun int sem_trywait (sem_t *@var{sem}); ++@deftypefun int sem_trywait (sem_t *@var{sem}) + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + @c All atomic operations are safe in all contexts. + @end deftypefun + +-@deftypefun int sem_post (sem_t *@var{sem}); ++@deftypefun int sem_post (sem_t *@var{sem}) + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + @c Same safety as sem_trywait. + @end deftypefun + +-@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval}); ++@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval}) + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + @c Atomic write of a value is safe in all contexts. + @end deftypefun +diff --git a/manual/llio.texi b/manual/llio.texi +index 05ab44c6e7a5d4fd..850d09205a604589 100644 +--- a/manual/llio.texi ++++ b/manual/llio.texi +@@ -4840,12 +4840,12 @@ of an IOCTL, see @ref{Out-of-Band Data}. + @manpagefunctionstub{poll,2} + @end deftypefun + +-@deftypefun int epoll_create(int @var{size}) ++@deftypefun int epoll_create (int @var{size}) + + @manpagefunctionstub{epoll_create,2} + @end deftypefun + +-@deftypefun int epoll_wait(int @var{epfd}, struct epoll_event *@var{events}, int @var{maxevents}, int @var{timeout}) ++@deftypefun int epoll_wait (int @var{epfd}, struct epoll_event *@var{events}, int @var{maxevents}, int @var{timeout}) + + @manpagefunctionstub{epoll_wait,2} + @end deftypefun +diff --git a/manual/memory.texi b/manual/memory.texi +index 3710d7ec667519cc..58683ee93dace783 100644 +--- a/manual/memory.texi ++++ b/manual/memory.texi +@@ -2935,7 +2935,7 @@ exceed the process' data storage limit. + @end deftypefun + + +-@deftypefun void *sbrk (ptrdiff_t @var{delta}) ++@deftypefun {void *} sbrk (ptrdiff_t @var{delta}) + @standards{BSD, unistd.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + +diff --git a/manual/stdio.texi b/manual/stdio.texi +index 3f837fa99c3c6574..aa137e9888b5b59d 100644 +--- a/manual/stdio.texi ++++ b/manual/stdio.texi +@@ -2523,7 +2523,7 @@ store the result in which case @code{-1} is returned. This was + changed in order to comply with the @w{ISO C99} standard. + @end deftypefun + +-@deftypefun dprintf (int @var{fd}, @var{template}, ...) ++@deftypefun int dprintf (int @var{fd}, @var{template}, ...) + @standards{POSIX, stdio.h} + @safety{@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} + This function formats its arguments according to @var{template} and +diff --git a/manual/threads.texi b/manual/threads.texi +index 25e99c9606dcad77..9ea137cb9663b89c 100644 +--- a/manual/threads.texi ++++ b/manual/threads.texi +@@ -592,7 +592,7 @@ destructor for the thread-specific data is not called during destruction, nor + is it called during thread exit. + @end deftypefun + +-@deftypefun void *pthread_getspecific (pthread_key_t @var{key}) ++@deftypefun {void *} pthread_getspecific (pthread_key_t @var{key}) + @standards{POSIX, pthread.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + @c pthread_getspecific ok +diff --git a/manual/time.texi b/manual/time.texi +index d292e269ebb2f975..6ccb07fcfc10449b 100644 +--- a/manual/time.texi ++++ b/manual/time.texi +@@ -1829,7 +1829,7 @@ can be placed in the buffer @var{s} the return value is zero, with the + same problems indicated in the @code{strftime} documentation. + @end deftypefun + +-@deftypefun {Deprecated function} {char *} asctime (const struct tm *@var{brokentime}) ++@deftypefn {Deprecated function} {char *} asctime (const struct tm *@var{brokentime}) + @standards{ISO, time.h} + @safety{@prelim{}@mtunsafe{@mtasurace{:asctime} @mtslocale{}}@asunsafe{}@acsafe{}} + @c asctime @mtasurace:asctime @mtslocale +@@ -1863,9 +1863,9 @@ string.) + @strong{Portability note:} + This obsolescent function is deprecated in C23. + Programs should instead use @code{strftime} or even @code{sprintf}. +-@end deftypefun ++@end deftypefn + +-@deftypefun {Deprecated function} {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer}) ++@deftypefn {Deprecated function} {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer}) + @standards{???, time.h} + @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} + @c asctime_r @mtslocale +@@ -1884,9 +1884,9 @@ it returns @code{NULL}. + @strong{Portability Note:} + POSIX.1-2024 removed this obsolescent function. + Programs should instead use @code{strftime} or even @code{sprintf}. +-@end deftypefun ++@end deftypefn + +-@deftypefun {Deprecated function} {char *} ctime (const time_t *@var{time}) ++@deftypefn {Deprecated function} {char *} ctime (const time_t *@var{time}) + @standards{ISO, time.h} + @safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtasurace{:asctime} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} + @c ctime @mtasurace:tmbuf @mtasurace:asctime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@@ -1909,9 +1909,9 @@ Calling @code{ctime} also sets the time zone state as if + @strong{Portability note:} + This obsolescent function is deprecated in C23. + Programs should instead use @code{strftime} or even @code{sprintf}. +-@end deftypefun ++@end deftypefn + +-@deftypefun {Deprecated function} {char *} ctime_r (const time_t *@var{time}, char *@var{buffer}) ++@deftypefn {Deprecated function} {char *} ctime_r (const time_t *@var{time}, char *@var{buffer}) + @standards{???, time.h} + @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} + @c ctime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@@ -1935,7 +1935,7 @@ it returns @code{NULL}. + @strong{Portability Note:} + POSIX.1-2024 removed this obsolescent function. + Programs should instead use @code{strftime} or even @code{sprintf}. +-@end deftypefun ++@end deftypefn + + @node Parsing Date and Time + @subsection Convert textual time and date information back diff --git a/glibc-RHEL-108974-9.patch b/glibc-RHEL-108974-9.patch new file mode 100644 index 0000000..66bb23f --- /dev/null +++ b/glibc-RHEL-108974-9.patch @@ -0,0 +1,58 @@ +commit dcad78507433a9a64b8b548b19e110933f8d939a +Author: DJ Delorie +Date: Thu Oct 10 17:16:35 2024 -0400 + + manual: Document stdio.h functions that may be macros + + Glibc has two gnu-extension functions that are implemented as + macros but not documented as such: fread_unlocked and + fwrite_unlocked. Document them as such. + + Additionally, putc_unlocked and getc_unlocked are documented in + POSIX as possibly being macros. Update the manual to add a warning + about those also, depite glibc not implementing them as macros. + +diff --git a/manual/stdio.texi b/manual/stdio.texi +index aa137e9888b5b59d..1708d33b10a63b89 100644 +--- a/manual/stdio.texi ++++ b/manual/stdio.texi +@@ -921,6 +921,9 @@ Therefore, @var{stream} should never be an expression with side-effects. + @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} + The @code{putc_unlocked} function is equivalent to the @code{putc} + function except that it does not implicitly lock the stream. ++Like @code{putc}, it may be implemented as a macro and may evaluate ++the @var{stream} argument more than once. Therefore, @var{stream} ++should not be an expression with side-effects. + @end deftypefun + + @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream}) +@@ -1124,6 +1127,9 @@ Therefore, @var{stream} should never be an expression with side-effects. + @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} + The @code{getc_unlocked} function is equivalent to the @code{getc} + function except that it does not implicitly lock the stream. ++Like @code{getc}, it may be implemented as a macro and may evaluate ++the @var{stream} argument more than once. Therefore, @var{stream} ++should not be an expression with side-effects. + @end deftypefun + + @deftypefun wint_t getwc_unlocked (FILE *@var{stream}) +@@ -1563,6 +1569,9 @@ The @code{fread_unlocked} function is equivalent to the @code{fread} + function except that it does not implicitly lock the stream. + + This function is a GNU extension. ++This function may be implemented as a macro and may evaluate ++@var{stream} more than once. Therefore, @var{stream} should not be an ++expression with side-effects. + @end deftypefun + + @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) +@@ -1581,6 +1590,9 @@ The @code{fwrite_unlocked} function is equivalent to the @code{fwrite} + function except that it does not implicitly lock the stream. + + This function is a GNU extension. ++This function may be implemented as a macro and may evaluate ++@var{stream} more than once. Therefore, @var{stream} should not be an ++expression with side-effects. + @end deftypefun + + @node Formatted Output diff --git a/glibc.spec b/glibc.spec index 99be6e2..5e82c9c 100644 --- a/glibc.spec +++ b/glibc.spec @@ -147,7 +147,7 @@ Version: %{glibcversion} # - It allows using the Release number without the %%dist tag in the dependency # generator to make the generated requires interchangeable between Rawhide # and ELN (.elnYY < .fcXX). -%global baserelease 54 +%global baserelease 55 Release: %{baserelease}%{?dist} # Licenses: @@ -651,6 +651,40 @@ Patch325: glibc-RHEL-107695-18.patch Patch326: glibc-RHEL-107695-19.patch Patch327: glibc-RHEL-108475-1.patch Patch328: glibc-RHEL-108475-2.patch +Patch329: glibc-RHEL-108974-1.patch +Patch330: glibc-RHEL-108974-2.patch +Patch331: glibc-RHEL-108974-3.patch +Patch332: glibc-RHEL-108974-4.patch +Patch333: glibc-RHEL-108974-5.patch +Patch334: glibc-RHEL-108974-6.patch +Patch335: glibc-RHEL-108974-7.patch +Patch336: glibc-RHEL-108974-8.patch +Patch337: glibc-RHEL-108974-9.patch +Patch338: glibc-RHEL-108974-10.patch +Patch339: glibc-RHEL-108974-11.patch +Patch340: glibc-RHEL-108974-12.patch +Patch341: glibc-RHEL-108974-13.patch +Patch342: glibc-RHEL-108974-14.patch +Patch343: glibc-RHEL-108974-15.patch +Patch344: glibc-RHEL-108974-16.patch +Patch345: glibc-RHEL-108974-17.patch +Patch346: glibc-RHEL-108974-18.patch +Patch347: glibc-RHEL-108974-19.patch +Patch348: glibc-RHEL-108974-20.patch +Patch349: glibc-RHEL-108974-21.patch +Patch350: glibc-RHEL-108974-22.patch +Patch351: glibc-RHEL-108974-23.patch +Patch352: glibc-RHEL-108974-24.patch +Patch353: glibc-RHEL-108974-25.patch +Patch354: glibc-RHEL-108974-26.patch +Patch355: glibc-RHEL-108974-27.patch +Patch356: glibc-RHEL-108974-28.patch +Patch357: glibc-RHEL-108974-29.patch +Patch358: glibc-RHEL-108974-30.patch +Patch359: glibc-RHEL-108974-31.patch +Patch360: glibc-RHEL-108974-32.patch +Patch361: glibc-RHEL-108974-33.patch +Patch362: glibc-RHEL-108974-34.patch ############################################################################## # Continued list of core "glibc" package information: @@ -2664,6 +2698,9 @@ update_gconv_modules_cache () %endif %changelog +* Wed Aug 13 2025 Arjun Shankar - 2.39-55 +- Various updates to the manual from upstream (RHEL-108974) + * Mon Aug 11 2025 Frédéric Bérat - 2.39-54 - Fix memory leak after fdopen seek failure (RHEL-108475)