From 81278fcf434bdfecd47aa1f280bc884116606c43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20B=C3=A9rat?= Date: Wed, 14 May 2025 11:16:37 +0200 Subject: [PATCH] Improve POSIX semaphore documentation - Backport: manual: Consolidate POSIX Semaphores docs in Threads chapter - Backport: manual: Add links to POSIX Semaphores man-pages documentation Resolves: RHEL-65355 --- glibc-RHEL-65355-1.patch | 223 +++++++++++++++++++++++++++++++++++++++ glibc-RHEL-65355-2.patch | 111 +++++++++++++++++++ glibc.spec | 7 +- 3 files changed, 340 insertions(+), 1 deletion(-) create mode 100644 glibc-RHEL-65355-1.patch create mode 100644 glibc-RHEL-65355-2.patch diff --git a/glibc-RHEL-65355-1.patch b/glibc-RHEL-65355-1.patch new file mode 100644 index 0000000..333f00d --- /dev/null +++ b/glibc-RHEL-65355-1.patch @@ -0,0 +1,223 @@ +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 + +Conflicts: + manual/ipc.texi (fixup context) + +diff --git a/manual/ipc.texi b/manual/ipc.texi +index 73189960c46c908a..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 becuase 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_increment (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_decrement 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 42e824fcdbec60f6..a6b30c099b5a1323 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-65355-2.patch b/glibc-RHEL-65355-2.patch new file mode 100644 index 0000000..d0d20ea --- /dev/null +++ b/glibc-RHEL-65355-2.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 a6b30c099b5a1323..f6cb7974479f75e3 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.spec b/glibc.spec index d18729d..bfc6fbb 100644 --- a/glibc.spec +++ b/glibc.spec @@ -157,7 +157,7 @@ end \ Summary: The GNU libc libraries Name: glibc Version: %{glibcversion} -Release: 190%{?dist} +Release: 191%{?dist} # In general, GPLv2+ is used by programs, LGPLv2+ is used for # libraries. @@ -1197,6 +1197,8 @@ Patch889: glibc-RHEL-68805-7.patch Patch890: glibc-RHEL-68805-8.patch Patch891: glibc-RHEL-68805-9.patch Patch892: glibc-RHEL-63210.patch +Patch893: glibc-RHEL-65355-1.patch +Patch894: glibc-RHEL-65355-2.patch ############################################################################## # Continued list of core "glibc" package information: @@ -3190,6 +3192,9 @@ update_gconv_modules_cache () %endif %changelog +* Wed May 14 2025 Frédéric Bérat - 2.34-191 +- Improve POSIX semaphore documentation (RHEL-65355) + * Wed May 14 2025 Frédéric Bérat - 2.34-190 - Add test case for fflush (RHEL-63210)