Commit | Line | Data |
---|---|---|
55c2faba WJ |
1 | .\" Copyright (c) 1980, 1991 Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)wait.2 6.5 (Berkeley) 3/10/91 | |
33 | .\" | |
34 | .Dd March 10, 1991 | |
35 | .Dt WAIT 2 | |
36 | .Os BSD 4 | |
37 | .Sh NAME | |
38 | .Nm wait , | |
39 | .Nm waitpid , | |
40 | .Nm wait4 , | |
41 | .Nm wait3 | |
42 | .Nd wait for process terminatation | |
43 | .Sh SYNOPSIS | |
44 | .Fd #include <sys/types.h> | |
45 | .Fd #include <sys/wait.h> | |
46 | .Ft pid_t | |
47 | .Fn wait "int *status" | |
48 | .Fd #include <sys/time.h> | |
49 | .Fd #include <sys/resource.h> | |
50 | .Ft pid_t | |
51 | .Fn waitpid "pid_t wpid" "int *status" "int options" | |
52 | .Ft pid_t | |
53 | .Fn wait3 "int *status" "int options" "struct rusage *rusage" | |
54 | .Ft pid_t | |
55 | .Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage" | |
56 | .Sh DESCRIPTION | |
57 | The | |
58 | .Fn wait | |
59 | function suspends execution of its calling process until | |
60 | .Fa status | |
61 | information is available for a terminated child process, | |
62 | or a signal is received. | |
63 | On return from a successful | |
64 | .Fn wait | |
65 | call, | |
66 | the | |
67 | .Fa status | |
68 | area contains termination information about the process that exited | |
69 | as defined below. | |
70 | .Pp | |
71 | The | |
72 | .Fn wait4 | |
73 | call provides a more general interface for programs | |
74 | that need to wait for certain child processes, | |
75 | that need resource utilization statistics accummulated by child processes, | |
76 | or that require options. | |
77 | The other wait functions are implemented using | |
78 | .Fn wait4 . | |
79 | .Pp | |
80 | The | |
81 | .Fa wpid | |
82 | parameter specifies the set of child processes for which to wait. | |
83 | If | |
84 | .Fa wpid | |
85 | is -1, the call waits for any child process. | |
86 | If | |
87 | .Fa wpid | |
88 | is 0, | |
89 | the call waits for any child process in the process group of the caller. | |
90 | If | |
91 | .Fa wpid | |
92 | is greater than zero, the call waits for the process with process id | |
93 | .Fa wpid . | |
94 | If | |
95 | .Fa wpid | |
96 | is less than -1, the call waits for any process whose process group id | |
97 | equals the absolute value of | |
98 | .Fa wpid . | |
99 | .Pp | |
100 | The | |
101 | .Fa status | |
102 | parameter is defined below. The | |
103 | .Fa options | |
104 | parameter contains the bitwise OR of any of the following options. | |
105 | The | |
106 | .Dv WNOHANG | |
107 | option | |
108 | is used to indicate that the call should not block if | |
109 | there are no processes that wish to report status. | |
110 | If the | |
111 | .Dv WUNTRACED | |
112 | option is set, | |
113 | children of the current process that are stopped | |
114 | due to a | |
115 | .Dv SIGTTIN , SIGTTOU , SIGTSTP , | |
116 | or | |
117 | .Dv SIGSTOP | |
118 | signal also have | |
119 | their status reported. | |
120 | .Pp | |
121 | If | |
122 | .Fa rusage | |
123 | is non-zero, a summary of the resources used by the terminated | |
124 | process and all its | |
125 | children is returned (this information is currently not available | |
126 | for stopped processes). | |
127 | .Pp | |
128 | When the | |
129 | .Dv WNOHANG | |
130 | option is specified and no processes | |
131 | wish to report status, | |
132 | .Fn wait4 | |
133 | returns a | |
134 | process id | |
135 | of 0. | |
136 | .Pp | |
137 | The | |
138 | .Fn waitpid | |
139 | call is identical to | |
140 | .Fn wait4 | |
141 | with an | |
142 | .Fa rusage | |
143 | value of zero. | |
144 | The older | |
145 | .Fn wait3 | |
146 | call is the same as | |
147 | .Fn wait4 | |
148 | with a | |
149 | .Fa wpid | |
150 | value of -1. | |
151 | .Pp | |
152 | The following macros may be used to test the manner of exit of the process. | |
153 | One of the first three macros will evaluate to a non-zero (true) value: | |
154 | .Bl -tag -width Ds | |
155 | .It Fn WIFEXITED status | |
156 | True if the process terminated normally by a call to | |
157 | .Xr _exit 2 | |
158 | or | |
159 | .Xr exit 2 . | |
160 | .It Fn WIFSIGNALED status | |
161 | True if the process terminated due to receipt of a signal. | |
162 | .It Fn WIFSTOPPED status | |
163 | True if the process has not terminated, but has stopped and can be restarted. | |
164 | This macro can be true only if the wait call specified the | |
165 | .Dv WUNTRACED | |
166 | option | |
167 | or if the child process is being traced (see | |
168 | .Xr ptrace 2 ) . | |
169 | .El | |
170 | .Pp | |
171 | Depending on the values of those macros, the following macros | |
172 | produce the remaining status information about the child process: | |
173 | .Bl -tag -width Ds | |
174 | .It Fn WEXITSTATUS status | |
175 | If | |
176 | .Fn WIFEXITED status | |
177 | is true, evaluates to the low-order 8 bits | |
178 | of the argument passed to | |
179 | .Xr _exit 2 | |
180 | or | |
181 | .Xr exit 2 | |
182 | by the child. | |
183 | .It Fn WTERMSIG status | |
184 | If | |
185 | .Fn WIFSIGNALED status | |
186 | is true, evaluates to the number of the signal | |
187 | that caused the termination of the process. | |
188 | .It Fn WCOREDUMP status | |
189 | If | |
190 | .Fn WIFSIGNALED status | |
191 | is true, evaluates as true if the termination | |
192 | of the process was accompanied by the creation of a core file | |
193 | containing an image of the process when the signal was received. | |
194 | .It Fn WSTOPSIG status | |
195 | If | |
196 | .Fn WIFSTOPPED status | |
197 | is true, evaluates to the number of the signal | |
198 | that caused the process to stop. | |
199 | .El | |
200 | .Sh NOTES | |
201 | See | |
202 | .Xr sigaction 2 | |
203 | for a list of termination signals. | |
204 | A status of 0 indicates normal termination. | |
205 | .Pp | |
206 | If a parent process terminates without | |
207 | waiting for all of its child processes to terminate, | |
208 | the remaining child processes are assigned the parent | |
209 | process 1 ID (the init process ID). | |
210 | .Pp | |
211 | If a signal is caught while any of the | |
212 | .Fn wait | |
213 | calls is pending, | |
214 | the call may be interrupted or restarted when the signal-catching routine | |
215 | returns, | |
216 | depending on the options in effect for the signal; | |
217 | see | |
218 | .Xr intro 2 , | |
219 | System call restart. | |
220 | .Sh RETURN VALUES | |
221 | If | |
222 | .Fn wait | |
223 | returns due to a stopped | |
224 | or terminated child process, the process ID of the child | |
225 | is returned to the calling process. Otherwise, a value of -1 | |
226 | is returned and | |
227 | .Va errno | |
228 | is set to indicate the error. | |
229 | .Pp | |
230 | If | |
231 | .Fn wait4 , | |
232 | .Fn wait3 | |
233 | or | |
234 | .Fn waitpid | |
235 | returns due to a stopped | |
236 | or terminated child process, the process ID of the child | |
237 | is returned to the calling process. | |
238 | If there are no children not previously awaited, | |
239 | -1 is returned with | |
240 | .Va errno | |
241 | set to | |
242 | .Bq Er ECHILD . | |
243 | Otherwise, if | |
244 | .Dv WNOHANG | |
245 | is specified and there are | |
246 | no stopped or exited children, | |
247 | 0 is returned. | |
248 | If an error is detected or a caught signal aborts the call, | |
249 | a value of -1 | |
250 | is returned and | |
251 | .Va errno | |
252 | is set to indicate the error. | |
253 | .Sh ERRORS | |
254 | .Fn Wait | |
255 | will fail and return immediately if: | |
256 | .Bl -tag -width Er | |
257 | .It Bq Er ECHILD | |
258 | The calling process has no existing unwaited-for | |
259 | child processes. | |
260 | .It Bq Er EFAULT | |
261 | The | |
262 | .Fa status | |
263 | or | |
264 | .Fa rusage | |
265 | arguments point to an illegal address. | |
266 | (May not be detected before exit of a child process.) | |
267 | .It Bq Er EINTR | |
268 | The call was interrupted by a caught signal, | |
269 | or the signal did not have the | |
270 | .Dv SA_RESTART | |
271 | flag set. | |
272 | .El | |
273 | .Sh STANDARDS | |
274 | The | |
275 | .Fn wait | |
276 | and | |
277 | .Fn waitpid | |
278 | functions are defined by POSIX; | |
279 | .Fn wait4 | |
280 | and | |
281 | .Fn wait3 | |
282 | are not specified by POSIX. | |
283 | The | |
284 | .Fn WCOREDUMP | |
285 | macro | |
286 | and the ability to restart a pending | |
287 | .Fn wait | |
288 | call are extensions to the POSIX interface. | |
289 | .Sh SEE ALSO | |
290 | .Xr exit 2 , | |
291 | .Xr sigaction 2 | |
292 | .Sh HISTORY | |
293 | A | |
294 | .Nm | |
295 | function call appeared in Version 6 AT&T UNIX. |