git: 522407f54078 - main - pthread_rwlock_clock{rd,wr}lock(3): document
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
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 .