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.\" $FreeBSD$ 36.\" 37.Dd May 24, 2017 38.Dt SEM_TIMEDWAIT 3 39.Os 40.Sh NAME 41.Nm sem_timedwait , 42.Nm sem_clockwait_np 43.Nd "lock a semaphore" 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.In semaphore.h 48.In time.h 49.Ft int 50.Fn sem_timedwait "sem_t * restrict sem" "const struct timespec * restrict abs_timeout" 51.Ft int 52.Fn sem_clockwait_np "sem_t * restrict sem" "clockid_t clock_id" "int flags" "const struct timespec * rqtp" "struct timespec * rmtp" 53.Sh DESCRIPTION 54The 55.Fn sem_timedwait 56function locks the semaphore referenced by 57.Fa sem , 58as in the 59.Xr sem_wait 3 60function. 61However, if the semaphore cannot be locked without waiting for 62another process or thread to unlock the semaphore by performing 63a 64.Xr sem_post 3 65function, this wait will be terminated when the specified timeout expires. 66.Pp 67The timeout will expire when the absolute time specified by 68.Fa abs_timeout 69passes, as measured by the clock on which timeouts are based (that is, 70when the value of that clock equals or exceeds 71.Fa abs_timeout ) , 72or if the 73absolute time specified by 74.Fa abs_timeout 75has already been passed at the time of the call. 76.Pp 77Note that the timeout is based on the 78.Dv CLOCK_REALTIME 79clock. 80.Pp 81The validity of the 82.Fa abs_timeout 83is not checked if the semaphore can be locked immediately. 84.Pp 85The 86.Fn sem_clockwait_np 87function is a more flexible variant of 88.Fn sem_timedwait . 89The 90.Fa clock_id 91parameter specifies the reference clock. 92If the 93.Fa flags 94parameter contains 95.Dv TIMER_ABSTIME , 96then the requested timeout 97.Pq Fa rqtp 98is an absolute timeout; otherwise, 99the timeout is relative. 100If this function fails with 101.Er EINTR 102and the timeout is relative, 103a non-NULL 104.Fa rmtp 105will be updated to contain the amount of time remaining in the interval 106.Po 107the requested time minus the time actually slept 108.Pc . 109An absolute timeout has no effect on 110.Fa rmtp . 111A single structure can be used for both 112.Fa rqtp 113and 114.Fa rmtp . 115.Sh RETURN VALUES 116These 117functions return zero if the calling process successfully performed the 118semaphore lock operation on the semaphore designated by 119.Fa sem . 120If the call was unsuccessful, the state of the semaphore is unchanged, 121and the function returns a value of \-1 and sets the global variable 122.Va errno 123to indicate the error. 124.Sh ERRORS 125These functions will fail if: 126.Bl -tag -width Er 127.It Bq Er EINVAL 128The 129.Fa sem 130argument does not refer to a valid semaphore, or the process or thread would 131have blocked, and the 132.Fa abs_timeout 133parameter specified a nanoseconds field value less than zero or greater than 134or equal to 1000 million. 135.It Bq Er ETIMEDOUT 136The semaphore could not be locked before the specified timeout expired. 137.It Bq Er EINTR 138A signal interrupted this function. 139.El 140.Sh SEE ALSO 141.Xr sem_post 3 , 142.Xr sem_trywait 3 , 143.Xr sem_wait 3 144.Sh STANDARDS 145The 146.Fn sem_timedwait 147function conforms to 148.St -p1003.1-2004 . 149The 150.Fn sem_clockwait_np 151function is not specified by any standard; 152it exists only on 153.Fx 154at the time of this writing. 155.Sh HISTORY 156The 157.Fn sem_timedwait 158function first appeared in 159.Fx 5.0 . 160The 161.Fn sem_clockwait_np 162function first appeared in 163.Fx 11.1 . 164