1SIGWAITINFO(2)             Linux Programmer's Manual            SIGWAITINFO(2)
2
3
4

NAME

6       sigwaitinfo,  sigtimedwait,  rt_sigtimedwait  -  synchronously wait for
7       queued signals
8

SYNOPSIS

10       #include <signal.h>
11
12       int sigwaitinfo(const sigset_t *restrict set,
13                       siginfo_t *restrict info);
14       int sigtimedwait(const sigset_t *restrict set,
15                       siginfo_t *restrict info,
16                       const struct timespec *restrict timeout);
17
18   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
19
20       sigwaitinfo(), sigtimedwait():
21           _POSIX_C_SOURCE >= 199309L
22

DESCRIPTION

24       sigwaitinfo() suspends execution of the calling thread until one of the
25       signals  in  set  is  pending  (If one of the signals in set is already
26       pending for the calling thread, sigwaitinfo() will return immediately.)
27
28       sigwaitinfo() removes the signal from the set of  pending  signals  and
29       returns the signal number as its function result.  If the info argument
30       is not NULL, then the buffer that it points to  is  used  to  return  a
31       structure  of  type siginfo_t (see sigaction(2)) containing information
32       about the signal.
33
34       If multiple signals in set are pending for the caller, the signal  that
35       is  retrieved by sigwaitinfo() is determined according to the usual or‐
36       dering rules; see signal(7) for further details.
37
38       sigtimedwait() operates in exactly the same way as sigwaitinfo() except
39       that it has an additional argument, timeout, which specifies the inter‐
40       val for which the thread is suspended waiting for a signal.  (This  in‐
41       terval  will  be rounded up to the system clock granularity, and kernel
42       scheduling delays mean  that  the  interval  may  overrun  by  a  small
43       amount.)  This argument is of the following type:
44
45           struct timespec {
46               long    tv_sec;         /* seconds */
47               long    tv_nsec;        /* nanoseconds */
48           }
49
50       If  both  fields  of  this structure are specified as 0, a poll is per‐
51       formed: sigtimedwait() returns  immediately,  either  with  information
52       about  a  signal  that  was pending for the caller, or with an error if
53       none of the signals in set was pending.
54

RETURN VALUE

56       On success, both sigwaitinfo() and sigtimedwait() return a signal  num‐
57       ber  (i.e.,  a  value greater than zero).  On failure both calls return
58       -1, with errno set to indicate the error.
59

ERRORS

61       EAGAIN No signal in set became pending within the timeout period speci‐
62              fied to sigtimedwait().
63
64       EINTR  The  wait  was  interrupted  by a signal handler; see signal(7).
65              (This handler was for a signal other than one of those in set.)
66
67       EINVAL timeout was invalid.
68

CONFORMING TO

70       POSIX.1-2001, POSIX.1-2008.
71

NOTES

73       In normal usage, the calling program blocks the signals in  set  via  a
74       prior call to sigprocmask(2) (so that the default disposition for these
75       signals does not occur if they become pending between successive  calls
76       to sigwaitinfo() or sigtimedwait()) and does not establish handlers for
77       these signals.  In  a  multithreaded  program,  the  signal  should  be
78       blocked  in  all  threads, in order to prevent the signal being treated
79       according to its default disposition in a thread  other  than  the  one
80       calling sigwaitinfo() or sigtimedwait()).
81
82       The  set  of signals that is pending for a given thread is the union of
83       the set of signals that is pending specifically for that thread and the
84       set  of  signals  that  is pending for the process as a whole (see sig‐
85       nal(7)).
86
87       Attempts to wait for SIGKILL and SIGSTOP are silently ignored.
88
89       If multiple threads of a process are blocked waiting for the same  sig‐
90       nal(s)  in  sigwaitinfo()  or  sigtimedwait(),  then exactly one of the
91       threads will actually receive the signal if it becomes pending for  the
92       process  as  a whole; which of the threads receives the signal is inde‐
93       terminate.
94
95       sigwaitinfo() or sigtimedwait(), can't be used to receive signals  that
96       are  synchronously  generated,  such as the SIGSEGV signal that results
97       from accessing an invalid memory address or the SIGFPE signal that  re‐
98       sults  from  an  arithmetic error.  Such signals can be caught only via
99       signal handler.
100
101       POSIX leaves the meaning of a NULL value for the  timeout  argument  of
102       sigtimedwait()  unspecified,  permitting  the possibility that this has
103       the same meaning as a call to sigwaitinfo(), and indeed this is what is
104       done on Linux.
105
106   C library/kernel differences
107       On  Linux,  sigwaitinfo()  is  a library function implemented on top of
108       sigtimedwait().
109
110       The  glibc  wrapper  functions  for  sigwaitinfo()  and  sigtimedwait()
111       silently ignore attempts to wait for the two real-time signals that are
112       used internally by the NPTL threading implementation.  See nptl(7)  for
113       details.
114
115       The original Linux system call was named sigtimedwait().  However, with
116       the addition of real-time signals in Linux 2.2, the fixed-size,  32-bit
117       sigset_t  type supported by that system call was no longer fit for pur‐
118       pose.  Consequently, a new system call, rt_sigtimedwait(), was added to
119       support  an enlarged sigset_t type.  The new system call takes a fourth
120       argument, size_t sigsetsize, which specifies the size in bytes  of  the
121       signal  set  in  set.   This argument is currently required to have the
122       value sizeof(sigset_t) (or the error EINVAL results).  The  glibc  sig‐
123       timedwait() wrapper function hides these details from us, transparently
124       calling rt_sigtimedwait() when the kernel provides it.
125

SEE ALSO

127       kill(2), sigaction(2), signal(2), signalfd(2), sigpending(2),  sigproc‐
128       mask(2), sigqueue(3), sigsetops(3), sigwait(3), signal(7), time(7)
129

COLOPHON

131       This  page  is  part of release 5.12 of the Linux man-pages project.  A
132       description of the project, information about reporting bugs,  and  the
133       latest     version     of     this    page,    can    be    found    at
134       https://www.kernel.org/doc/man-pages/.
135
136
137
138Linux                             2021-03-22                    SIGWAITINFO(2)
Impressum