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