.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2024 Oxide Computer Company
.\"
.Dd June 22, 2024
.Dt PTHRAD_MUTEX_TIMEDLOCK 3C
.Os
.Sh NAME
.Nm pthread_mutex_clocklock ,
.Nm pthread_mutex_timedlock ,
.Nm pthread_mutex_relclocklock_np ,
.Nm pthread_mutex_reltimedlock_np
.Nd lock a mutex with a timeout
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In pthread.h
.In time.h
.Ft int
.Fo pthread_mutex_clocklock
.Fa "pthread_mutex_t *restrict mutex"
.Fa "clockid_t clock"
.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
.Ft int
.Fo pthread_mutex_relclocklock_np
.Fa "pthread_mutex_t *restrict mutex"
.Fa "clockid_t clock"
.Fa "const struct timespec *restrict rel_timeout"
.Fc
.Ft int
.Fo pthread_mutex_reltimedlock_np
.Fa "pthread_mutex_t *restrict mutex"
.Fa "const struct timespec *restrict rel_timeout"
.Fc
.Sh DESCRIPTION
The
.Fn pthread_mutex_clocklock ,
.Fn pthread_mutex_timedlock ,
.Fn pthread_mutex_relclocklock_np ,
and
.Fn pthread_mutex_reltimedlock_np
functions all lock the mutex object
.Fa mutex .
If the mutex is already locked, the calling thread will block until the
mutex becomes available just as
.Xr pthread_mutex_lock 3C ;
however, if the mutex does not become available within a specified
timeout, then the function call will terminate without acquiring the
lock and return the
.Er ETIMEDOUT
error.
These functions all differ in terms of how the timeout is specified and
the clock that is used to determine when the timeout has elapsed.
.Pp
In general, the system provides the ability to program timeouts against
either the realtime clock,
.Dv CLOCK_REALTIME ,
which measures the wall clock and is subject to changes due to time
synchronization daemons such as NTP and PTP, or the high-resolution clock,
.Dv CLOCK_HIGHRES ,
which is a non-adjustable high-resolution clock that is provided by
system hardware.
The specified timeout may either be specified as an absolute time in the
future or as a relative amount of time that should elapse.
Each clock has its own resolution, which can be determined by
.Xr clock_getres 3C .
Timeouts may be rounded up to a given clock's resolution.
Due to scheduling effects, it is possible that more time may elapse than
was specified in the timeout when the caller does not successfully
acquire the lock.
.Pp
The
.Fn pthread_mutex_clocklock
and
.Fn pthread_mutex_relclocklock_np
functions allow the clock source to be used to be specified by the
.Fa clock
argument.
While there are additional clocks in the system, only
.Dv CLOCK_REALTIME
or
.Dv CLOCK_HIGHRES
may be specified.
The thread and process-specific CPU time clocks cannot be used.
Conversely, the
.Fn pthread_mutex_timedlock
and
.Fn pthread_mutex_reltimedlock_np
functions will always utilize the realtime clock,
.Dv CLOCK_REALTIME .
.Pp
The
.Fn pthread_mutex_clocklock
and
.Fn pthread_mutex_timedlock
functions treat the timeout value,
.Fa abs_timeout ,
as the absolute time in the future when the timeout should expire.
Conversely, the
.Fn pthread_mutex_relclocklock_np
and
.Fn pthread_mutex_reltimedlock_np
functions operate in terms of a relative time.
The timer will expire when a specified amount of time passes on the
clock specified as indicated by
.Fa rel_timeout .
.Pp
If the mutex,
.Fa mutex ,
can be immediately locked, then the timeout value is ignored
entirely, even if the timeout had already expired or represented a
value that didn't make sense.
Both are only checked if the thread would block on the mutex itself.
.Pp
Mutexes may have priority inheritance enabled via the
.Dv PTHREAD_PRIO_INHERIT
attribute.
When a thread is blocked on a timed mutex, it may boost the priority of
the mutex owner based on the priority inheritance rules.
When the timer expires, the calling thread will no longer be blocking on
the mutex and therefore will no longer provide any potential priority
inheritance.
If it had boosted the holder of the mutex, then the owner's scheduling
priority will be re-evaluated.
.Sh RETURN VALUES
Upon successful completion, the
.Fn pthread_mutex_clocklock ,
.Fn pthread_mutex_timedlock ,
.Fn pthread_mutex_relclocklock_np ,
and
.Fn pthread_mutex_reltimedlock_np
functions will return
.Sy 0
and successfully have entered the mutex,
.Fa mutex .
Otherwise, an error number is returned to indicate the error.
.Sh ERRORS
The
.Fn pthread_mutex_clocklock ,
.Fn pthread_mutex_timedlock ,
.Fn pthread_mutex_relclocklock_np ,
and
.Fn pthread_mutex_reltimedlock_np
functions will all fail for the same reasons as
.Xr pthread_mutex_lock 3C .
In addition, they will fail if:
.Bl -tag -width Er
.It Er EINVAL
The caller would have blocked and the
.Fa timeout
parameter specified a nanoseconds field value less than zero or greater than or
equal to 1,000 million.
.Pp
For
.Fn pthread_mutex_clocklock
and
.Fn pthread_mutex_relclocklock_np
the value of
.Fa clock
is either unsupported for locking or unknown to the system.
.It Er ETIMEDOUT
The mutex could not be locked before the specified
.Fa timeout
expired.
.El
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Sy MT-Safe
.Sh SEE ALSO
.Xr time 2 ,
.Xr clock_getres 3C ,
.Xr pthread_mutex_destroy 3C ,
.Xr pthread_mutex_lock 3C ,
.Xr pthread_mutex_trylock  3C ,
.Xr attributes 7 ,
.Xr standards 7