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 1991, 1992, 1994, The X/Open Company Ltd. 44.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. 45.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. 46.\" Copyright 2024 Oxide Computer Company 47.\" 48.Dd June 23, 2024 49.Dt PTHREAD_COND_WAIT 3C 50.Os 51.Sh NAME 52.Nm pthread_cond_wait , 53.Nm pthread_cond_clockwait , 54.Nm pthread_cond_timedwait , 55.Nm pthread_cond_relclockwait_np , 56.Nm pthread_cond_reltimedwait_np 57.Nd wait on a condition 58.Sh LIBRARY 59.Lb libc 60.Sh SYNOPSIS 61.Ft int 62.Fo pthread_cond_wait 63.Fa "pthread_cond_t *restrict cond" 64.Fa "pthread_mutex_t *restrict mutex" 65.Fc 66.Ft int 67.Fo pthread_cond_clockwait 68.Fa "pthread_cond_t *restrict cond" 69.Fa "pthread_mutex_t *restrict mutex" 70.Fa "clockid_t clock" 71.Fa "const struct timespec *restrict abstime" 72.Fc 73.Ft int 74.Fo pthread_cond_timedwait 75.Fa "pthread_cond_t *restrict cond" 76.Fa "pthread_mutex_t *restrict mutex" 77.Fa "const struct timespec *restrict abstime" 78.Fc 79.Ft int 80.Fo pthread_cond_relclockwait_np 81.Fa "pthread_cond_t *restrict cond" 82.Fa "pthread_mutex_t *restrict mutex" 83.Fa "clockid_t clock" 84.Fa "const struct timespec *restrict reltime" 85.Fc 86.Ft int 87.Fo pthread_cond_reltimedwait_np 88.Fa "pthread_cond_t *restrict cond" 89.Fa "pthread_mutex_t *restrict mutex" 90.Fa "const struct timespec *restrict reltime" 91.Fc 92.Sh DESCRIPTION 93The 94.Fn pthread_cond_wait , 95.Fn pthread_cond_clockwait , 96.Fn pthread_cond_timedwait , 97.Fn pthread_cond_relclockwait_np , 98and 99.Fn pthread_cond_reltimedwait_np 100functions are used to block on a condition variable. 101They must be called with 102.Fa mutex 103locked by the calling thread or undefined behavior will result. 104.Pp 105These functions atomically release 106.Fa mutex 107and cause the calling thread to block on the condition variable 108.Fa cond . 109Atomically here means atomically with respect to access by another thread to 110the mutex and then the condition variable. 111That is, if another thread is able to acquire the mutex after the about-to-block 112thread has released it, then a subsequent call to 113.Xr pthread_cond_signal 3C 114or 115.Xr pthread_cond_broadcast 3C 116in that thread behaves as if it were issued after the about-to-block thread has 117blocked. 118.Pp 119Upon successful return, the mutex has been locked and is owned by the calling 120thread. 121If mutex is a robust mutex where an owner terminated while holding the lock and 122the state is recoverable, the mutex is acquired even though the function returns 123an error value. 124.Pp 125When using condition variables there is always a boolean predicate, an 126invariant, associated with each condition wait that must be true before the 127thread should proceed. 128Spurious wakeups from the 129.Fn pthread_cond_wait , 130.Fn pthread_cond_clockwait , 131.Fn pthread_cond_timedwait , 132.Fn pthread_cond_relclockwait_np , 133or 134.Fn pthread_cond_reltimedwait_np 135functions could occur. 136The return from these functions does not imply anything about the value of this 137predicate and the predicate must always be reevaluated. 138.Pp 139The order in which blocked threads are awakened by 140.Xr pthread_cond_signal 3C 141or 142.Xr pthread_cond_broadcast 3C 143is determined by the scheduling policy. 144See 145.Xr pthread 7 . 146.Pp 147The effect of using more than one mutex for concurrent 148.Fn pthread_cond_wait , 149.Fn pthread_cond_clockwait , 150.Fn pthread_cond_timedwait , 151.Fn pthread_cond_relclockwait_np , 152or 153.Fn pthread_cond_reltimedwait_np 154operations on the same condition variable will result in undefined behavior. 155.Pp 156A condition wait 157.Pq whether timed or not 158is a cancellation point. 159When the cancelability enable state of a thread is set to 160.Dv PTHREAD_CANCEL_DEFERRED , 161a side effect of acting upon a cancellation request while in a condition wait 162is that the mutex is reacquired before calling the first cancellation cleanup 163handler. 164.Pp 165A thread that has been unblocked because it has been canceled while blocked in 166a call to any of these functions does not consume any condition signal that may 167be directed concurrently at the condition variable if there are other threads 168blocked on the condition variable. 169.Pp 170The 171.Fn pthread_cond_wait 172function will block forever until it is signaled. 173With the other functions, it is possible to bound the amount of time that the 174calling thread will block waiting to be signaled. 175When a timeout occurs, the calling threads will return with the mutex held, but 176will instead indicate an error occurred. 177.Pp 178In general, the system provides the ability to program timeouts against 179either the realtime clock, 180.Dv CLOCK_REALTIME , 181which measures the wall clock and is subject to changes due to time 182synchronization daemons such as NTP and PTP, or the high-resolution clock, 183.Dv CLOCK_HIGHRES , 184which is a non-adjustable high-resolution clock that is provided by 185system hardware. 186The specified timeout may either be specified as an absolute time in the 187future or as a relative amount of time that should elapse. 188Each clock has its own resolution, which can be determined by 189.Xr clock_getres 3C . 190Timeouts may be rounded up to a given clock's resolution. 191.Pp 192The 193.Fn pthread_cond_timedwait 194and 195.Fn pthrad_cond_reltimedwait_np 196functions determine which clock they use to wait based upon the clock that the 197condition variable was created with. 198By default, all timed condition variables utilize the realtime clock, 199.Dv CLOCK_REALTIME . 200The default clock may be changed on a per-condition variable basis by setting 201the condition variable's attributes with the 202.Xr pthread_condattr_setclock 3C 203function when creating the condition variable. 204.Pp 205The 206.Fn pthread_cond_clockwait 207and 208.Fn pthread_cond_relclockwait_np 209functions ignore the condition variable's defined clock and instead utilize the 210clock specified by the 211.Fa clock 212argument. 213While there are additional clocks in the system, only 214.Dv CLOCK_REALTIME 215or 216.Dv CLOCK_HIGHRES 217may be specified. 218The thread and process-specific CPU time clocks cannot be used. 219.Pp 220The 221.Fn pthread_cond_clockwait 222and 223.Fn pthread_cond_timedwait 224functions treat the timeout value, 225.Fa abstime , 226as the absolute time in the future when the timeout should expire. 227Conversely, the 228.Fn pthread_cond_relclockwait_np 229and 230.Fn pthread_cond_reltimedwait_np 231functions operate in terms of a relative time. 232The timer will expire when a specified amount of time passes on the 233clock as indicated by 234.Fa reltime . 235.Pp 236The 237.Fn pthread_cond_wait , 238.Fn pthread_cond_clockwait , 239.Fn pthread_cond_timedwait , 240.Fn pthread_cond_relclockwait_np , 241or 242.Fn pthread_cond_reltimedwait_np 243functions split the errors that they return into those that occur before and 244those that occur after dropping the lock in any form. 245In particular, error checking is guaranteed to occur before releasing the mutex 246and waiting on the condition variable. 247The errors 248.Er ETIMEDOUT , 249.Er EOWNERDEAD , 250and 251.Er ENOTRECOVERABLE 252are the only errors that may occur after a wait has begun. 253The latter two errors only apply to a robust mutex. 254No matter why the calling functions return, they will always return with the 255mutex 256.Fa mutex 257held, excepting certain unrecoverable robust mutexes. 258In addition, if the calling thread that is waiting on a condition variable 259takes a signal, the thread will never return 260.Er EINTR . 261It may resume blocking or potentially deliver a spurious wakeup. 262.Sh RETURN VALUES 263Upon successful completion, the 264.Fn pthread_cond_wait , 265.Fn pthread_cond_clockwait , 266.Fn pthread_cond_timedwait , 267.Fn pthread_cond_relclockwait_np , 268and 269.Fn pthread_cond_reltimedwait_np 270functions return 0. 271Otherwise, an error value is returned to indicate the error. 272.Sh ERRORS 273The 274.Fn pthread_cond_wait , 275.Fn pthread_cond_clockwait , 276.Fn pthread_cond_timedwait , 277.Fn pthread_cond_relclockwait_np , 278and 279.Fn pthread_cond_reltimedwait_np 280functions will fail if: 281.Bl -tag -width Er 282.It Er EPERM 283The mutex type is 284.Dv PTHREAD_MUTEX_ERRORCHECK 285or the mutex is a robust mutex, and the current thread does not own the mutex. 286.It Er ETIMEDOUT 287The absolute or relative time specified by 288.Fa abstime 289and 290.Fa reltime 291respectively, has passed. 292This does not apply to 293.Fn pthread_cond_wait . 294.It Er EINVAL 295One or more of the values specified by 296.Fa cond , 297.Fa mutex , 298.Fa abstime , 299or 300.Fa reltime 301is invalid. 302.Pp 303Different mutexes were supplied for concurrent operation on the same condition 304variable. 305.Pp 306The value of 307.Fa clock 308is either unsupported for timing operations or the value is unknown to the 309system. 310.It Er EOWNERDEAD 311The mutex is a robust mutex initialized with the attribute 312.Dv PTHREAD_MUTEX_ROBUST 313and the last owner of this mutex died while holding the mutex, leaving the 314state it was protecting possibly inconsistent. 315The mutex is now owned by the caller. 316.It Er ENOTRECOVERABLE 317The mutex is a robust mutex initialized with the attribute 318.Dv PTHREAD_MUTEX_ROBUST 319and the mutex was protecting state that has now been left irrecoverable. 320The mutex has not been acquired. 321.El 322.Sh INTERFACE STABILITY 323.Sy Committed 324.Sh MT-LEVEL 325.Sy MT-Safe 326.Sh SEE ALSO 327.Xr clock_getres 3C , 328.Xr pthread_cond_broadcast 3C , 329.Xr pthread_cond_signal 3C , 330.Xr pthread_condattr_setclock 3C , 331.Xr pthread_mutex_lock 3C , 332.Xr pthread_mutexattr_getrobust 3C , 333.Xr time.h 3HEAD , 334.Xr attributes 7 , 335.Xr condition 7 , 336.Xr pthreads 7 , 337.Xr standards 7 338