1 .\" Copyright (c) 1980, 1991, 1993, 1994
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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 .\" 4. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" @(#)wait.2 8.2 (Berkeley) 4/19/94
39 .Nd wait for process termination
46 .Fn wait "int *status"
48 .Fn waitpid "pid_t wpid" "int *status" "int options"
52 .Fn wait3 "int *status" "int options" "struct rusage *rusage"
54 .Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage"
58 function suspends execution of its calling process until
60 information is available for a terminated child process,
61 or a signal is received.
62 On return from a successful
67 area contains termination information about the process that exited
85 system call provides a more general interface for programs
86 that need to wait for certain child processes,
87 that need resource utilization statistics accumulated by child processes,
88 or that require options.
89 The other wait functions are implemented using
94 argument specifies the set of child processes for which to wait.
97 is -1, the call waits for any child process.
101 the call waits for any child process in the process group of the caller.
104 is greater than zero, the call waits for the process with process id
108 is less than -1, the call waits for any process whose process group id
109 equals the absolute value of
114 argument is defined below.
118 argument contains the bitwise OR of any of the following options.
121 option indicates that children of the current process that
122 have continued from a job control stop, by receiving a
124 signal, should also have their status reported.
128 is used to indicate that the call should not block if
129 there are no processes that wish to report status.
133 children of the current process that are stopped
135 .Dv SIGTTIN , SIGTTOU , SIGTSTP ,
138 signal also have their status reported.
141 option is an alias for
145 option keeps the process whose status is returned in a waitable state.
146 The process may be waited for again after this call completes.
150 is non-zero, a summary of the resources used by the terminated
152 children is returned (this information is currently not available
153 for stopped or continued processes).
157 option is specified and no processes
158 wish to report status,
166 function is identical to
179 The following macros may be used to test the manner of exit of the process.
180 One of the first three macros will evaluate to a non-zero (true) value:
182 .It Fn WIFCONTINUED status
183 True if the process has not terminated, and
184 has continued after a job control stop.
185 This macro can be true only if the wait call specified the
188 .It Fn WIFEXITED status
189 True if the process terminated normally by a call to
193 .It Fn WIFSIGNALED status
194 True if the process terminated due to receipt of a signal.
195 .It Fn WIFSTOPPED status
196 True if the process has not terminated, but has stopped and can be restarted.
197 This macro can be true only if the wait call specified the
200 or if the child process is being traced (see
204 Depending on the values of those macros, the following macros
205 produce the remaining status information about the child process:
207 .It Fn WEXITSTATUS status
210 is true, evaluates to the low-order 8 bits
211 of the argument passed to
216 .It Fn WTERMSIG status
218 .Fn WIFSIGNALED status
219 is true, evaluates to the number of the signal
220 that caused the termination of the process.
221 .It Fn WCOREDUMP status
223 .Fn WIFSIGNALED status
224 is true, evaluates as true if the termination
225 of the process was accompanied by the creation of a core file
226 containing an image of the process when the signal was received.
227 .It Fn WSTOPSIG status
229 .Fn WIFSTOPPED status
230 is true, evaluates to the number of the signal
231 that caused the process to stop.
236 for a list of termination signals.
237 A status of 0 indicates normal termination.
239 If a parent process terminates without
240 waiting for all of its child processes to terminate,
241 the remaining child processes are assigned the parent
242 process 1 ID (the init process ID).
244 If a signal is caught while any of the
247 the call may be interrupted or restarted when the signal-catching routine
249 depending on the options in effect for the signal;
255 The implementation queues one
257 signal for each child process whose
258 status has changed, if
260 returns because the status of a child process is available, the pending
261 SIGCHLD signal associated with the process ID of the child process will
265 signals remain pending.
271 returns because the status of a child process is available, the pending
273 signal will be cleared unless another status of the child process
278 returns due to a stopped, continued,
279 or terminated child process, the process ID of the child
280 is returned to the calling process.
281 Otherwise, a value of \-1
284 is set to indicate the error.
291 returns due to a stopped, continued,
292 or terminated child process, the process ID of the child
293 is returned to the calling process.
294 If there are no children not previously awaited,
301 is specified and there are
302 no stopped, continued or exited children,
304 If an error is detected or a caught signal aborts the call,
308 is set to indicate the error.
313 will fail and return immediately if:
316 The calling process has no existing unwaited-for
319 No status from the terminated child process is available
320 because the calling process has asked the system to discard
321 such status by ignoring the signal
331 argument points to an illegal address.
332 (May not be detected before exit of a child process.)
334 The call was interrupted by a caught signal,
335 or the signal did not have the
350 functions are defined by POSIX;
354 are not specified by POSIX.
358 and the ability to restart a pending
360 call are extensions to the POSIX interface.