git: d0d8362be2ed - stable/15 - pthread_mutex_clocklock.3: document

From: Konstantin Belousov <kib_at_FreeBSD.org>
Date: Tue, 17 Nov 2026 01:09:52 UTC
The branch stable/15 has been updated by kib:

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

commit d0d8362be2ed97a2536e39ae614e959a54722a26
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2026-11-05 18:32:08 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2026-11-17 00:25:03 +0000

    pthread_mutex_clocklock.3: document
    
    (cherry picked from commit 1c08e2b915bf44dacd5b14ee8d8214ef40946c65)
---
 share/man/man3/Makefile                  |  1 +
 share/man/man3/pthread_mutex_timedlock.3 | 70 ++++++++++++++++++++++++++------
 2 files changed, 59 insertions(+), 12 deletions(-)

diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile
index 874926bda0f1..4d80fea05b88 100644
--- a/share/man/man3/Makefile
+++ b/share/man/man3/Makefile
@@ -514,6 +514,7 @@ PTHREAD_MLINKS+=pthread_condattr.3 pthread_condattr_destroy.3 \
 PTHREAD_MLINKS+=pthread_cond_timedwait.3 pthread_cond_clockwait.3
 PTHREAD_MLINKS+=pthread_getconcurrency.3 pthread_setconcurrency.3
 PTHREAD_MLINKS+=pthread_multi_np.3 pthread_single_np.3
+PTHREAD_MLINKS+=pthread_mutex_timedlock.3 pthread_mutex_clocklock.3
 PTHREAD_MLINKS+=pthread_mutexattr.3 pthread_mutexattr_destroy.3 \
 		pthread_mutexattr.3 pthread_mutexattr_getprioceiling.3 \
 		pthread_mutexattr.3 pthread_mutexattr_getprotocol.3 \
diff --git a/share/man/man3/pthread_mutex_timedlock.3 b/share/man/man3/pthread_mutex_timedlock.3
index 59d9c3883637..16aadf76430b 100644
--- a/share/man/man3/pthread_mutex_timedlock.3
+++ b/share/man/man3/pthread_mutex_timedlock.3
@@ -26,6 +26,7 @@
 .Dt PTHREAD_MUTEX_TIMEDLOCK 3
 .Os
 .Sh NAME
+.Nm pthread_mutex_clocklock ,
 .Nm pthread_mutex_timedlock
 .Nd lock a mutex without blocking indefinitely
 .Sh LIBRARY
@@ -34,33 +35,58 @@
 .In pthread.h
 .In time.h
 .Ft int
+.Fo pthread_mutex_clocklock
+.Fa "pthread_mutex_t *restrict mutex"
+.Fa "clockid_t clockid"
+.Fa "const struct timespec *restrict abs_timeout"
+.Fc
+.Ft int
 .Fo pthread_mutex_timedlock
 .Fa "pthread_mutex_t *restrict mutex"
 .Fa "const struct timespec *restrict abs_timeout"
 .Fc
 .Sh DESCRIPTION
 The
-.Fn pthread_mutex_timedlock
-function will lock
+.Fn pthread_mutex_clocklock
+function locks
 .Fa mutex .
-If it is already locked the calling thread will block until
-the mutex becomes available or
-the timeout,
-specified by abs_timeout,
-expires.
-The time of the timeout is an absolute time and
-is not relative to the current time.
+If the mutex is already locked, the calling thread blocks until the
+mutex becomes available or the timeout expires.
+The timeout expires when the clock specified by
+.Fa clockid
+reaches or passes the absolute time
+.Fa abs_timeout ;
+it is not relative to the current time.
+If the mutex can be locked immediately, the call does not fail
+with a timeout, and
+.Fa abs_timeout
+and
+.Fa clockid
+are not checked for validity.
+.Pp
+The
+.Fn pthread_mutex_timedlock
+function is equivalent to
+.Fn pthread_mutex_clocklock
+with
+.Fa clockid
+set to
+.Dv CLOCK_REALTIME .
 .Sh RETURN VALUES
 If successful,
+.Fn pthread_mutex_clocklock
+and
 .Fn pthread_mutex_timedlock
 will return zero, otherwise an error number will be returned to
 indicate the error.
 .Sh ERRORS
 The
+.Fn pthread_mutex_clocklock
+and
 .Fn pthread_mutex_timedlock
-function will fail if:
+functions will fail if:
 .Bl -tag -width Er
-.It Bq "Er ENOTRECOVERABLE"
+.It Bq Er ENOTRECOVERABLE
 The
 .Fa mutex
 was created with the protocol attribute having the
@@ -76,6 +102,17 @@ greater than or equal to 1 billion.
 The
 .Fa mutex
 parameter is invalid.
+.It Bq Er EINVAL
+The
+.Fa clockid
+parameter is invalid.
+The
+.Dv CLOCK_REALTIME
+and
+.Dv CLOCK_MONOTONIC
+clocks are always supported; see
+.Xr _umtx_op 2
+for the full list of accepted clocks.
 .It Bq Er ETIMEDOUT
 The
 .Fa mutex
@@ -112,5 +149,14 @@ is not recoverable.
 .Sh STANDARDS
 The
 .Fn pthread_mutex_timedlock
-function is expected to conform to
+function conforms to
 .St -p1003.1-96 .
+The
+.Fn pthread_mutex_clocklock
+function conforms to
+.St -p1003.1-2024 .
+.Sh HISTORY
+The
+.Fn pthread_mutex_clocklock
+function first appeared in
+.Fx 16.0 .