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