git: 522407f54078 - main - pthread_rwlock_clock{rd,wr}lock(3): document

From: Konstantin Belousov <kib_at_FreeBSD.org>
Date: Tue, 10 Nov 2026 00:22:15 UTC
The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=522407f54078e986bca5a74c8335881c6a1afe81

commit 522407f54078e986bca5a74c8335881c6a1afe81
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2026-11-05 22:40:23 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2026-11-10 00:21:19 +0000

    pthread_rwlock_clock{rd,wr}lock(3): document
    
    Reviewed by:    markj
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
    Differential revision:  https://reviews.freebsd.org/D61253
---
 share/man/man3/Makefile                     |  2 +
 share/man/man3/pthread_rwlock_timedrdlock.3 | 62 ++++++++++++++++++++---------
 share/man/man3/pthread_rwlock_timedwrlock.3 | 62 ++++++++++++++++++++---------
 3 files changed, 88 insertions(+), 38 deletions(-)

diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile
index 4d80fea05b88..7893193fe357 100644
--- a/share/man/man3/Makefile
+++ b/share/man/man3/Makefile
@@ -530,6 +530,8 @@ PTHREAD_MLINKS+=pthread_mutexattr.3 pthread_mutexattr_destroy.3 \
 PTHREAD_MLINKS+=pthread_mutexattr_getkind_np.3 pthread_mutexattr_setkind_np.3
 PTHREAD_MLINKS+=pthread_rwlock_rdlock.3 pthread_rwlock_tryrdlock.3
 PTHREAD_MLINKS+=pthread_rwlock_wrlock.3 pthread_rwlock_trywrlock.3
+PTHREAD_MLINKS+=pthread_rwlock_timedwrlock.3 pthread_rwlock_clockwrlock.3
+PTHREAD_MLINKS+=pthread_rwlock_timedrdlock.3 pthread_rwlock_clockrdlock.3
 PTHREAD_MLINKS+=pthread_schedparam.3 pthread_getschedparam.3 \
 		pthread_schedparam.3 pthread_setschedparam.3
 PTHREAD_MLINKS+=pthread_set_name_np.3 pthread_get_name_np.3 \
diff --git a/share/man/man3/pthread_rwlock_timedrdlock.3 b/share/man/man3/pthread_rwlock_timedrdlock.3
index 4feb6c9910a0..778c61b1349e 100644
--- a/share/man/man3/pthread_rwlock_timedrdlock.3
+++ b/share/man/man3/pthread_rwlock_timedrdlock.3
@@ -26,6 +26,7 @@
 .Dt PTHREAD_RWLOCK_TIMEDRDLOCK 3
 .Os
 .Sh NAME
+.Nm pthread_rwlock_clockrdlock ,
 .Nm pthread_rwlock_timedrdlock
 .Nd "acquire a read-write lock for reading or give up after a specified period"
 .Sh LIBRARY
@@ -33,19 +34,32 @@
 .Sh SYNOPSIS
 .In pthread.h
 .Ft int
+.Fo pthread_rwlock_clockrdlock
+.Fa "pthread_rwlock_t *restrict rwlock"
+.Fa "clockid_t clockid"
+.Fa "const struct timespec *restrict abs_timeout"
+.Fc
+.Ft int
 .Fo pthread_rwlock_timedrdlock
 .Fa "pthread_rwlock_t *restrict rwlock"
 .Fa "const struct timespec *restrict abs_timeout"
 .Fc
 .Sh DESCRIPTION
-This function acquires a read lock on the read-write lock
+These functions acquire a read lock on the read-write lock
 .Fa rwlock .
 However, if the lock cannot be
 acquired without waiting for another thread to
 unlock the lock,
-this wait shall be terminated when
+this wait is terminated when
 .Fa abs_timeout
 expires.
+The
+.Fa abs_timeout
+value is an absolute time, measured on
+.Fa clockid
+for the clock variant and on
+.Dv CLOCK_REALTIME
+for the timed variant.
 .Pp
 A thread may hold multiple concurrent read locks.
 The
@@ -53,38 +67,30 @@ The
 function must be called once for each lock acquired.
 .Pp
 If the thread should be interrupted by a signal,
-the
-.Fn pthread_rwlock_timedrdlock
-function will be automatically restarted after the thread returns from
-the signal handler.
+the functions are automatically restarted after the thread
+returns from the signal handler.
 .Pp
 The calling thread may deadlock if
 at the time the call is made it holds a write lock on
 .Fa rwlock .
-The results are undefined if this function is called with
+The results are undefined if these functions are called with
 an uninitialized read-write lock.
 .Sh IMPLEMENTATION NOTES
 To prevent writer starvation, writers are favored over readers.
 .Sh RETURN VALUES
-If successful, the
-.Fn pthread_rwlock_timedrdlock
-function will return zero.
+If successful, the functions will return zero.
 Otherwise, an error number will be returned to indicate the error.
 .Pp
-This function shall not return an error code of
+These functions do not return an error code of
 .Er EINTR .
 .Sh ERRORS
-The
-.Fn pthread_rwlock_timedrdlock
-function will fail if:
+The functions will fail if:
 .Bl -tag -width Er
 .It Bq Er ETIMEDOUT
 The lock could not be acquired before the specified timeout expired.
 .El
 .Pp
-The
-.Fn pthread_rwlock_timedrdlock
-function may fail if:
+The functions may fail if:
 .Bl -tag -width Er
 .It Bq Er EAGAIN
 The read lock could not be
@@ -101,7 +107,17 @@ does not refer to an initialized read-write lock object,
 or the
 .Fa abs_timeout
 nanosecond value is less than zero or
-greater than or equal to 1 billion.
+greater than or equal to 1 billion, or the
+.Fa clockid
+parameter is invalid.
+.Pp
+The
+.Dv CLOCK_REALTIME
+and
+.Dv CLOCK_MONOTONIC
+clocks are always supported; see
+.Xr _umtx_op 2
+for the full list of accepted clocks.
 .El
 .Sh SEE ALSO
 .Xr pthread_rwlock_init 3 ,
@@ -110,10 +126,18 @@ greater than or equal to 1 billion.
 .Sh STANDARDS
 The
 .Fn pthread_rwlock_timedrdlock
-function is expected to conform to
+function conforms to
 .St -p1003.1-96 .
+The
+.Fn pthread_rwlock_clockrdlock
+function conforms to
+.St -p1003.1-2024 .
 .Sh HISTORY
 The
 .Fn pthread_rwlock_timedrdlock
 function first appeared in
 .Fx 5.2 .
+The
+.Fn pthread_rwlock_clockrdlock
+function first appeared in
+.Fx 16.0 .
diff --git a/share/man/man3/pthread_rwlock_timedwrlock.3 b/share/man/man3/pthread_rwlock_timedwrlock.3
index c3267d694534..89d76d42834f 100644
--- a/share/man/man3/pthread_rwlock_timedwrlock.3
+++ b/share/man/man3/pthread_rwlock_timedwrlock.3
@@ -26,6 +26,7 @@
 .Dt PTHREAD_RWLOCK_TIMEDWRLOCK 3
 .Os
 .Sh NAME
+.Nm pthread_rwlock_clockwrlock ,
 .Nm pthread_rwlock_timedwrlock
 .Nd "acquire a read-write lock for writing or give up after a specified period"
 .Sh LIBRARY
@@ -33,53 +34,58 @@
 .Sh SYNOPSIS
 .In pthread.h
 .Ft int
+.Fo pthread_rwlock_clockwrlock
+.Fa "pthread_rwlock_t *restrict rwlock"
+.Fa "clockid_t clockid"
+.Fa "const struct timespec *restrict abs_timeout"
+.Fc
+.Ft int
 .Fo pthread_rwlock_timedwrlock
 .Fa "pthread_rwlock_t *restrict rwlock"
 .Fa "const struct timespec *restrict abs_timeout"
 .Fc
 .Sh DESCRIPTION
-This function acquires a write lock on the read-write lock
+These functions acquire a write lock on the read-write lock
 .Fa rwlock .
 However, if the lock cannot be
 acquired without waiting for another thread to
 unlock the lock,
-this wait shall be terminated when
+this wait is terminated when
 .Fa abs_timeout
 expires.
+The
+.Fa abs_timeout
+value is an absolute time, measured on
+.Fa clockid
+for the clock variant and on
+.Dv CLOCK_REALTIME
+for the timed variant.
 .Pp
 If the thread should be interrupted by a signal,
-the
-.Fn pthread_rwlock_timedwrlock
-function will be automatically restarted after the thread returns from
-the signal handler.
+the functions are automatically restarted after the thread
+returns from the signal handler.
 .Pp
 The calling thread may deadlock if
 at the time the call is made it holds
 .Fa rwlock .
-The results are undefined if this function is called with
+The results are undefined if these functions are called with
 an uninitialized read-write lock.
 .Sh IMPLEMENTATION NOTES
 To prevent writer starvation, writers are favored over readers.
 .Sh RETURN VALUES
-If successful, the
-.Fn pthread_rwlock_timedwrlock
-function will return zero.
+If successful, the functions will return zero.
 Otherwise, an error number will be returned to indicate the error.
 .Pp
-This function shall not return an error code of
+These functions do not return an error code of
 .Er EINTR .
 .Sh ERRORS
-The
-.Fn pthread_rwlock_timedwrlock
-function shall fail if:
+The functions will fail if:
 .Bl -tag -width Er
 .It Bq Er ETIMEDOUT
 The lock could not be acquired before the specified timeout expired.
 .El
 .Pp
-The
-.Fn pthread_rwlock_timedwrlock
-function may fail if:
+The functions may fail if:
 .Bl -tag -width Er
 .It Bq Er EDEADLK
 The calling thread already holds
@@ -91,7 +97,17 @@ does not refer to an initialized read-write lock object,
 or the
 .Fa abs_timeout
 nanosecond value is less than zero or
-greater than or equal to 1 billion.
+greater than or equal to 1 billion, or the
+.Fa clockid
+parameter is invalid.
+.Pp
+The
+.Dv CLOCK_REALTIME
+and
+.Dv CLOCK_MONOTONIC
+clocks are always supported; see
+.Xr _umtx_op 2
+for the full list of accepted clocks.
 .El
 .Sh SEE ALSO
 .Xr pthread_rwlock_init 3 ,
@@ -100,10 +116,18 @@ greater than or equal to 1 billion.
 .Sh STANDARDS
 The
 .Fn pthread_rwlock_timedwrlock
-function is expected to conform to
+function conforms to
 .St -p1003.1-96 .
+The
+.Fn pthread_rwlock_clockwrlock
+function conforms to
+.St -p1003.1-2024 .
 .Sh HISTORY
 The
 .Fn pthread_rwlock_timedwrlock
 function first appeared in
 .Fx 5.2 .
+The
+.Fn pthread_rwlock_clockwrlock
+function first appeared in
+.Fx 16.0 .