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 *set, siginfo_t *info);
13
14       int sigtimedwait(const sigset_t *set, siginfo_t *info,
15                        const struct timespec *timeout);
16
17   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
18
19       sigwaitinfo(), sigtimedwait(): _POSIX_C_SOURCE >= 199309L
20

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

CONFORMING TO

68       POSIX.1-2001, POSIX.1-2008.
69

NOTES

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

SEE ALSO

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

COLOPHON

129       This  page  is  part of release 4.15 of the Linux man-pages project.  A
130       description of the project, information about reporting bugs,  and  the
131       latest     version     of     this    page,    can    be    found    at
132       https://www.kernel.org/doc/man-pages/.
133
134
135
136Linux                             2017-09-15                    SIGWAITINFO(2)
Impressum