1.\" $NetBSD: sigtimedwait.2,v 1.8 2012/04/02 22:06:47 agc Exp $ 2.\" 3.\" Copyright (c) 2003 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jaromir Dolecek. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 2, 2012 31.Dt SIGTIMEDWAIT 2 32.Os 33.Sh NAME 34.Nm sigtimedwait , 35.Nm sigwaitinfo , 36.Nm sigwait 37.Nd wait for queued signals 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In signal.h 42.Ft int 43.Fn sigtimedwait "const sigset_t * restrict set" "siginfo_t * restrict info" "const struct timespec * restrict timeout" 44.Ft int 45.Fn sigwaitinfo "const sigset_t * restrict set" "siginfo_t * restrict info" 46.Ft int 47.Fn sigwait "const sigset_t * restrict set" "int * restrict sig" 48.Sh DESCRIPTION 49.Fn sigwaitinfo 50and 51.Fn sigwait 52return the first pending signal from the set specified by 53.Fa set . 54Should multiple signals from 55.Fa set 56be pending, the lowest numbered one is returned. 57The selection order between realtime and non-realtime signals is unspecified. 58If there is no signal from 59.Ar set 60pending at the time of the call, the calling thread 61is suspended until one of the specified signals is generated. 62.Pp 63.Fn sigtimedwait 64is exactly equal to 65.Fn sigwaitinfo , 66except 67.Fa timeout 68specifies the maximum time interval for which the calling thread will 69be suspended. 70If 71.Fa timeout 72is zero (tv_sec == tv_nsec == 0), 73.Fn sigtimedwait 74only checks the currently pending signals and returns immediately. 75If 76.Dv NULL 77is used for 78.Fa timeout , 79.Fn sigtimedwait 80behaves exactly like 81.Fn sigwaitinfo 82in all regards. 83.Pp 84If several threads are waiting for a given signal, exactly one of them 85returns from the signal wait when the signal is generated. 86.Pp 87Behaviour of these functions is unspecified if any of the signals in 88.Fa set 89are unblocked at the time these functions are called. 90.Sh RETURN VALUES 91Upon successful completion of 92.Fn sigtimedwait 93or 94.Fn sigwaitinfo 95.Fa info 96is updated with signal information, and the function returns the signal number. 97Otherwise, \-1 is returned and the global variable 98.Va errno 99indicates the error. 100Upon successful completion of 101.Fn sigwait 102.Fa sig 103is updated with the signal number, and the function returns 0. 104Otherwise, a non-zero error code is returned. 105.Sh ERRORS 106.Fn sigwaitinfo 107and 108.Fn sigwait 109always succeed. 110.Pp 111.Fn sigtimedwait 112will fail and the 113.Fa info 114pointer will remain unchanged if: 115.Bl -tag -width Er 116.It Bq Er EAGAIN 117No signal specified in 118.Fa set 119was generated in the specified 120.Fa timeout . 121.El 122.Pp 123.Fn sigtimedwait 124may also fail if: 125.Bl -tag -width Er 126.It Bq Er EINVAL 127The specified 128.Fa timeout 129was invalid. 130.El 131.Pp 132This error is only checked if no signal from 133.Fa set 134is pending and it would be necessary to wait. 135.Sh SEE ALSO 136.Xr sigaction 2 , 137.Xr sigprocmask 2 , 138.Xr signal 7 139.Sh STANDARDS 140The functions 141.Fn sigtimedwait , 142.Fn sigwaitinfo , 143and 144.Fn sigwait 145conform to 146.St -p1003.1-2001 . 147.Sh HISTORY 148The 149.Fn sigtimedwait , 150.Fn sigwaitinfo , 151and 152.Fn sigwait 153functions appeared in 154.Nx 2.0 . 155