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) 2008, Sun Microsystems, Inc. All Rights Reserved. 45.\" Copyright 2024 Oxide Computer Company 46.\" 47.Dd June 23, 2024 48.Dt SEM_TIMEDWAIT 3C 49.Os 50.Sh NAME 51.Nm sem_clockwait , 52.Nm sem_timedwait , 53.Nm sem_relclockwait_np , 54.Nm sem_reltimedwait_np 55.Nd lock a semaphore with timeout 56.Sh SYNOPSIS 57.In sempahore.h 58.In time.h 59.Ft int 60.Fo sem_clockwait 61.Fa "sem_t *restrict sem" 62.Fa "clockid_t clock" 63.Fa "const struct timespec *abstime" 64.Fc 65.Ft int 66.Fo sem_timedwait 67.Fa "sem_t *restrict sem" 68.Fa "const struct timespec *abstime" 69.Fc 70.Ft int 71.Fo sem_relclockwait_np 72.Fa "sem_t *restrict sem" 73.Fa "clockid_t clock" 74.Fa "const struct timespec *reltime" 75.Fc 76.Ft int 77.Fo sem_reltimedwait_np 78.Fa "sem_t *restrict sem" 79.Fa "const struct timespec *reltime" 80.Fc 81.Sh DESCRIPTION 82The 83.Fn sem_clockwait , 84.Fn sem_timedwait , 85.Fn sem_relclockwait_np , 86and 87.Fn sem_reltimewait_np 88functions lock the sempahore referenced by 89.Fa sem 90as in the 91.Xr sem_wait 3C 92function. 93If the semaphore is locked, the calling thread will block until it 94becomes available by another process or thread unlocking the semaphore 95by calling 96.Xr sem_post 3C . 97However, if the semaphore does not become available within a specified 98timeout, then the function call will terminate without acquiring the 99semaphore and return the 100.Er ETIMEDOUT 101error. 102These functions all differ in terms of how the timeout is specified and 103the clock that is used to determine when the timeout has elapsed. 104.Pp 105In general, the system provides the ability to program timeouts against 106either the realtime clock, 107.Dv CLOCK_REALTIME , 108which measures the wall clock and is subject to changes due to time 109synchronization daemons such as NTP and PTP, or the high-resolution clock, 110.Dv CLOCK_HIGHRES , 111which is a non-adjustable high-resolution clock that is provided by 112system hardware. 113The specified timeout may either be specified as an absolute time in the 114future or as a relative amount of time that should elapse. 115Each clock has its own resolution, which can be determined by 116.Xr clock_getres 3C . 117Timeouts may be rounded up to a given clock's resolution. 118Due to scheduling effects, it is possible that more time may elapse than 119was specified in the timeout when the caller does not successfully 120acquire the lock. 121.Pp 122The 123.Fn sem_clockwait 124and 125.Fn sem_relclocklock_np 126functions allow the clock source to be used to be specified by the 127.Fa clock 128argument. 129While there are additional clocks in the system, only 130.Dv CLOCK_REALTIME 131or 132.Dv CLOCK_HIGHRES 133may be specified. 134The thread and process-specific CPU time clocks cannot be used. 135Conversely, the 136.Fn sem_timedwait 137and 138.Fn sem_reltimedwait_np 139functions will always utilize the realtime clock, 140.Dv CLOCK_REALTIME . 141.Pp 142The 143.Fn sem_clockwait 144and 145.Fn sem_timedwait 146functions treat the timeout value, 147.Fa abstime , 148as the absolute time in the future when the timeout should expire. 149Conversely, the 150and 151.Fn sem_reltimedwait_np 152functions operate in terms of a relative time. 153The timer will expire when a specified amount of time passes on the 154clock specified as indicated by 155.Fa reltime . 156.Pp 157If the semaphore, 158.Fa sem , 159can be immediately locked, then the timeout value is ignored 160entirely, even if the timeout had already expired or represented a 161value that didn't make sense. 162Both are only checked if the thread would block on the semaphore itself. 163.Sh RETURN VALUES 164Upon successful completion, the 165.Fn sem_clockwait , 166.Fn sem_timedwait , 167.Fn sem_relclockwait_np , 168and 169.Fn sem_reltimewait_np 170functions return 171.Sy 0 172and the thread will have successfully locked the semaphore. 173Otherwise 174.Sy -1 175is returned and 176.Va errno 177is set to indicate the error. 178.Sh ERRORS 179The 180.Fn sem_clockwait , 181.Fn sem_timedwait , 182.Fn sem_relclockwait_np , 183and 184.Fn sem_reltimewait_np 185functions will fail if: 186.Bl -tag -width Er 187.It Er EINVAL 188The 189.Fa sem 190argument does not refer to a valid semaphore or the process or thread 191would have blocked, and the timeout parameter specified a nanoseconds 192field value less than zero or greater than or equal to 1,000 million. 193.Pp 194For 195.Fn sem_clockwait 196or 197.Fn sem_relclockwait_np 198the value of 199.Fa clock 200is either unsupported for locking or unknown to the system. 201.It Er EDEADLK 202A deadlock condition was detected. 203.It Er EINTR 204A signal interrupted this function. 205.It Er ETIMEDOUT 206The semaphore could not be locked before the specified timeout expired. 207.El 208.Sh INTERFACE STABILITY 209.Sy Committed 210.Sh MT-LEVEL 211.Sy MT-Safe 212.Sh SEE ALSO 213.Xr semctl 2 , 214.Xr semget 2 , 215.Xr semop 2 , 216.Xr time 2 , 217.Xr clock_getres 3C , 218.Xr sem_post 3C , 219.Xr sem_trywait 3C , 220.Xr sem_wait 3C , 221.Xr attributes 7 , 222.Xr standards 7 223