Hello Ted,

Ted Unangst wrote on Sat, Jul 05, 2025 at 12:31:52PM -0400:

> And now the same for mutex. Pretty much same as before.
> 
> I removed some description text about errors that duplicates the errors
> section. I preserved the partial lie about unlock returning an error.

OK schwarze@ except that you need to sort ERRORS and that you broke
STANDARDS.

Saying that pthread_mutex_timedlock(3) conforms to -p1003.1-96 is a lie.
That function was only introduced in -p1003.1-2001 as part of the
advanced realtime extensions.

The simplest way to fix this is to just keep the text as it is, i.e.

The functions
.Fn pthread_mutex_init ,
.Fn pthread_mutex_destroy ,
and
.Fn pthread_mutex_unlock
conform to
.St -p1003.1-96 .
The functions
.Fn pthread_mutex_lock ,
.Fn pthread_mutex_timedlock ,
and
.Fn pthread_mutex_trylock
conform to
.St -p1003.1-2008 .

That lazy copout seems acceptable for now, but not very good in the
long run.  It is likely to make readers wonder why we conform to
inconsistent standards.  It would seem desirable to check whether we
conform to -p1003.1-2024 and update to that if we do.

It appears that guenther@ checked on 2012/02/24 that the three *lock*
functions conform to -p1003.1-2008 but didn't go any further than that.

Yours,
  Ingo


> Index: pthread_mutex_init.3
> ===================================================================
> RCS file: /home/cvs/src/lib/libpthread/man/pthread_mutex_init.3,v
> diff -u -p -r1.15 pthread_mutex_init.3
> --- pthread_mutex_init.3	7 Jun 2025 00:16:52 -0000	1.15
> +++ pthread_mutex_init.3	5 Jul 2025 04:37:17 -0000
> @@ -28,18 +28,50 @@
>  .\" SUCH DAMAGE.
>  .\"
>  .\" $FreeBSD: pthread_mutex_init.3,v 1.6 1999/08/28 00:03:07 peter Exp $
> +.\" $FreeBSD: pthread_mutex_destroy.3,v 1.5 1999/08/28 00:03:07 peter Exp $
> +.\" $FreeBSD: pthread_mutex_lock.3,v 1.5 1999/08/28 00:03:07 peter Exp $
> +.\" $FreeBSD: pthread_mutex_unlock.3,v 1.5 1999/08/28 00:03:08 peter Exp $
>  .\"
>  .Dd $Mdocdate: June 7 2025 $
>  .Dt PTHREAD_MUTEX_INIT 3
>  .Os
>  .Sh NAME
> -.Nm pthread_mutex_init
> -.Nd create a mutex
> +.Nm pthread_mutex_init ,
> +.Nm pthread_mutex_destroy ,
> +.Nm pthread_mutex_lock ,
> +.Nm pthread_mutex_timedlock ,
> +.Nm pthread_mutex_trylock ,
> +.Nm pthread_mutex_unlock
> +.Nd operations on mutex variables
>  .Sh SYNOPSIS
>  .Lb libpthread
>  .In pthread.h
>  .Ft int
> -.Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
> +.Fo pthread_mutex_init
> +.Fa "pthread_mutex_t *mutex"
> +.Fa "const pthread_mutexattr_t *attr"
> +.Fc
> +.Ft int
> +.Fo pthread_mutex_destroy
> +.Fa "pthread_mutex_t *mutex"
> +.Fc
> +.Ft int
> +.Fo pthread_mutex_lock
> +.Fa "pthread_mutex_t *mutex"
> +.Fc
> +.Ft int
> +.Fo pthread_mutex_timedlock
> +.Fa "pthread_mutex_t *mutex"
> +.Fa "const struct timespec *abstime"
> +.Fc
> +.Ft int
> +.Fo pthread_mutex_trylock
> +.Fa "pthread_mutex_t *mutex"
> +.Fc
> +.Ft int
> +.Fo pthread_mutex_unlock
> +.Fa "pthread_mutex_t *mutex"
> +.Fc
>  .Sh DESCRIPTION
>  The
>  .Fn pthread_mutex_init
> @@ -56,15 +88,75 @@ should be initialized by calling
>  .Pp
>  A mutex may also be initialized by assignment with the macro
>  PTHREAD_MUTEX_INITIALIZER.
> +.Pp
> +The
> +.Fn pthread_mutex_destroy
> +function frees the resources allocated for
> +.Fa mutex .
> +.Pp
> +The
> +.Fn pthread_mutex_lock
> +function locks
> +.Fa mutex .
> +If the mutex is currently locked by another thread,
> +the calling thread will block until the
> +mutex becomes available.
> +.Pp
> +If the mutex is currently locked by the calling thread,
> +then the behavior depends on the type of the mutex.
> +If
> +.Fa mutex
> +is of type
> +.Dv PTHREAD_MUTEX_NORMAL ,
> +then the calling thread will deadlock and never return from
> +.Fn pthread_mutex_lock .
> +If
> +.Fa mutex
> +is of type
> +.Dv PTHREAD_MUTEX_ERRORCHECK ,
> +then
> +.Er EDEADLK
> +is immediately returned.
> +If
> +.Fa mutex
> +is of type
> +.Dv PTHREAD_MUTEX_RECURSIVE ,
> +then the recursion count on the mutex is incremented.
> +.Pp
> +The
> +.Fn pthread_mutex_timedlock
> +function locks
> +.Fa mutex
> +like
> +.Fn pthread_mutex_lock
> +except that it will not block or deadlock past the system time
> +specified in
> +.Fa abstime .
> +.Pp
> +The
> +.Fn pthread_mutex_trylock
> +function locks
> +.Fa mutex
> +like
> +.Fn pthread_mutex_lock
> +except that if
> +.Fa mutex
> +is locked by another thread,
> +or is locked by the calling thread and is not of type
> +.Dv PTHREAD_MUTEX_RECURSIVE ,
> +then it will immediately return
> +.Er EBUSY .
> +.Pp
> +The
> +.Fn pthread_mutex_unlock
> +function unlocks the previously locked
> +.Fa mutex .
>  .Sh RETURN VALUES
> -If successful,
> -.Fn pthread_mutex_init
> -will return zero and put the new mutex ID into
> -.Fa mutex ,
> -otherwise an error number will be returned to indicate the error.
> +These functions return zero for success and positive error numbers
> +for failure.
>  .Sh ERRORS
>  .Fn pthread_mutex_init
> -will fail if:
> +fails if:
>  .Bl -tag -width Er
>  .It Bq Er EINVAL
>  The value specified by
> @@ -73,12 +165,70 @@ is invalid.
>  .It Bq Er ENOMEM
>  The process cannot allocate enough memory to create another mutex.
>  .El
> +.Pp
> +The other functions fail if:
> +.Bl -tag -width Er
> +.It Bq Er EINVAL
> +The value specified by
> +.Fa mutex
> +is invalid.
> +.El
> +.Pp
> +.Fn pthread_mutex_destroy
> +fails if:
> +.Bl -tag -width Er
> +.It Bq Er EBUSY
> +.Fa mutex
> +is locked or referenced by another thread.
> +.El
> +.Pp
> +.Fn pthread_mutex_lock ,
> +.Fn pthread_mutex_timedlock ,
> +and
> +.Fn pthread_mutex_trylock
> +fail if:
> +.Bl -tag -width Er
> +.It Bq Er EAGAIN
> +The mutex is of type
> +.Dv PTHREAD_MUTEX_RECURSIVE
> +and the maximum recursion count has been reached.
> +.El
> +.Pp
> +.Fn pthread_mutex_lock
> +and
> +.Fn pthread_mutex_timedlock
> +fail if:
> +.Bl -tag -width Er
> +.It Bq Er EDEADLK
> +The mutex is of type
> +.Dv PTHREAD_MUTEX_ERRORCHECK
> +and is already locked by the calling thread.
> +.El
> +.Pp
> +.Fn pthread_mutex_timedlock
> +fails if:
> +.Bl -tag -width Er
> +.It Bq Er ETIMEDOUT
> +The mutex could not be locked and the specified time was reached.
> +.El
> +.Pp
> +.Fn pthread_mutex_trylock
> +fails if:
> +.Bl -tag -width Er
> +.It Bq Er EBUSY
> +The mutex could not be locked because it was already locked.
> +.El
> +.Pp
> +.Fn pthread_mutex_unlock
> +fails if:
> +.Bl -tag -width Er
> +.It Bq Er EPERM
> +The current thread does not hold a lock on
> +.Fa mutex .
> +.El
>  .Sh SEE ALSO
> -.Xr pthread_mutex_destroy 3 ,
> -.Xr pthread_mutex_lock 3 ,
> -.Xr pthread_mutex_unlock 3 ,
> +.Xr pthreads 3 ,
>  .Xr pthread_mutexattr_init 3
>  .Sh STANDARDS
> -.Fn pthread_mutex_init
> -conforms to
> +These functions conform to
>  .St -p1003.1-96 .