1.\" 2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 3.\" permission to reproduce portions of its copyrighted documentation. 4.\" Original documentation from The Open Group can be obtained online at 5.\" http://www.opengroup.org/bookstore/. 6.\" 7.\" The Institute of Electrical and Electronics Engineers and The Open 8.\" Group, have given us permission to reprint portions of their 9.\" documentation. 10.\" 11.\" In the following statement, the phrase ``this text'' refers to portions 12.\" of the system documentation. 13.\" 14.\" Portions of this text are reprinted and reproduced in electronic form 15.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, 16.\" Standard for Information Technology -- Portable Operating System 17.\" Interface (POSIX), The Open Group Base Specifications Issue 6, 18.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 19.\" Engineers, Inc and The Open Group. In the event of any discrepancy 20.\" between these versions and the original IEEE and The Open Group 21.\" Standard, the original IEEE and The Open Group Standard is the referee 22.\" document. The original Standard can be obtained online at 23.\" http://www.opengroup.org/unix/online.html. 24.\" 25.\" This notice shall appear on any product containing this material. 26.\" 27.\" The contents of this file are subject to the terms of the 28.\" Common Development and Distribution License (the "License"). 29.\" You may not use this file except in compliance with the License. 30.\" 31.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 32.\" or http://www.opensolaris.org/os/licensing. 33.\" See the License for the specific language governing permissions 34.\" and limitations under the License. 35.\" 36.\" When distributing Covered Code, include this CDDL HEADER in each 37.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 38.\" If applicable, add the following below this CDDL HEADER, with the 39.\" fields enclosed by brackets "[]" replaced with your own identifying 40.\" information: Portions Copyright [yyyy] [name of copyright owner] 41.\" 42.\" 43.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. 44.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. 45.\" Copyright 2024 Oxide Computer Company 46.\" 47.Dd June 22, 2024 48.Dt PTHRAD_MUTEX_TIMEDLOCK 3C 49.Os 50.Sh NAME 51.Nm pthread_mutex_clocklock , 52.Nm pthread_mutex_timedlock , 53.Nm pthread_mutex_relclocklock_np , 54.Nm pthread_mutex_reltimedlock_np 55.Nd lock a mutex with a timeout 56.Sh LIBRARY 57.Lb libc 58.Sh SYNOPSIS 59.In pthread.h 60.In time.h 61.Ft int 62.Fo pthread_mutex_clocklock 63.Fa "pthread_mutex_t *restrict mutex" 64.Fa "clockid_t clock" 65.Fa "const struct timespec *restrict abs_timeout" 66.Fc 67.Ft int 68.Fo pthread_mutex_timedlock 69.Fa "pthread_mutex_t *restrict mutex" 70.Fa "const struct timespec *restrict abs_timeout" 71.Fc 72.Ft int 73.Fo pthread_mutex_relclocklock_np 74.Fa "pthread_mutex_t *restrict mutex" 75.Fa "clockid_t clock" 76.Fa "const struct timespec *restrict rel_timeout" 77.Fc 78.Ft int 79.Fo pthread_mutex_reltimedlock_np 80.Fa "pthread_mutex_t *restrict mutex" 81.Fa "const struct timespec *restrict rel_timeout" 82.Fc 83.Sh DESCRIPTION 84The 85.Fn pthread_mutex_clocklock , 86.Fn pthread_mutex_timedlock , 87.Fn pthread_mutex_relclocklock_np , 88and 89.Fn pthread_mutex_reltimedlock_np 90functions all lock the mutex object 91.Fa mutex . 92If the mutex is already locked, the calling thread will block until the 93mutex becomes available just as 94.Xr pthread_mutex_lock 3C ; 95however, if the mutex does not become available within a specified 96timeout, then the function call will terminate without acquiring the 97lock and return the 98.Er ETIMEDOUT 99error. 100These functions all differ in terms of how the timeout is specified and 101the clock that is used to determine when the timeout has elapsed. 102.Pp 103In general, the system provides the ability to program timeouts against 104either the realtime clock, 105.Dv CLOCK_REALTIME , 106which measures the wall clock and is subject to changes due to time 107synchronization daemons such as NTP and PTP, or the high-resolution clock, 108.Dv CLOCK_HIGHRES , 109which is a non-adjustable high-resolution clock that is provided by 110system hardware. 111The specified timeout may either be specified as an absolute time in the 112future or as a relative amount of time that should elapse. 113Each clock has its own resolution, which can be determined by 114.Xr clock_getres 3C . 115Timeouts may be rounded up to a given clock's resolution. 116Due to scheduling effects, it is possible that more time may elapse than 117was specified in the timeout when the caller does not successfully 118acquire the lock. 119.Pp 120The 121.Fn pthread_mutex_clocklock 122and 123.Fn pthread_mutex_relclocklock_np 124functions allow the clock source to be used to be specified by the 125.Fa clock 126argument. 127While there are additional clocks in the system, only 128.Dv CLOCK_REALTIME 129or 130.Dv CLOCK_HIGHRES 131may be specified. 132The thread and process-specific CPU time clocks cannot be used. 133Conversely, the 134.Fn pthread_mutex_timedlock 135and 136.Fn pthread_mutex_reltimedlock_np 137functions will always utilize the realtime clock, 138.Dv CLOCK_REALTIME . 139.Pp 140The 141.Fn pthread_mutex_clocklock 142and 143.Fn pthread_mutex_timedlock 144functions treat the timeout value, 145.Fa abs_timeout , 146as the absolute time in the future when the timeout should expire. 147Conversely, the 148.Fn pthread_mutex_relclocklock_np 149and 150.Fn pthread_mutex_reltimedlock_np 151functions operate in terms of a relative time. 152The timer will expire when a specified amount of time passes on the 153clock specified as indicated by 154.Fa rel_timeout . 155.Pp 156If the mutex, 157.Fa mutex , 158can be immediately locked, then the timeout value is ignored 159entirely, even if the timeout had already expired or represented a 160value that didn't make sense. 161Both are only checked if the thread would block on the mutex itself. 162.Pp 163Mutexes may have priority inheritance enabled via the 164.Dv PTHREAD_PRIO_INHERIT 165attribute. 166When a thread is blocked on a timed mutex, it may boost the priority of 167the mutex owner based on the priority inheritance rules. 168When the timer expires, the calling thread will no longer be blocking on 169the mutex and therefore will no longer provide any potential priority 170inheritance. 171If it had boosted the holder of the mutex, then the owner's scheduling 172priority will be re-evaluated. 173.Sh RETURN VALUES 174Upon successful completion, the 175.Fn pthread_mutex_clocklock , 176.Fn pthread_mutex_timedlock , 177.Fn pthread_mutex_relclocklock_np , 178and 179.Fn pthread_mutex_reltimedlock_np 180functions will return 181.Sy 0 182and successfully have entered the mutex, 183.Fa mutex . 184Otherwise, an error number is returned to indicate the error. 185.Sh ERRORS 186The 187.Fn pthread_mutex_clocklock , 188.Fn pthread_mutex_timedlock , 189.Fn pthread_mutex_relclocklock_np , 190and 191.Fn pthread_mutex_reltimedlock_np 192functions will all fail for the same reasons as 193.Xr pthread_mutex_lock 3C . 194In addition, they will fail if: 195.Bl -tag -width Er 196.It Er EINVAL 197The caller would have blocked and the 198.Fa timeout 199parameter specified a nanoseconds field value less than zero or greater than or 200equal to 1,000 million. 201.Pp 202For 203.Fn pthread_mutex_clocklock 204and 205.Fn pthread_mutex_relclocklock_np 206the value of 207.Fa clock 208is either unsupported for locking or unknown to the system. 209.It Er ETIMEDOUT 210The mutex could not be locked before the specified 211.Fa timeout 212expired. 213.El 214.Sh INTERFACE STABILITY 215.Sy Committed 216.Sh MT-LEVEL 217.Sy MT-Safe 218.Sh SEE ALSO 219.Xr time 2 , 220.Xr clock_getres 3C , 221.Xr pthread_mutex_destroy 3C , 222.Xr pthread_mutex_lock 3C , 223.Xr pthread_mutex_trylock 3C , 224.Xr attributes 7 , 225.Xr standards 7 226