From: "Ted Unangst" <tedu@tedunangst.com>
Subject: pthread_rwlock_combo
To: tech@openbsd.org
Date: Thu, 03 Jul 2025 14:53:55 -0400

I think the rwlock pages are also ripe for collection.
These are all Copyright (c) 1998 Alex Nash.

I reworked some of the wording so that that the timed and try lock functions
are together. I think the main body of description is easier to follow this
way.

The errors section could probably use another pass. I favored being specific,
but there are perhaps more lists than ideal.

Also some changes to make the language more direct, i.e.:
-function is used to initialize a read/write lock, with attributes
+function initializes a read/write lock, with attributes

Also some Index: pthread_rwlock_init.3
===================================================================
RCS file: /home/cvs/src/lib/libpthread/man/pthread_rwlock_init.3,v
diff -u -p -r1.9 pthread_rwlock_init.3
--- pthread_rwlock_init.3	7 Jun 2025 00:16:52 -0000	1.9
+++ pthread_rwlock_init.3	3 Jul 2025 18:40:19 -0000
@@ -24,40 +24,136 @@
 .\" SUCH DAMAGE.
 .\"
 .\" $FreeBSD: pthread_rwlock_init.3,v 1.2 1999/08/28 00:03:09 peter Exp $
+.\" $FreeBSD: pthread_rwlock_destroy.3,v 1.3 1999/08/28 00:03:09 peter Exp $
+.\" $FreeBSD: pthread_rwlock_rdlock.3,v 1.2 1999/08/28 00:03:09 peter Exp $
+.\" $FreeBSD: pthread_rwlock_wrlock.3,v 1.2 1999/08/28 00:03:10 peter Exp $
+.\" $FreeBSD: pthread_rwlock_unlock.3,v 1.2 1999/08/28 00:03:10 peter Exp $
 .\"
 .Dd $Mdocdate: June 7 2025 $
 .Dt PTHREAD_RWLOCK_INIT 3
 .Os
 .Sh NAME
-.Nm pthread_rwlock_init
-.Nd initialize a read/write lock
+.Nm pthread_rwlock_init ,
+.Nm pthread_rwlock_destroy ,
+.Nm pthread_rwlock_rdlock ,
+.Nm pthread_rwlock_timedrdlock ,
+.Nm pthread_rwlock_tryrdlock ,
+.Nm pthread_rwlock_wrlock ,
+.Nm pthread_rwlock_timedwrlock ,
+.Nm pthread_rwlock_trywrlock ,
+.Nm pthread_rwlock_unlock
+.Nd operations on read/write locks
 .Sh SYNOPSIS
 .Lb libpthread
 .In pthread.h
 .Ft int
-.Fn pthread_rwlock_init "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
+.Fo pthread_rwlock_init
+.Fa "pthread_rwlock_t *lock"
+.Fa "const pthread_rwlockattr_t *attr"
+.Fc
+.Ft int
+.Fo pthread_rwlock_destroy
+.Fa "pthread_rwlock_t *lock"
+.Fc
+.Ft int
+.Fo pthread_rwlock_rdlock
+.Fa "pthread_rwlock_t *lock"
+.Fc
+.Ft int
+.Fo pthread_rwlock_timedrdlock
+.Fa "pthread_rwlock_t *lock"
+.Fa "const struct timespec *abstime"
+.Fc
+.Ft int
+.Fo pthread_rwlock_tryrdlock
+.Fa "pthread_rwlock_t *lock"
+.Fc
+.Ft int
+.Fo pthread_rwlock_wrlock
+.Fa "pthread_rwlock_t *lock"
+.Fc
+.Ft int
+.Fo pthread_rwlock_timedwrlock
+.Fa "pthread_rwlock_t *lock"
+.Fa "const struct timespec *abstime"
+.Fc
+.Ft int
+.Fo pthread_rwlock_trywrlock
+.Fa "pthread_rwlock_t *lock"
+.Fc
+.Ft int
+.Fo pthread_rwlock_unlock
+.Fa "pthread_rwlock_t *lock"
+.Fc
 .Sh DESCRIPTION
 The
 .Fn pthread_rwlock_init
-function is used to initialize a read/write lock, with attributes
+function initializes a read/write lock, with attributes
 specified by
 .Fa attr .
 If
 .Fa attr
 is NULL, the default read/write lock attributes are used.
-.Pp
 The results of calling
 .Fn pthread_rwlock_init
 with an already initialized lock are undefined.
+.Pp
+The
+.Fn pthread_rwlock_destroy
+function destroys a read/write lock previously created with
+.Fn pthread_rwlock_init .
+.Pp
+The
+.Fn pthread_rwlock_rdlock
+function acquires a read lock on
+.Fa lock
+provided that
+.Fa lock
+is not presently held for writing and no writer threads are
+presently blocked on the lock.
+If the read lock cannot be immediately acquired,
+the calling thread blocks until it can acquire the lock.
+.Pp
+The
+.Fn pthread_rwlock_wrlock
+function blocks until a write lock can be acquired against
+.Fa lock .
+.Pp
+The
+.Fn pthread_rwlock_timedrdlock
+and
+.Fn pthread_rwlock_timedwrlock
+functions perform the same action,
+but will not wait beyond
+.Fa abstime
+to obtain the lock before returning.
+.Pp
+The
+.Fn pthread_rwlock_tryrdlock
+and
+.Fn pthread_rwlock_trywrlock
+functions perform the same action
+but do not block if the lock cannot be immediately obtained.
+.Pp
+The
+.Fn pthread_rwlock_unlock
+function releases the read/write lock previously obtained.
+.Pp
+A thread may hold multiple concurrent read locks.
+If so,
+.Fn pthread_rwlock_unlock
+must be called once for each lock obtained.
+.Pp
+The results of acquiring a read lock while the calling thread holds
+a write lock are undefined.
+The results of acquiring a write lock while the calling thread holds
+either a read or write lock are undefined.
 .Sh RETURN VALUES
-If successful, the
-.Fn pthread_rwlock_init
-function will return zero.
+If successful, these functions return zero.
 Otherwise an error number will be returned to indicate the error.
 .Sh ERRORS
-The
 .Fn pthread_rwlock_init
-function will fail if:
+fails if:
 .Bl -tag -width Er
 .It Bq Er EAGAIN
 The system lacked the necessary resources (other than memory) to
@@ -67,12 +163,6 @@ Insufficient memory exists to initialize
 .It Bq Er EPERM
 The caller does not have sufficient privilege to perform the
 operation.
-.El
-.Pp
-The
-.Fn pthread_rwlock_init
-function may fail if:
-.Bl -tag -width Er
 .It Bq Er EBUSY
 The system has detected an attempt to re-initialize the object
 referenced by
@@ -83,14 +173,88 @@ The value specified by
 .Fa attr
 is invalid.
 .El
+.Pp
+Other functions fail if:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The value specified by
+.Fa lock
+is invalid.
+.It Bq Er ENOMEM
+Insufficient memory exists to initialize the lock (applies to
+statically initialized locks only).
+.El
+.Pp
+.Fn pthread_rwlock_destroy
+fails if:
+.Bl -tag -width Er
+.It Bq Er EBUSY
+The system has detected an attempt to destroy the object referenced by
+.Fa lock
+while it is locked.
+.El
+.Pp
+.Fn pthread_rwlock_tryrdlock
+and
+.Fn pthread_rwlock_trywrlock
+fail if:
+.Bl -tag -width Er
+.It Bq Er EBUSY
+The lock could not be acquired without blocking.
+.El
+.Pp
+.Fn pthread_rwlock_timedrdlock
+and
+.Fn pthread_rwlock_timedwrlock
+fail if:
+.Bl -tag -width Er
+.It Bq Er ETIMEDOUT
+The time specified by
+.Fa abstime
+was reached before the lock could be obtained.
+.El
+.Pp
+The
+.Fn pthread_rwlock_rdlock ,
+.Fn pthread_rwlock_timedrdlock ,
+and
+.Fn pthread_rwlock_tryrdlock
+functions fail if:
+.Bl -tag -width Er
+.It Bq Er EAGAIN
+The lock could not be acquired because the maximum number of read locks
+against
+.Fa lock
+has been exceeded.
+.It Bq Er EDEADLK
+The current thread already owns
+.Fa lock
+for writing.
+.El
+.Pp
+The
+.Fn pthread_rwlock_wrlock ,
+.Fn pthread_rwlock_timedwrlock ,
+and
+.Fn pthread_rwlock_trywrlock
+functions fail if:
+.Bl -tag -width Er
+.It Bq Er EDEADLK
+The calling thread already owns the read/write lock (for reading
+or writing).
+.El
+.Pp
+The 
+.Fn pthread_rwlock_unlock
+fails if:
+.Bl -tag -width Er
+.It Bq Er EPERM
+The current thread does not own the read/write lock.
+.El
 .Sh SEE ALSO
-.Xr pthread_rwlock_destroy 3 ,
-.Xr pthread_rwlockattr_init 3 ,
-.Xr pthread_rwlockattr_setpshared 3
+.Xr pthread_rwlockattr_init 3
 .Sh STANDARDS
-The
-.Fn pthread_rwlock_init
-function is expected to conform to
+These functions are expected to conform to
 .St -susv2 .
 .Sh HISTORY
 The