original/man2/sigwaitinfo.2

   1 .\" Copyright (c) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH SIGWAITINFO 2 2013-09-04 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 sigwaitinfo, sigtimedwait \- synchronously wait for queued signals
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <signal.h>
  31 .sp
  32 .BI "int sigwaitinfo(const sigset_t *" set ", siginfo_t *" info ");"
  33 .sp
  34 .BI "int sigtimedwait(const sigset_t *" set ", siginfo_t *" info ", "
  35 .BI "                 const struct timespec *" timeout ");"
  36 .fi
  37 .sp
  38 .in -4n
  39 Feature Test Macro Requirements for glibc (see
  40 .BR feature_test_macros (7)):
  41 .in
  42 .sp
  43 .BR sigwaitinfo (),
  44 .BR sigtimedwait ():
  45 _POSIX_C_SOURCE\ >=\ 199309L
  46 .SH DESCRIPTION
  47 .BR sigwaitinfo ()
  48 suspends execution of the calling thread until one of the signals in
  49 .I set
  50 is pending
  51 (If one of the signals in
  52 .I set
  53 is already pending for the calling thread,
  54 .BR sigwaitinfo ()
  55 will return immediately.)
  56
  57 .BR sigwaitinfo ()
  58 removes the signal from the set of pending
  59 signals and returns the signal number as its function result.
  60 If the
  61 .I info
  62 argument is not NULL,
  63 then the buffer that it points to is used to return a structure of type
  64 .I siginfo_t
  65 (see
  66 .BR sigaction (2))
  67 containing information about the signal.
  68 .PP
  69 If multiple signals in
  70 .I set
  71 are pending for the caller, the signal that is retrieved by
  72 .BR sigwaitinfo ()
  73 is determined according to the usual ordering rules; see
  74 .BR signal (7)
  75 for further details.
  76 .PP
  77 .BR sigtimedwait ()
  78 operates in exactly the same way as
  79 .BR sigwaitinfo ()
  80 except that it has an additional argument,
  81 .IR timeout ,
  82 which specifies the interval for which
  83 the thread is suspended waiting for a signal.
  84 (This interval will be rounded up to the system clock granularity,
  85 and kernel scheduling delays mean that the interval
  86 may overrun by a small amount.)
  87 This argument is of the following type:
  88 .sp
  89 .in +4n
  90 .nf
  91 struct timespec {
  92     long    tv_sec;         /* seconds */
  93     long    tv_nsec;        /* nanoseconds */
  94 }
  95 .fi
  96 .in
  97 .sp
  98 If both fields of this structure are specified as 0, a poll is performed:
  99 .BR sigtimedwait ()
 100 returns immediately, either with information about a signal that
 101 was pending for the caller, or with an error
 102 if none of the signals in
 103 .I set
 104 was pending.
 105 .SH RETURN VALUE
 106 On success, both
 107 .BR sigwaitinfo ()
 108 and
 109 .BR sigtimedwait ()
 110 return a signal number (i.e., a value greater than zero).
 111 On failure both calls return \-1, with
 112 .I errno
 113 set to indicate the error.
 114 .SH ERRORS
 115 .TP
 116 .B EAGAIN
 117 No signal in
 118 .I set
 119 was became pending within the
 120 .I timeout
 121 period specified to
 122 .BR sigtimedwait ().
 123 .TP
 124 .B EINTR
 125 The wait was interrupted by a signal handler; see
 126 .BR signal (7).
 127 (This handler was for a signal other than one of those in
 128 .IR set .)
 129 .TP
 130 .B EINVAL
 131 .I timeout
 132 was invalid.
 133 .SH CONFORMING TO
 134 POSIX.1-2001.
 135 .SH NOTES
 136 In normal usage, the calling program blocks the signals in
 137 .I set
 138 via a prior call to
 139 .BR sigprocmask (2)
 140 (so that the default disposition for these signals does not occur if they
 141 become pending between successive calls to
 142 .BR sigwaitinfo ()
 143 or
 144 .BR sigtimedwait ())
 145 and does not establish handlers for these signals.
 146 In a multithreaded program,
 147 the signal should be blocked in all threads, in order to prevent
 148 the signal being treated according to its default disposition in
 149 a thread other than the one calling
 150 .BR sigwaitinfo ()
 151 or
 152 .BR sigtimedwait ()).
 153
 154 The set of signals that is pending for a given thread is the
 155 union of the set of signals that is pending specifically for that thread
 156 and the set of signals that is pending for the process as a whole (see
 157 .BR signal (7)).
 158
 159 Attempts to wait for
 160 .B SIGKILL
 161 and
 162 .B SIGSTOP
 163 are silently ignored.
 164
 165 If multiple threads of a process are blocked
 166 waiting for the same signal(s) in
 167 .BR sigwaitinfo ()
 168 or
 169 .BR sigtimedwait (),
 170 then exactly one of the threads will actually receive the
 171 signal if it becomes pending for the process as a whole;
 172 which of the threads receives the signal is indeterminate.
 173
 174 POSIX leaves the meaning of a NULL value for the
 175 .I timeout
 176 argument of
 177 .BR sigtimedwait ()
 178 unspecified, permitting the possibility that this has the same meaning
 179 as a call to
 180 .BR sigwaitinfo (),
 181 and indeed this is what is done on Linux.
 182
 183 On Linux,
 184 .BR sigwaitinfo ()
 185 is a library function implemented on top of
 186 .BR sigtimedwait ().
 187 .SH SEE ALSO
 188 .BR kill (2),
 189 .BR sigaction (2),
 190 .BR signal (2),
 191 .BR signalfd (2),
 192 .BR sigpending (2),
 193 .BR sigprocmask (2),
 194 .BR sigqueue (3),
 195 .BR sigsetops (3),
 196 .BR sigwait (3),
 197 .BR signal (7),
 198 .BR time (7)
 199 .SH COLOPHON
 200 This page is part of release 3.67 of the Linux
 201 .I man-pages
 202 project.
 203 A description of the project,
 204 information about reporting bugs,
 205 and the latest version of this page,
 206 can be found at
 207 \%http://www.kernel.org/doc/man\-pages/.