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.Dd April 21, 2022 29.Dt SIGTIMEDWAIT 2 30.Os 31.Sh NAME 32.Nm sigtimedwait , sigwaitinfo 33.Nd "wait for queued signals (REALTIME)" 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In signal.h 38.Ft int 39.Fo sigtimedwait 40.Fa "const sigset_t *restrict set" "siginfo_t *restrict info" 41.Fa "const struct timespec *restrict timeout" 42.Fc 43.Ft int 44.Fn sigwaitinfo "const sigset_t * restrict set" "siginfo_t * restrict info" 45.Sh DESCRIPTION 46The 47.Fn sigtimedwait 48system call is equivalent to 49.Fn sigwaitinfo 50except that if none of the signals specified by 51.Fa set 52are pending, 53.Fn sigtimedwait 54waits for the time interval specified in the 55.Vt timespec 56structure referenced by 57.Fa timeout . 58If the 59.Vt timespec 60structure pointed to by 61.Fa timeout 62is zero-valued and if none of the signals specified by 63.Fa set 64are pending, then 65.Fn sigtimedwait 66returns immediately with an error. 67If 68.Fa timeout 69is the 70.Dv NULL 71pointer, 72.Fn sigtimedwait 73blocks indefinitely. 74.Dv CLOCK_MONOTONIC 75clock is used to measure the time interval specified by the 76.Fa timeout 77argument. 78.Pp 79The 80.Fn sigwaitinfo 81system call selects the pending signal from the set specified by 82.Fa set . 83Should any of multiple pending signals in the range 84.Dv SIGRTMIN 85to 86.Dv SIGRTMAX 87be selected, it shall be the lowest numbered one. 88The 89selection order between realtime and non-realtime signals, or 90between multiple pending non-realtime signals, is unspecified. 91If no signal in 92.Fa set 93is pending at the time of the call, the calling thread 94is suspended until one or more signals in 95.Fa set 96become pending or until it is interrupted by an unblocked, caught signal. 97.Pp 98The 99.Fn sigwaitinfo 100system call is equivalent to the 101.Fn sigwait 102system call if the 103.Fa info 104argument is 105.Dv NULL . 106If the 107.Fa info 108argument is 109.Pf non- Dv NULL , 110the 111.Fn sigwaitinfo 112function is equivalent to 113.Fn sigwait , 114except that the selected signal number shall be stored in the 115.Va si_signo 116member, and the cause of the signal shall be stored in the 117.Va si_code 118member. 119Besides this, the 120.Fn sigwaitinfo 121and 122.Fn sigtimedwait 123system calls may return 124.Er EINTR 125if interrupted by signal, which is not allowed for the 126.Fn sigwait 127function. 128.Pp 129If any value is queued to the selected signal, the first such queued 130value is dequeued and, if the info argument is 131.Pf non- Dv NULL , 132the value is stored in the 133.Va si_value 134member of 135.Fa info . 136The system resource used to queue the signal 137is released and returned to the system for other use. 138If no value is queued, 139the content of the 140.Va si_value 141member is zero-valued. 142If no further signals are 143queued for the selected signal, the pending indication for that signal 144is reset. 145.Sh RETURN VALUES 146Upon successful completion (that is, one of the signals specified by 147.Fa set 148is pending or is generated) 149.Fn sigwaitinfo 150and 151.Fn sigtimedwait 152return the selected signal number. 153Otherwise, the functions return a value of \-1 154and set the global variable 155.Va errno 156to indicate the error. 157.Sh ERRORS 158The 159.Fn sigtimedwait 160system call 161will fail if: 162.Bl -tag -width Er 163.It Bq Er EAGAIN 164No signal specified by set was generated within the specified timeout period. 165.El 166.Pp 167The 168.Fn sigtimedwait 169and 170.Fn sigwaitinfo 171system calls fail if: 172.Bl -tag -width Er 173.It Bq Er EINTR 174The wait was interrupted by an unblocked, caught signal. 175.El 176.Pp 177The 178.Fn sigtimedwait 179system call may also fail if: 180.Bl -tag -width Er 181.It Bq Er EINVAL 182The 183.Fa timeout 184argument specified a 185.Va tv_nsec 186value less than zero or greater than or equal 187to 1000 million. 188Kernel only checks for this error if no signal is pending in set and it 189is necessary to wait. 190.El 191.Sh SEE ALSO 192.Xr sigaction 2 , 193.Xr sigpending 2 , 194.Xr sigqueue 2 , 195.Xr sigsuspend 2 , 196.Xr sigwait 2 , 197.Xr pause 3 , 198.Xr pthread_sigmask 3 , 199.Xr siginfo 3 200.Sh STANDARDS 201The 202.Fn sigtimedwait 203and 204.Fn sigwaitinfo 205system calls conform to 206.St -p1003.1-96 . 207POSIX 208leaves the behavior of 209.Fn sigtimedwait 210with a 211.Dv NULL 212.Fa timeout 213pointer unspecified. 214