]>
Commit | Line | Data |
---|---|---|
6a31cfdd | 1 | .\" Copyright (c) 2002 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
2 | .\" |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
11 | .\" | |
12 | .\" Since the Linux kernel and libraries are constantly changing, this | |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. | |
16 | .\" | |
17 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
18 | .\" the source, must acknowledge the copyright and authors of this work. | |
19 | .\" | |
cc4615cc | 20 | .TH SIGWAITINFO 2 2007-07-26 "Linux" "Linux Programmer's Manual" |
fea681da MK |
21 | .SH NAME |
22 | sigwaitinfo, sigtimedwait \- synchronously wait for queued signals | |
23 | .SH SYNOPSIS | |
d1331c6f | 24 | .nf |
fea681da MK |
25 | .B #include <signal.h> |
26 | .sp | |
27 | .BI "int sigwaitinfo(const sigset_t *" set ", siginfo_t *" info ");" | |
28 | .sp | |
29 | .BI "int sigtimedwait(const sigset_t *" set ", siginfo_t *" info ", " | |
d1331c6f MK |
30 | .BI " const struct timespec *" timeout ");" |
31 | .fi | |
cc4615cc MK |
32 | .sp |
33 | .in -4n | |
34 | Feature Test Macro Requirements for glibc (see | |
35 | .BR feature_test_macros (7)): | |
36 | .in | |
37 | .sp | |
38 | .BR sigwaitinfo (), | |
39 | .BR sigtimedwait (): | |
40 | _POSIX_C_SOURCE\ >=\ 199309L | |
fea681da MK |
41 | .SH DESCRIPTION |
42 | .BR sigwaitinfo () | |
43 | suspends execution of the calling process until one of the signals in | |
44 | .I set | |
45 | is delivered. | |
46 | (If one of the signals in | |
47 | .I set | |
48 | is already pending for the calling process, | |
49 | .BR sigwaitinfo () | |
50 | will return immediately with information about that signal.) | |
51 | ||
52 | .BR sigwaitinfo () | |
53 | removes the delivered signal from the calling process's list of pending | |
54 | signals and returns the signal number as its function result. | |
55 | If the | |
56 | .I info | |
8478ee02 | 57 | argument is not NULL, |
fea681da MK |
58 | then it returns a structure of type |
59 | .I siginfo_t | |
60 | (see | |
61 | .BR sigaction (2)) | |
62 | containing information about the signal. | |
63 | .PP | |
64 | Signals returned via | |
65 | .BR sigwaitinfo () | |
66 | are delivered in the usual order; see | |
67 | .BR signal (7) | |
68 | for further details. | |
69 | .PP | |
70 | .BR sigtimedwait () | |
71 | operates in exactly the same way as | |
72 | .BR sigwaitinfo () | |
73 | except that it has an additional argument, | |
74 | .IR timeout , | |
75 | which enables an upper bound to be placed on the time for which | |
76 | the process is suspended. | |
77 | This argument is of the following type: | |
78 | .sp | |
088a639b | 79 | .in +4n |
fea681da MK |
80 | .nf |
81 | struct timespec { | |
82 | long tv_sec; /* seconds */ | |
83 | long tv_nsec; /* nanoseconds */ | |
84 | } | |
85 | .fi | |
088a639b | 86 | .in |
fea681da MK |
87 | .sp |
88 | If both fields of this structure are specified as 0, a poll is performed: | |
89 | .BR sigtimedwait () | |
90 | returns immediately, either with information about a signal that | |
91 | was pending for the caller, or with an error | |
92 | if none of the signals in | |
93 | .I set | |
94 | was pending. | |
95 | .SH "RETURN VALUE" | |
96 | On success, both | |
97 | .BR sigwaitinfo () | |
98 | and | |
99 | .BR sigtimedwait () | |
100 | return a signal number (i.e., a value greater than zero). | |
101 | On failure both calls return \-1, with | |
102 | .I errno | |
103 | set to indicate the error. | |
104 | .SH ERRORS | |
105 | .TP | |
106 | .B EAGAIN | |
107 | No signal in | |
108 | .I set | |
109 | was delivered within the | |
110 | .I timeout | |
111 | period specified to | |
112 | .BR sigtimedwait (). | |
113 | .TP | |
114 | .B EINTR | |
115 | The wait was interrupted by a signal handler. | |
116 | (This handler was for a signal other than one of those in | |
117 | .IR set .) | |
118 | .TP | |
119 | .B EINVAL | |
120 | .I timeout | |
121 | was invalid. | |
2dd578fd MK |
122 | .SH "CONFORMING TO" |
123 | POSIX.1-2001 | |
fea681da | 124 | .SH NOTES |
d1331c6f | 125 | In normal usage, the calling program blocks the signals in |
fea681da MK |
126 | .I set |
127 | via a prior call to | |
0bfa087b | 128 | .BR sigprocmask (2) |
fea681da MK |
129 | (so that the default disposition for these signals does not occur if they |
130 | are delivered between successive calls to | |
c13182ef | 131 | .BR sigwaitinfo () |
f87925c6 | 132 | or |
4d52e8f8 | 133 | .BR sigtimedwait ()) |
fea681da | 134 | and does not establish handlers for these signals. |
c13182ef MK |
135 | In a multithreaded program, |
136 | the signal should be blocked in all threads to prevent | |
d1331c6f | 137 | the signal being delivered to a thread other than the one calling |
c13182ef | 138 | .BR sigwaitinfo () |
d1331c6f MK |
139 | or |
140 | .BR sigtimedwait ()). | |
fea681da | 141 | .PP |
8478ee02 | 142 | POSIX leaves the meaning of a NULL value for the |
fea681da MK |
143 | .I timeout |
144 | argument of | |
145 | .BR sigtimedwait () | |
146 | unspecified, permitting the possibility that this has the same meaning | |
147 | as a call to | |
148 | .BR sigwaitinfo (), | |
149 | and indeed this is what is done on Linux. | |
7fdd2ee1 MK |
150 | |
151 | On Linux, | |
152 | .BR sigwaitinfo () | |
153 | is a library function implemented on top of | |
154 | .BR sigtimedwait (). | |
fea681da MK |
155 | .SH "SEE ALSO" |
156 | .BR kill (2), | |
157 | .BR sigaction (2), | |
158 | .BR signal (2), | |
058c1165 | 159 | .BR signalfd (2), |
fea681da MK |
160 | .BR sigpending (2), |
161 | .BR sigprocmask (2), | |
162 | .BR sigqueue (2), | |
163 | .BR sigsetops (3), | |
164 | .BR signal (7) |