1.\" Copyright (c) 2008, David Xu <davidxu@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" Portions of this text are reprinted and reproduced in electronic form 26.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- 27.\" Portable Operating System Interface (POSIX), The Open Group Base 28.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of 29.\" Electrical and Electronics Engineers, Inc and The Open Group. In the 30.\" event of any discrepancy between this version and the original IEEE and 31.\" The Open Group Standard, the original IEEE and The Open Group Standard is 32.\" the referee document. The original Standard can be obtained online at 33.\" http://www.opengroup.org/unix/online.html. 34.\" 35.Dd May 24, 2017 36.Dt SEM_TIMEDWAIT 3 37.Os 38.Sh NAME 39.Nm sem_timedwait , 40.Nm sem_clockwait_np 41.Nd "lock a semaphore" 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In semaphore.h 46.In time.h 47.Ft int 48.Fn sem_timedwait "sem_t * restrict sem" "const struct timespec * restrict abs_timeout" 49.Ft int 50.Fn sem_clockwait_np "sem_t * restrict sem" "clockid_t clock_id" "int flags" "const struct timespec * rqtp" "struct timespec * rmtp" 51.Sh DESCRIPTION 52The 53.Fn sem_timedwait 54function locks the semaphore referenced by 55.Fa sem , 56as in the 57.Xr sem_wait 3 58function. 59However, if the semaphore cannot be locked without waiting for 60another process or thread to unlock the semaphore by performing 61a 62.Xr sem_post 3 63function, this wait will be terminated when the specified timeout expires. 64.Pp 65The timeout will expire when the absolute time specified by 66.Fa abs_timeout 67passes, as measured by the clock on which timeouts are based (that is, 68when the value of that clock equals or exceeds 69.Fa abs_timeout ) , 70or if the 71absolute time specified by 72.Fa abs_timeout 73has already been passed at the time of the call. 74.Pp 75Note that the timeout is based on the 76.Dv CLOCK_REALTIME 77clock. 78.Pp 79The validity of the 80.Fa abs_timeout 81is not checked if the semaphore can be locked immediately. 82.Pp 83The 84.Fn sem_clockwait_np 85function is a more flexible variant of 86.Fn sem_timedwait . 87The 88.Fa clock_id 89parameter specifies the reference clock. 90If the 91.Fa flags 92parameter contains 93.Dv TIMER_ABSTIME , 94then the requested timeout 95.Pq Fa rqtp 96is an absolute timeout; otherwise, 97the timeout is relative. 98If this function fails with 99.Er EINTR 100and the timeout is relative, 101a non-NULL 102.Fa rmtp 103will be updated to contain the amount of time remaining in the interval 104.Po 105the requested time minus the time actually slept 106.Pc . 107An absolute timeout has no effect on 108.Fa rmtp . 109A single structure can be used for both 110.Fa rqtp 111and 112.Fa rmtp . 113.Sh RETURN VALUES 114These 115functions return zero if the calling process successfully performed the 116semaphore lock operation on the semaphore designated by 117.Fa sem . 118If the call was unsuccessful, the state of the semaphore is unchanged, 119and the function returns a value of \-1 and sets the global variable 120.Va errno 121to indicate the error. 122.Sh ERRORS 123These functions will fail if: 124.Bl -tag -width Er 125.It Bq Er EINVAL 126The 127.Fa sem 128argument does not refer to a valid semaphore, or the process or thread would 129have blocked, and the 130.Fa abs_timeout 131parameter specified a nanoseconds field value less than zero or greater than 132or equal to 1000 million. 133.It Bq Er ETIMEDOUT 134The semaphore could not be locked before the specified timeout expired. 135.It Bq Er EINTR 136A signal interrupted this function. 137.El 138.Sh SEE ALSO 139.Xr sem_post 3 , 140.Xr sem_trywait 3 , 141.Xr sem_wait 3 142.Sh STANDARDS 143The 144.Fn sem_timedwait 145function conforms to 146.St -p1003.1-2004 . 147The 148.Fn sem_clockwait_np 149function is not specified by any standard; 150it exists only on 151.Fx 152at the time of this writing. 153.Sh HISTORY 154The 155.Fn sem_timedwait 156function first appeared in 157.Fx 5.0 . 158The 159.Fn sem_clockwait_np 160function first appeared in 161.Fx 11.1 . 162