Index | Thread | Search

From:
"Ted Unangst" <tedu@tedunangst.com>
Subject:
pthread mutex combo
To:
tech@openbsd.org
Date:
Sat, 05 Jul 2025 12:31:52 -0400

Download raw body.

Thread
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 .