Hello Ted,

Ted Unangst wrote on Wed, Jul 02, 2025 at 03:07:36PM -0400:
> On 2025-06-21, Ingo Schwarze wrote:
>> Ted Unangst proposed some teduing:

>>> This diff more or less mechanically combines the pages. I think a
>>> bit more narrative structure can be added, but at least you can get
>>> some idea of what these functions are for and how they work together
>>> in a single page now.

>> My in-line remarks are suggestions, not conditions for going ahead.

> Mostly incorporated. Thanks.
> I changed a few words here and there for clarity and brevity.

Very good, OK schwarze@ if you fix the three typos noted inline below.

Thanks for doing this!  :-)
  Ingo


> Index: Makefile.inc
> ===================================================================
> RCS file: /home/cvs/src/lib/libpthread/man/Makefile.inc,v
> diff -u -p -r1.37 Makefile.inc
> --- Makefile.inc	12 Jan 2019 00:16:03 -0000	1.37
> +++ Makefile.inc	2 Jul 2025 18:30:21 -0000
> @@ -20,12 +20,7 @@ MAN+=	\
>  	pthread_cleanup_pop.3 \
>  	pthread_cleanup_push.3 \
>  	pthread_condattr_init.3 \
> -	pthread_cond_broadcast.3 \
> -	pthread_cond_destroy.3 \
>  	pthread_cond_init.3 \
> -	pthread_cond_signal.3 \
> -	pthread_cond_timedwait.3 \
> -	pthread_cond_wait.3 \
>  	pthread_cancel.3 \
>  	pthread_create.3 \
>  	pthread_detach.3 \
> Index: pthread_cond_init.3
> ===================================================================
> RCS file: /home/cvs/src/lib/libpthread/man/pthread_cond_init.3,v
> diff -u -p -r1.13 pthread_cond_init.3
> --- pthread_cond_init.3	7 Jun 2025 00:16:52 -0000	1.13
> +++ pthread_cond_init.3	2 Jul 2025 19:02:40 -0000
> @@ -28,37 +28,104 @@
>  .\" SUCH DAMAGE.
>  .\"
>  .\" $FreeBSD: pthread_cond_init.3,v 1.6 1999/08/28 00:03:03 peter Exp $
> +.\" $FreeBSD: pthread_cond_destroy.3,v 1.5 1999/08/28 00:03:03 peter Exp $
> +.\" $FreeBSD: pthread_cond_wait.3,v 1.6 1999/08/28 00:03:04 peter Exp $
> +.\" $FreeBSD: pthread_cond_timedwait.3,v 1.6 1999/08/28 00:03:04 peter Exp $
> +.\" $FreeBSD: pthread_cond_broadcast.3,v 1.5 1999/08/28 00:03:03 peter Exp $
> +.\" $FreeBSD: pthread_cond_signal.3,v 1.5 1999/08/28 00:03:04 peter Exp $
>  .\"
>  .Dd $Mdocdate: June 7 2025 $
>  .Dt PTHREAD_COND_INIT 3
>  .Os
>  .Sh NAME
> -.Nm pthread_cond_init
> -.Nd create a condition variable
> +.Nm pthread_cond_init ,
> +.Nm pthread_cond_destroy ,
> +.Nm pthread_cond_wait ,
> +.Nm pthread_cond_timedwait ,
> +.Nm pthread_cond_broadcast ,
> +.Nm pthread_cond_signal
> +.Nd block and unblock threads with condition variables
>  .Sh SYNOPSIS
>  .Lb libpthread
>  .In pthread.h
>  .Ft int
> -.Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
> +.Fo pthread_cond_init
> +.Fa "pthread_cond_t *cond"
> +.Fa "const pthread_condattr_t *attr"
> +.Fc
> +.Ft int
> +.Fo pthread_cond_destroy
> +.Fa "pthread_cond_t *cond"
> +.Fc
> +.Ft int
> +.Fo pthread_cond_wait
> +.Fa "pthread_cond_t *cond"
> +.Fa "pthread_mutex_t *mutex"
> +.Fc
> +.Ft int
> +.Fo pthread_cond_timedwait
> +.Fa "pthread_cond_t *cond"
> +.Fa "pthread_mutex_t *mutex"
> +.Fa "const struct timespec *abstime"
> +.Fc
> +.Ft int
> +.Fo pthread_cond_broadcast
> +.Fa "pthread_cond_t *cond"
> +.Fc
> +.Ft int
> +.Fo pthread_cond_signal
> +.Fa "pthread_cond_t *cond"
> +.Fc
>  .Sh DESCRIPTION
>  The
>  .Fn pthread_cond_init
> -function creates a new condition variable, with attributes specified with
> +function creates a new condition variable with attributes specified by
>  .Fa attr .
>  If
>  .Fa attr
>  is
>  .Dv NULL ,
>  the default attributes are used.
> -.Sh RETURN VALUES
> -If successful, the
> -.Fn pthread_cond_init
> -function will return zero and put the new condition variable ID into
> +.Pp
> +The
> +.Fn pthread_cond_destroy
> +function frees the resources associated with the condition variable
> +.Fa cond .
> +.Pp
> +The
> +.Fn pthread_cond_wait
> +function atomically blocks the current thread by waiting on the condition
> +variable
>  .Fa cond ,
> -otherwise an error number will be returned to indicate the error.
> +and unlocks the mutex specified by
> +.Fa mutex .
> +The waiting thread unblocks only after another thread calls
> +.Fn pthread_cond_broadcast
> +or
> +.Fn pthread_cond_signal
> +with the same condition variable.
> +The
> +.Fn pthread_cond_timedwait
> +function does the same, but returns after the system time reaches
> +.Fa abstime .
> +In all cases, both functions then reacquire the lock on
> +.Fa mutex
> +before returning.
> +.Pp
> +The
> +.Fn pthread_cond_broadcast
> +function unblocks all threads waiting for the condition variable
> +.Fa cond .
> +The
> +.Fn pthread_cond_signal
> +function unblocks at least one thread waiting for the condition variable
> +.Fa cond .
> +.Sh RETURN VALUES
> +These functions return zero for success and positive error numbers
> +for failure.
>  .Sh ERRORS
>  .Fn pthread_cond_init
> -will fail if:
> +fails if:
>  .Bl -tag -width Er
>  .It Bq Er EINVAL
>  The value specified by
> @@ -71,13 +138,37 @@ variable.
>  The system temporarily lacks the resources to create another condition
>  variable.
>  .El
> +.Pp
> +The other functions fail if:
> +.Bl -tag -width Er
> +.It Bq Er EINVAL
> +The value specified by
> +.Fa cond ,
> +.Fa mutex ,
> +or
> +.Fa abstime
> +is invalid.
> +.Pp
> +.El

You have to change to order of macros here:

.El
.Pp

> +.Fn pthread_cond_destory

s/destory/destroy/

> +additionally fails if:
> +.Bl -tag -width Er
> +.It Bq Er EBUSY
> +The variable
> +.Fa cond
> +is locked by another thread.
> +.Pp
> +.El

Again:

.El
.Pp

> +.Fn pthread_cond_timedwait
> +additionally fails if:
> +.Bl -tag -width Er
> +.It Bq Er ETIMEDOUT
> +The system time has reached or exceeded the time specified in
> +.Fa abstime .
> +.El
>  .Sh SEE ALSO
> -.Xr pthread_cond_broadcast 3 ,
> -.Xr pthread_cond_destroy 3 ,
> -.Xr pthread_cond_signal 3 ,
> -.Xr pthread_cond_timedwait 3 ,
> -.Xr pthread_cond_wait 3
> +.Xr pthread_condattr_init 3 ,
> +.Xr pthread_mutex_init 3
>  .Sh STANDARDS
> -.Fn pthread_cond_init
> -conforms to
> +These functions conform to
>  .St -p1003.1-96 .
> Index: pthreads.3
> ===================================================================
> RCS file: /home/cvs/src/lib/libpthread/man/pthreads.3,v
> diff -u -p -r1.45 pthreads.3
> --- pthreads.3	21 Jun 2025 08:10:02 -0000	1.45
> +++ pthreads.3	2 Jul 2025 19:03:54 -0000
> @@ -412,12 +412,7 @@ with larger numbers generating more verb
>  .Xr pthread_cancel 3 ,
>  .Xr pthread_cleanup_pop 3 ,
>  .Xr pthread_cleanup_push 3 ,
> -.Xr pthread_cond_broadcast 3 ,
> -.Xr pthread_cond_destroy 3 ,
>  .Xr pthread_cond_init 3 ,
> -.Xr pthread_cond_signal 3 ,
> -.Xr pthread_cond_timedwait 3 ,
> -.Xr pthread_cond_wait 3 ,
>  .Xr pthread_condattr_init 3 ,
>  .Xr pthread_create 3 ,
>  .Xr pthread_detach 3 ,