[PATCH v2 2/2] manual: Add links to POSIX Semaphores man-pages documentation

[Adhemerval Zanella Netto]

On 13/01/25 22:52, Arjun Shankar wrote:
> 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.

LGTM, thanks.

Reviewed-by: Adhemerval Zanella  <adhemerval.zanella@linaro.org>

> ---
> v1: https://sourceware.org/pipermail/libc-alpha/2024-December/163202.html
> Changes in v2:
>  * Moved man page stubs under safety assertions.
>  * Added standards information
> 
>  manual/threads.texi | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/manual/threads.texi b/manual/threads.texi
> index 806ab866c5..7b9c79636c 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
>