1.\" Copyright (c) 2005 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(s), this list of conditions and the following disclaimer as 9.\" the first lines of this file unmodified other than the possible 10.\" addition of one or more copyright notices. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice(s), this list of conditions and the following disclaimer in 13.\" the documentation and/or other materials provided with the 14.\" distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE 20.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 23.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 25.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 26.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.\" $FreeBSD: head/lib/libc/sys/sigwaitinfo.2 276006 2014-12-21 12:36:36Z brueffer $ 29.\" 30.Dd July 20, 2016 31.Dt SIGTIMEDWAIT 2 32.Os 33.Sh NAME 34.Nm sigtimedwait , sigwaitinfo 35.Nd "wait for queued signals (REALTIME)" 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In signal.h 40.Ft int 41.Fo sigtimedwait 42.Fa "const sigset_t * restrict set" "siginfo_t * restrict info" 43.Fa "const struct timespec * restrict timeout" 44.Fc 45.Ft int 46.Fn sigwaitinfo "const sigset_t * restrict set" "siginfo_t * restrict info" 47.Sh DESCRIPTION 48The 49.Fn sigtimedwait 50system call is equivalent to 51.Fn sigwaitinfo 52except that if none of the signals specified by 53.Fa set 54are pending, 55.Fn sigtimedwait 56waits for the time interval specified in the 57.Vt timespec 58structure referenced by 59.Fa timeout . 60If the 61.Vt timespec 62structure pointed to by 63.Fa timeout 64is zero-valued and if none of the signals specified by 65.Fa set 66are pending, then 67.Fn sigtimedwait 68returns immediately with an error. 69If 70.Fa timeout 71is the 72.Dv NULL 73pointer, the behavior is unspecified. 74.\"The 75.\".Dv CLOCK_MONOTONIC 76.\"clock is used to measure the time interval specified by the 77.\".Fa timeout 78.\"argument. 79.Pp 80The 81.Fn sigwaitinfo 82system call selects the pending signal from the set specified by 83.Fa set . 84.\"Should any of multiple pending signals in the range 85.\".Dv SIGRTMIN 86.\"to 87.\".Dv SIGRTMAX 88.\"be selected, it shall be the lowest numbered one. 89.\"The 90.\"selection order between realtime and non-realtime signals, or 91.\"between multiple pending non-realtime signals, is unspecified. 92If no signal in 93.Fa set 94is pending at the time of the call, the calling thread 95is suspended until one or more signals in 96.Fa set 97become pending or until it is interrupted by an unblocked, caught signal. 98.Pp 99The 100.Fn sigwaitinfo 101system call is equivalent to the 102.Fn sigwait 103function call if the 104.Fa info 105argument is 106.Dv NULL . 107If the 108.Fa info 109argument is 110.Pf non- Dv NULL , 111the 112.Fn sigwaitinfo 113function is equivalent to 114.Fn sigwait , 115except that the selected signal number shall be stored in the 116.Fa si_signo 117member, and the cause of the signal shall be stored in the 118.Fa si_code 119member. 120Besides this, the 121.Fn sigwaitinfo 122and 123.Fn sigtimedwait 124system calls may return 125.Er EINTR 126if interrupted by signal, which is not allowed for the 127.Fn sigwait 128function. 129.Pp 130If any value is queued to the selected signal, the first such queued 131value is dequeued and, if the info argument is 132.Pf non- Dv NULL , 133the value is stored in the 134.Fa si_value 135member of 136.Fa info . 137The system resource used to queue the signal 138is released and returned to the system for other use. 139If no value is queued, 140the content of the 141.Fa si_value 142member is zero-valued. 143If no further signals are 144queued for the selected signal, the pending indication for that signal 145is reset. 146.Sh RETURN VALUES 147Upon successful completion (that is, one of the signals specified by 148.Fa set 149is pending or is generated) 150.Fn sigwaitinfo 151and 152.Fn sigtimedwait 153return the selected signal number. 154Otherwise, the functions return a value of \-1 155and set the global variable 156.Va errno 157to indicate the error. 158.Sh ERRORS 159The 160.Fn sigtimedwait 161system call 162will fail if: 163.Bl -tag -width Er 164.It Bq Er EAGAIN 165No signal specified by set was generated within the specified timeout period. 166.El 167.Pp 168The 169.Fn sigtimedwait 170and 171.Fn sigwaitinfo 172system calls fail if: 173.Bl -tag -width Er 174.It Bq Er EINTR 175The wait was interrupted by an unblocked, caught signal. 176.El 177.Pp 178The 179.Fn sigtimedwait 180system call may also fail if: 181.Bl -tag -width Er 182.It Bq Er EINVAL 183The 184.Fa timeout 185argument specified a 186.Fa tv_nsec 187value less than zero or greater than or equal 188to 1000 million. 189Kernel only checks for this error if no signal is pending in set and it 190is necessary to wait. 191.El 192.Sh SEE ALSO 193.Xr sigaction 2 , 194.Xr sigpending 2 , 195.\" .Xr sigqueue 2 , 196.Xr sigsuspend 2 , 197.Xr pause 3 , 198.Xr pthread_sigmask 3 , 199.\" .Xr siginfo 3 , 200.Xr sigwait 3 201.Sh STANDARDS 202The 203.Fn sigtimedwait 204and 205.Fn sigwaitinfo 206system calls conform to 207.St -p1003.1-96 . 208