From: "Ted Unangst" Subject: pthread mutex combo To: tech@openbsd.org Date: Sat, 05 Jul 2025 12:31:52 -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. 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 .