man2/sigwaitinfo.2

   1 .\" Copyright (c) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH SIGWAITINFO 2 2022-09-09 "Linux man-pages (unreleased)"
   6 .SH NAME
   7 sigwaitinfo, sigtimedwait, rt_sigtimedwait \- synchronously wait
   8 for queued signals
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <signal.h>
  15 .PP
  16 .BI "int sigwaitinfo(const sigset_t *restrict " set ,
  17 .BI "                siginfo_t *restrict " info );
  18 .BI "int sigtimedwait(const sigset_t *restrict " set ,
  19 .BI "                siginfo_t *restrict " info ,
  20 .BI "                const struct timespec *restrict " timeout );
  21 .fi
  22 .PP
  23 .RS -4
  24 Feature Test Macro Requirements for glibc (see
  25 .BR feature_test_macros (7)):
  26 .RE
  27 .PP
  28 .BR sigwaitinfo (),
  29 .BR sigtimedwait ():
  30 .nf
  31     _POSIX_C_SOURCE >= 199309L
  32 .fi
  33 .SH DESCRIPTION
  34 .BR sigwaitinfo ()
  35 suspends execution of the calling thread until one of the signals in
  36 .I set
  37 is pending
  38 (If one of the signals in
  39 .I set
  40 is already pending for the calling thread,
  41 .BR sigwaitinfo ()
  42 will return immediately.)
  43 .PP
  44 .BR sigwaitinfo ()
  45 removes the signal from the set of pending
  46 signals and returns the signal number as its function result.
  47 If the
  48 .I info
  49 argument is not NULL,
  50 then the buffer that it points to is used to return a structure of type
  51 .I siginfo_t
  52 (see
  53 .BR sigaction (2))
  54 containing information about the signal.
  55 .PP
  56 If multiple signals in
  57 .I set
  58 are pending for the caller, the signal that is retrieved by
  59 .BR sigwaitinfo ()
  60 is determined according to the usual ordering rules; see
  61 .BR signal (7)
  62 for further details.
  63 .PP
  64 .BR sigtimedwait ()
  65 operates in exactly the same way as
  66 .BR sigwaitinfo ()
  67 except that it has an additional argument,
  68 .IR timeout ,
  69 which specifies the interval for which
  70 the thread is suspended waiting for a signal.
  71 (This interval will be rounded up to the system clock granularity,
  72 and kernel scheduling delays mean that the interval
  73 may overrun by a small amount.)
  74 This argument is a
  75 .BR timespec (3)
  76 structure.
  77 .PP
  78 If both fields of this structure are specified as 0, a poll is performed:
  79 .BR sigtimedwait ()
  80 returns immediately, either with information about a signal that
  81 was pending for the caller, or with an error
  82 if none of the signals in
  83 .I set
  84 was pending.
  85 .SH RETURN VALUE
  86 On success, both
  87 .BR sigwaitinfo ()
  88 and
  89 .BR sigtimedwait ()
  90 return a signal number (i.e., a value greater than zero).
  91 On failure both calls return \-1, with
  92 .I errno
  93 set to indicate the error.
  94 .SH ERRORS
  95 .TP
  96 .B EAGAIN
  97 No signal in
  98 .I set
  99 became pending within the
 100 .I timeout
 101 period specified to
 102 .BR sigtimedwait ().
 103 .TP
 104 .B EINTR
 105 The wait was interrupted by a signal handler; see
 106 .BR signal (7).
 107 (This handler was for a signal other than one of those in
 108 .IR set .)
 109 .TP
 110 .B EINVAL
 111 .I timeout
 112 was invalid.
 113 .SH STANDARDS
 114 POSIX.1-2001, POSIX.1-2008.
 115 .SH NOTES
 116 In normal usage, the calling program blocks the signals in
 117 .I set
 118 via a prior call to
 119 .BR sigprocmask (2)
 120 (so that the default disposition for these signals does not occur if they
 121 become pending between successive calls to
 122 .BR sigwaitinfo ()
 123 or
 124 .BR sigtimedwait ())
 125 and does not establish handlers for these signals.
 126 In a multithreaded program,
 127 the signal should be blocked in all threads, in order to prevent
 128 the signal being treated according to its default disposition in
 129 a thread other than the one calling
 130 .BR sigwaitinfo ()
 131 or
 132 .BR sigtimedwait ()).
 133 .PP
 134 The set of signals that is pending for a given thread is the
 135 union of the set of signals that is pending specifically for that thread
 136 and the set of signals that is pending for the process as a whole (see
 137 .BR signal (7)).
 138 .PP
 139 Attempts to wait for
 140 .B SIGKILL
 141 and
 142 .B SIGSTOP
 143 are silently ignored.
 144 .PP
 145 If multiple threads of a process are blocked
 146 waiting for the same signal(s) in
 147 .BR sigwaitinfo ()
 148 or
 149 .BR sigtimedwait (),
 150 then exactly one of the threads will actually receive the
 151 signal if it becomes pending for the process as a whole;
 152 which of the threads receives the signal is indeterminate.
 153 .PP
 154 .BR sigwaitinfo ()
 155 or
 156 .BR sigtimedwait (),
 157 can't be used to receive signals that
 158 are synchronously generated, such as the
 159 .B SIGSEGV
 160 signal that results from accessing an invalid memory address
 161 or the
 162 .B SIGFPE
 163 signal that results from an arithmetic error.
 164 Such signals can be caught only via signal handler.
 165 .PP
 166 POSIX leaves the meaning of a NULL value for the
 167 .I timeout
 168 argument of
 169 .BR sigtimedwait ()
 170 unspecified, permitting the possibility that this has the same meaning
 171 as a call to
 172 .BR sigwaitinfo (),
 173 and indeed this is what is done on Linux.
 174 .\"
 175 .SS C library/kernel differences
 176 On Linux,
 177 .BR sigwaitinfo ()
 178 is a library function implemented on top of
 179 .BR sigtimedwait ().
 180 .PP
 181 The glibc wrapper functions for
 182 .BR sigwaitinfo ()
 183 and
 184 .BR sigtimedwait ()
 185 silently ignore attempts to wait for the two real-time signals that
 186 are used internally by the NPTL threading implementation.
 187 See
 188 .BR nptl (7)
 189 for details.
 190 .PP
 191 The original Linux system call was named
 192 .BR sigtimedwait ().
 193 However, with the addition of real-time signals in Linux 2.2,
 194 the fixed-size, 32-bit
 195 .I sigset_t
 196 type supported by that system call was no longer fit for purpose.
 197 Consequently, a new system call,
 198 .BR rt_sigtimedwait (),
 199 was added to support an enlarged
 200 .I sigset_t
 201 type.
 202 The new system call takes a fourth argument,
 203 .IR "size_t sigsetsize" ,
 204 which specifies the size in bytes of the signal set in
 205 .IR set .
 206 This argument is currently required to have the value
 207 .I sizeof(sigset_t)
 208 (or the error
 209 .B EINVAL
 210 results).
 211 The glibc
 212 .BR sigtimedwait ()
 213 wrapper function hides these details from us, transparently calling
 214 .BR rt_sigtimedwait ()
 215 when the kernel provides it.
 216 .\"
 217 .SH SEE ALSO
 218 .BR kill (2),
 219 .BR sigaction (2),
 220 .BR signal (2),
 221 .BR signalfd (2),
 222 .BR sigpending (2),
 223 .BR sigprocmask (2),
 224 .BR sigqueue (3),
 225 .BR sigsetops (3),
 226 .BR sigwait (3),
 227 .BR timespec (3),
 228 .BR signal (7),
 229 .BR time (7)