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
41 .Nd wait for processes to change status
48 .Fn wait "int *status"
50 .Fn waitpid "pid_t wpid" "int *status" "int options"
53 .Fn waitid "idtype_t idtype" "id_t id" "siginfo_t *info" "int options"
57 .Fn wait3 "int *status" "int options" "struct rusage *rusage"
59 .Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage"
61 .Fn wait6 "idtype_t idtype" "id_t id" "int *status" "int options" "struct __wrusage *wrusage" "siginfo_t *infop"
65 function suspends execution of its calling process until
67 information is available for a terminated child process,
68 or a signal is received.
69 On return from a successful
74 area contains termination information about the process that exited
92 system call provides a more general interface for programs
93 that need to wait for certain child processes,
94 that need resource utilization statistics accumulated by child processes,
95 or that require options.
97 The broadest interface of all functions in this family is
99 which is otherwise very much like
101 but with a few very important distinctions.
102 To wait for exited processes, the option flag
104 need to be explicitly specified.
105 This allows for waiting for processes which have experienced other
106 status changes without having to handle also the exit status from
107 the terminated processes.
108 Instead of the traditional
110 argument, a pointer to a new structure
113 struct rusage wru_self;
114 struct rusage wru_children;
118 This allows the calling process to collect resource usage statistics
119 from both its own child process as well as from its grand children.
120 When no resource usage statistics are needed this pointer can be
129 When specified, the structure is filled the same as for
131 signal, delivered at the process state change.
133 The process, which state is queried, is specified by two arguments
141 arguments allows to support many other types of
142 IDs as well in addition to PID and PGID.
143 .Bl -bullet -offset indent
152 wait for the child process with a process ID equal to
162 wait for the child process with a process group ID equal to
172 wait for any child process and the
188 wait for any child process in the same process group as the caller.
191 Non-standard specifiers for the process to wait for, supported by this
197 .Bl -bullet -offset indent
203 waits for processes which effective UID is equal to
210 waits for processes which effective GID is equal to
217 waits for processes which session ID is equal to
219 In case the child process started its own new session,
220 SID will be the same as its own PID.
221 Otherwise the SID of a child process will match the caller's SID.
227 waits for processes within a jail which jail identifier is equal
237 functions, the single
239 argument specifies the set of child processes for which to wait.
240 .Bl -bullet -offset indent
244 is -1, the call waits for any child process.
249 the call waits for any child process in the process group of the caller.
253 is greater than zero, the call waits for the process with process id
258 is less than -1, the call waits for any process whose process group id
259 equals the absolute value of
265 argument is defined below.
269 argument contains the bitwise OR of any of the following options.
272 indicates that children of the current process that
273 have continued from a job control stop, by receiving a
275 signal, should also have their status reported.
277 is used to indicate that the call should not block when
278 there are no processes wishing to report status.
280 indicates that children of the current process which are stopped
282 .Dv SIGTTIN , SIGTTOU , SIGTSTP ,
285 signal shall have their status reported.
290 allows waiting for processes which have trapped or reached a breakpoint.
292 indicates that the caller is wants to receive status reports from
293 terminated processes.
294 This flag is implicitly set for the functions
305 functions, the flag has to be explicitly included in the
307 if status reports from terminated processes are expected.
309 keeps the process whose status is returned in a waitable state.
310 The process may be waited for again after this call completes.
317 functions, at least one of the options
325 Otherwise there will be no events for the call to report.
326 To avoid hanging indefinitely in such a case these functions
334 is non-NULL, a summary of the resources used by the terminated
335 process and all its children is returned.
339 argument is non-NULL, a resource usage statistics
340 from both its own child process as well as from its grand children
345 is non-NULL, it must point to a
347 structure which is filled on return such that the
353 if be non-zero, if there is a status change to report.
354 If there are no status changes to report and WNOHANG is applied,
355 both of these fields are returned zero.
360 option set, checking these fields is the only way to know whether
361 there were any status changes to report, because the return value
364 is be zero as it is for any successful return from
369 option is specified and no processes
370 wish to report status,
378 function is identical to
405 The following macros may be used to test the manner of exit of the process.
406 One of the first four macros will evaluate to a non-zero (true) value:
408 .It Fn WIFCONTINUED status
409 True if the process has not terminated, and
410 has continued after a job control stop.
411 This macro can be true only if the wait call specified the
414 .It Fn WIFEXITED status
415 True if the process terminated normally by a call to
419 .It Fn WIFSIGNALED status
420 True if the process terminated due to receipt of a signal.
421 .It Fn WIFSTOPPED status
422 True if the process has not terminated, but has stopped and can be restarted.
423 This macro can be true only if the wait call specified the
426 or if the child process is being traced (see
430 Depending on the values of those macros, the following macros
431 produce the remaining status information about the child process:
433 .It Fn WEXITSTATUS status
436 is true, evaluates to the low-order 8 bits
437 of the argument passed to
442 .It Fn WTERMSIG status
444 .Fn WIFSIGNALED status
445 is true, evaluates to the number of the signal
446 that caused the termination of the process.
447 .It Fn WCOREDUMP status
449 .Fn WIFSIGNALED status
450 is true, evaluates as true if the termination
451 of the process was accompanied by the creation of a core file
452 containing an image of the process when the signal was received.
453 .It Fn WSTOPSIG status
455 .Fn WIFSTOPPED status
456 is true, evaluates to the number of the signal
457 that caused the process to stop.
462 for a list of termination signals.
463 A status of 0 indicates normal termination.
465 If a parent process terminates without
466 waiting for all of its child processes to terminate,
467 the remaining child processes are assigned the parent
468 process 1 ID (the init process ID).
470 If a signal is caught while any of the
473 the call may be interrupted or restarted when the signal-catching routine
475 depending on the options in effect for the signal;
481 The implementation queues one
483 signal for each child process whose
484 status has changed, if
486 returns because the status of a child process is available, the pending
487 SIGCHLD signal associated with the process ID of the child process will
491 signals remain pending.
497 returns because the status of a child process is available, the pending
499 signal will be cleared unless another status of the child process
504 returns due to a stopped, continued,
505 or terminated child process, the process ID of the child
506 is returned to the calling process.
507 Otherwise, a value of \-1
510 is set to indicate the error.
518 returns due to a stopped, continued,
519 or terminated child process, the process ID of the child
520 is returned to the calling process.
521 If there are no children not previously awaited,
528 is specified and there are
529 no stopped, continued or exited children,
531 If an error is detected or a caught signal aborts the call,
535 is set to indicate the error.
539 returns because one or more processes have a state change to report,
541 To indicate an error, -1 will be returned and
543 set to an appropriate value.
546 was used, 0 can be returned indicating no error, but no processes
547 may have changed state either, if si_signo and/or si_pid are zero.
552 will fail and return immediately if:
555 The calling process has no existing unwaited-for
558 No status from the terminated child process is available
559 because the calling process has asked the system to discard
560 such status by ignoring the signal
570 argument points to an illegal address.
571 (May not be detected before exit of a child process.)
573 The call was interrupted by a caught signal,
574 or the signal did not have the
578 An invalid value was specified for
584 do not specify a valid set of processes.
598 functions are defined by POSIX;
603 are not specified by POSIX.
607 and the ability to restart a pending
609 call are extensions to the POSIX interface.