git: d0d8362be2ed - stable/15 - pthread_mutex_clocklock.3: document
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
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 .