1wait3(3C) Standard C Library Functions wait3(3C)
2
6 wait3, wait4 - wait for process to terminate or stop
7
9 #include <sys/wait.h>
10 #include <sys/time.h>
11 #include <sys/resource.h>
12 pid_t wait3(int *statusp, int options, struct rusage *rusage);
14 pid_t wait4(pid_t pid, int *statusp, int options, struct rusage *rusage);
17
20 The wait3() function delays its caller until a signal is received or
21 one of its child processes terminates or stops due to tracing. If any
22 child process has died or stopped due to tracing and this has not
23 already been reported, return is immediate, returning the process ID
24 and status of one of those children. If that child process has died, it
25 is discarded. If there are no children, −1 is returned immediately. If
26 there are only running or stopped but reported children, the calling
27 process is blocked.
28 If statusp is not a null pointer, then on return from a successful
31 wait3() call, the status of the child process is stored in the integer
32 pointed to by statusp. *statusp indicates the cause of termination and
33 other information about the terminated process in the following manner:
34 o If the low-order 8 bits of *statusp are equal to 0177, the
36 child process has stopped; the 8 bits higher up from the
37 low-order 8 bits of *statusp contain the number of the sig‐
38 nal that caused the process to stop. See signal.h(3HEAD).
39 o If the low-order 8 bits of *statusp are non-zero and are not
41 equal to 0177, the child process terminated due to a signal;
42 the low-order 7 bits of *statusp contain the number of the
43 signal that terminated the process. In addition, if the low-
44 order seventh bit of *statusp (that is, bit 0200) is set, a
45 ``core image'' of the process was produced; see sig‐
46 nal.h(3HEAD).
47 o Otherwise, the child process terminated due to an exit()
49 call; the 8 bits higher up from the low-order 8 bits of
50 *statusp contain the low-order 8 bits of the argument that
51 the child process passed to exit(); see exit(2).
52 The options argument is constructed from the bitwise inclusive OR of
55 zero or more of the following flags, defined in <sys/wait.h>:
56 WNOHANG Execution of the calling process is not suspended if sta‐
58 tus is not immediately available for any child process.
59 WUNTRACED The status of any child processes that are stopped, and
62 whose status has not yet been reported since they stopped,
63 are also reported to the requesting process.
64 If rusage is not a null pointer, a summary of the resources used by the
68 terminated process and all its children is returned. Only the user time
69 used and the system time used are currently available. They are
70 returned in the ru_utime and ru_stime, members of the rusage structure,
71 respectively.
72 When the WNOHANG option is specified and no processes have status to
75 report, wait3() returns 0. The WNOHANG and WUNTRACED options may be
76 combined by the bitwise OR operation of the two values.
77 The wait4() function is an extended interface. If pid is 0, wait4() is
80 equivalent to wait3(). If pid has a nonzero value, wait4() returns sta‐
81 tus only for the indicated process ID, but not for any other child pro‐
82 cesses. If pid has a negative value, wait4() return status only for
83 child processes whose process group ID is equal to the absolute value
84 of pid. The status can be evaluated using the macros defined by
85 wait.h(3HEAD).
86
88 If wait3() or wait4() returns due to a stopped or terminated child
89 process, the process ID of the child is returned to the calling
90 process. Otherwise, −1 is returned and errno is set to indicate the
91 error.
92 If wait3() or wait4() return due to the delivery of a signal to the
95 calling process, −1 is returned and errno is set to EINTR. If WNOHANG
96 was set in options, it has at least one child process specified by pid
97 for which status is not available, and status is not available for any
98 process specified by pid, 0 is returned. Otherwise, −1 is returned and
99 errno is set to indicate the error.
100 The wait3() and wait4() functions return 0 if WNOHANG is specified and
103 there are no stopped or exited children, and return the process ID of
104 the child process if they return due to a stopped or terminated child
105 process. Otherwise, they return −1 and set errno to indicate the error.
106
108 The wait3() and wait4() functions will fail and return immediately if:
109 ECHILD The calling process has no existing unwaited-for child pro‐
111 cesses.
112 EFAULT The statusp or rusage arguments point to an illegal address.
115 EINTR The function was interrupted by a signal. The value of the
118 location pointed to by statusp is undefined.
119 EINVAL The value of options is not valid.
122 The wait4() function may fail if:
126 ECHILD The process specified by pid does not exist or is not a child
128 of the calling process.
129 The wait3()and wait4() functions will terminate prematurely, return −1,
133 and set errno to EINTR upon the arrival of a signal whose SA_RESTART
134 bit in its flags field is not set (see sigaction(2)).
135
137 See attributes(5) for descriptions of the following attributes:
138 ┌─────────────────────────────┬─────────────────────────────┐
143 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
144 ├─────────────────────────────┼─────────────────────────────┤
145 │MT-Level │Async-Signal-Safe │
146 └─────────────────────────────┴─────────────────────────────┘
147
149 kill(1), exit(2), waitid(2), waitpid(3C), getrusage(3C), signal(3C),
150 signal.h(3HEAD), wait(3C), wait.h(3HEAD), proc(4), attributes(5)
151
153 If a parent process terminates without waiting on its children, the
154 initialization process (process ID = 1) inherits the children.
155 The wait3() and wait4() functions are automatically restarted when a
158 process receives a signal while awaiting termination of a child
159 process, unless the SA_RESTART bit is not set in the flags for that
160 signal.
161SunOS 5.11 4 Nov 2005 wait3(3C)