1wait(3UCB) SunOS/BSD Compatibility Library Functions wait(3UCB)
2
6 wait, wait3, wait4, waitpid, WIFSTOPPED, WIFSIGNALED, WIFEXITED - wait
7 for process to terminate or stop
8
10 /usr/ucb/cc [ flag ... ] file ...
11 #include <sys/wait.h>
12 int wait(statusp)
14 int *statusp;
15 int waitpid(pid, statusp, options)
18 int pid;
19 int *statusp;
20 int options;
21 #include <sys/time.h>
24 #include <sys/resource.h>
25 int wait3(statusp, options, rusage)
27 int *statusp;
28 int options;
29 struct rusage *rusage;
30 int wait4(pid, statusp, options, rusage)
33 int pid;
34 int *statusp;
35 int options;
36 struct rusage *rusage;
37 WIFSTOPPED(status)
40 int status;
41 WIFSIGNALED(status)
44 int status;
45 WIFEXITED(status)
48 int status;
49
52 The wait() function delays its caller until a signal is received or one
53 of its child processes terminates or stops due to tracing. If any child
54 process has died or stopped due to tracing and this has not been
55 reported using wait(), return is immediate, returning the process ID
56 and exit status of one of those children. If that child process has
57 died, it is discarded. If there are no children, return is immediate
58 with the value −1 returned. If there are only running or stopped but
59 reported children, the calling process is blocked.
60 If status is not a NULL pointer, then on return from a successful
63 wait() call the status of the child process whose process ID is the
64 return value of wait() is stored in the wait() union pointed to by sta‐
65 tus. The w_status member of that union is an int; it indicates the
66 cause of termination and other information about the terminated process
67 in the following manner:
68 o If the low-order 8 bits of w_status are equal to 0177, the
70 child process has stopped; the 8 bits higher up from the
71 low-order 8 bits of w_status contain the number of the sig‐
72 nal that caused the process to stop. Seeptrace(3C) and
73 sigvec(3UCB).
74 o If the low-order 8 bits of w_status are non-zero and are not
76 equal to 0177, the child process terminated due to a signal;
77 the low-order 7 bits of w_status contain the number of the
78 signal that terminated the process. In addition, if the low-
79 order seventh bit of w_status (that is, bit 0200) is set, a
80 ``core image'' of the process was produced; see
81 sigvec(3UCB).
82 o Otherwise, the child process terminated due to an exit()
84 call; the 8 bits higher up from the low-order 8 bits of
85 w_status contain the low-order 8 bits of the argument that
86 the child process passed to exit(); see exit(2).
87 waitpid() behaves identically to wait() if pid has a value of −1 and
90 options has a value of zero. Otherwise, the behavior of waitpid() is
91 modified by the values of pid and options as follows:
92 pid specifies a set of child processes for which status is requested.
95 waitpid() only returns the status of a child process from this set.
96 o If pid is equal to −1, status is requested for any child
98 process. In this respect, waitpid() is then equivalent to
99 wait().
100 o If pid is greater than zero, it specifies the process ID of
102 a single child process for which status is requested.
103 o If pid is equal to zero, status is requested for any child
105 process whose process group ID is equal to that of the call‐
106 ing process.
107 o If pid is less than −1, status is requested for any child
109 process whose process group ID is equal to the absolute
110 value of pid.
111 options is constructed from the bitwise inclusive OR of zero or more of
114 the following flags, defined in the header <sys/wait.h>:
115 WNOHANG waitpid() does not suspend execution of the calling
117 process if status is not immediately available for one of
118 the child processes specified by pid.
119 WUNTRACED The status of any child processes specified by pid that
122 are stopped, and whose status has not yet been reported
123 since they stopped, are also reported to the requesting
124 process.
125 wait3() is an alternate interface that allows both non-blocking status
129 collection and the collection of the status of children stopped by any
130 means. The status parameter is defined as above. The options parameter
131 is used to indicate the call should not block if there are no processes
132 that have status to report (WNOHANG), and/or that children of the cur‐
133 rent process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or
134 SIGSTOP signal are eligible to have their status reported as well (WUN‐
135 TRACED). A terminated child is discarded after it reports status, and a
136 stopped process will not report its status more than once. If rusage is
137 not a NULL pointer, a summary of the resources used by the terminated
138 process and all its children is returned. Only the user time used and
139 the system time used are currently available. They are returned in
140 rusage.ru_utime and rusage.ru_stime, respectively.
141 When the WNOHANG option is specified and no processes have status to
144 report, wait3() returns 0. The WNOHANG and WUNTRACED options may be
145 combined by ORing the two values.
146 wait4() is another alternate interface. With a pid argument of 0, it
149 is equivalent to wait3(). If pid has a nonzero value, then wait4()
150 returns status only for the indicated process ID, but not for any other
151 child processes.
152 WIFSTOPPED, WIFSIGNALED, WIFEXITED, are macros that take an argument
155 status, of type int, as returned by wait(), or wait3(), or wait4().
156 WIFSTOPPED evaluates to true (1) when the process for which the wait()
157 call was made is stopped, or to false (0) otherwise. WIFSIGNALED evalu‐
158 ates to true when the process was terminated with a signal. WIFEXITED
159 evaluates to true when the process exited by using an exit(2) call.
160
162 If wait()or waitpid() returns due to a stopped or terminated child
163 process, the process ID of the child is returned to the calling
164 process. Otherwise, a value of −1 is returned and errno is set to indi‐
165 cate the error.
166 If wait() or waitpid() return due to the delivery of a signal to the
169 calling process, a value of −1 is returned and errno is set to EINTR.
170 If waitpid() function was invoked with WNOHANG set in options, it has
171 at least one child process specified by pid for which status is not
172 available, and status is not available for any process specified by
173 pid, a value of zero is returned. Otherwise, a value of −1 is returned,
174 and errno is set to indicate the error.
175 wait3() and wait4() return 0 if WNOHANG is specified and there are no
178 stopped or exited children, and returns the process ID of the child
179 process if it returns due to a stopped or terminated child process.
180 Otherwise, they returns a value of −1 and sets errno to indicate the
181 error.
182
184 The wait(), wait3() and wait4() functions will fail and return immedi‐
185 ately if:
186 ECHILD The calling process has no existing unwaited-for child pro‐
188 cesses.
189 EFAULT The status or rusage arguments point to an illegal address.
192 waitpid() may set errno to:
196 ECHILD The process or process group specified by pid does not exist
198 or is not a child of the calling process.
199 EINTR The function was interrupted by a signal. The value of the
202 location pointed to by statusp is undefined.
203 EINVAL The value of options is not valid.
206 The wait(), wait3(), and wait4() functions will terminate prematurely,
210 return −1, and set errno to EINTR upon the arrival of a signal whose
211 SV_INTERRUPT bit in its flags field is set (see sigvec(3UCB) and sigin‐
212 terrupt(3UCB)). signal(3UCB), sets this bit for any signal it catches.
213
215 exit(2), getrusage(3C), ptrace(3C), siginterrupt(3UCB), signal(3C),
216 signal(3UCB), sigvec(3UCB), wait(3C), waitpid(3C)
217
219 Use of these interfaces should be restricted to only applications writ‐
220 ten on BSD platforms. Use of these interfaces with any of the system
221 libraries or in multi-thread applications is unsupported.
222 If a parent process terminates without waiting on its children, the
225 initialization process (process ID = 1) inherits the children.
226 The wait(), wait3(), and wait4() functions are automatically restarted
229 when a process receives a signal while awaiting termination of a child
230 process, unless the SV_INTERRUPT bit is set in the flags for that sig‐
231 nal.
232 Calls to wait() with an argument of 0 should be cast to type `int *',
235 as in:
236 wait((int *)0)
238 Previous SunOS releases used union wait*statusp and union wait status
243 in place of int *statusp and int status. The union contained a member
244 w_status that could be treated in the same way as status.
245 Other members of the wait union could be used to extract this informa‐
248 tion more conveniently:
249 o If the w_stopval member had the value WSTOPPED, the child
251 process had stopped; the value of the w_stopsig member was
252 the signal that stopped the process.
253 o If the w_termsig member was non-zero, the child process ter‐
255 minated due to a signal; the value of the w_termsig member
256 was the number of the signal that terminated the process.
257 If the w_coredump member was non-zero, a core dump was pro‐
258 duced.
259 o Otherwise, the child process terminated due to a call to
261 exit(). The value of the w_retcode member was the low-order
262 8 bits of the argument that the child process passed to
263 exit().
264 union wait is obsolete in light of the new specifications provided by
267 IEEE Std 1003.1-1988 and endorsed by SVID89 and XPG3. SunOS Release 4.1
268 supports unionwait for backward compatibility, but it will disappear in
269 a future release.
270SunOS 5.11 30 Oct 2007 wait(3UCB)