]> git.saurik.com Git - apple/xnu.git/blame_incremental - bsd/man/man2/wait.2
xnu-1228.9.59.tar.gz
[apple/xnu.git] / bsd / man / man2 / wait.2
... / ...
CommitLineData
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
71The
72.Fn wait
73function suspends execution of its calling process until
74.Fa stat_loc
75information is available for a terminated child process,
76or a signal is received.
77On return from a successful
78.Fn wait
79call,
80the
81.Fa stat_loc
82area contains termination information about the process that exited
83as defined below.
84.Pp
85The
86.Fn wait4
87call provides a more general interface for programs
88that need to wait for certain child processes,
89that need resource utilization statistics accumulated by child processes,
90or that require options.
91The other wait functions are implemented using
92.Fn wait4 .
93.Pp
94The
95.Fa pid
96parameter specifies the set of child processes for which to wait.
97If
98.Fa pid
99is -1, the call waits for any child process.
100If
101.Fa pid
102is 0,
103the call waits for any child process in the process group of the caller.
104If
105.Fa pid
106is greater than zero, the call waits for the process with process id
107.Fa pid .
108If
109.Fa pid
110is less than -1, the call waits for any process whose process group id
111equals the absolute value of
112.Fa pid .
113.Pp
114The
115.Fa stat_loc
116parameter is defined below. The
117.Fa options
118parameter contains the bitwise OR of any of the following options.
119The
120.Dv WNOHANG
121option
122is used to indicate that the call should not block if
123there are no processes that wish to report status.
124If the
125.Dv WUNTRACED
126option is set,
127children of the current process that are stopped
128due to a
129.Dv SIGTTIN , SIGTTOU , SIGTSTP ,
130or
131.Dv SIGSTOP
132signal also have
133their status reported.
134.Pp
135If
136.Fa rusage
137is non-zero, a summary of the resources used by the terminated
138process and all its
139children is returned (this information is currently not available
140for stopped processes).
141.Pp
142When the
143.Dv WNOHANG
144option is specified and no processes
145wish to report status,
146.Fn wait4
147returns a
148process id
149of 0.
150.Pp
151The
152.Fn waitpid
153call is identical to
154.Fn wait4
155with an
156.Fa rusage
157value of zero.
158The older
159.Fn wait3
160call is the same as
161.Fn wait4
162with a
163.Fa pid
164value of -1.
165.Pp
166The following macros may be used to test the manner of exit of the process.
167One of the first three macros will evaluate to a non-zero (true) value:
168.Bl -tag -width Ds
169.It Fn WIFEXITED status
170True if the process terminated normally by a call to
171.Xr _exit 2
172or
173.Xr exit 3 .
174.It Fn WIFSIGNALED status
175True if the process terminated due to receipt of a signal.
176.It Fn WIFSTOPPED status
177True if the process has not terminated, but has stopped and can be restarted.
178This macro can be true only if the wait call specified the
179.Dv WUNTRACED
180option
181or if the child process is being traced (see
182.Xr ptrace 2 ) .
183.El
184.Pp
185Depending on the values of those macros, the following macros
186produce the remaining status information about the child process:
187.Bl -tag -width Ds
188.It Fn WEXITSTATUS status
189If
190.Fn WIFEXITED status
191is true, evaluates to the low-order 8 bits
192of the argument passed to
193.Xr _exit 2
194or
195.Xr exit 3
196by the child.
197.It Fn WTERMSIG status
198If
199.Fn WIFSIGNALED status
200is true, evaluates to the number of the signal
201that caused the termination of the process.
202.It Fn WCOREDUMP status
203If
204.Fn WIFSIGNALED status
205is true, evaluates as true if the termination
206of the process was accompanied by the creation of a core file
207containing an image of the process when the signal was received.
208.It Fn WSTOPSIG status
209If
210.Fn WIFSTOPPED status
211is true, evaluates to the number of the signal
212that caused the process to stop.
213.El
214.Sh NOTES
215See
216.Xr sigaction 2
217for a list of termination signals.
218A status of 0 indicates normal termination.
219.Pp
220If a parent process terminates without
221waiting for all of its child processes to terminate,
222the remaining child processes are assigned the parent
223process 1 ID (the init process ID).
224.Pp
225If a signal is caught while any of the
226.Fn wait
227calls is pending,
228the call may be interrupted or restarted when the signal-catching routine
229returns,
230depending on the options in effect for the signal;
231see
232.Xr intro 2 ,
233System call restart.
234.Sh RETURN VALUES
235If
236.Fn wait
237returns due to a stopped
238or terminated child process, the process ID of the child
239is returned to the calling process. Otherwise, a value of -1
240is returned and
241.Va errno
242is set to indicate the error.
243.Pp
244If
245.Fn wait3 ,
246.Fn wait4 ,
247or
248.Fn waitpid
249returns due to a stopped
250or terminated child process, the process ID of the child
251is returned to the calling process.
252If there are no children not previously awaited,
253-1 is returned with
254.Va errno
255set to
256.Bq Er ECHILD .
257Otherwise, if
258.Dv WNOHANG
259is specified and there are
260no stopped or exited children,
2610 is returned.
262If an error is detected or a caught signal aborts the call,
263a value of -1
264is returned and
265.Va errno
266is set to indicate the error.
267.Sh ERRORS
268The
269.Fn wait
270system call will fail and return immediately if:
271.Bl -tag -width Er
272.\" ===========
273.It Bq Er ECHILD
274The calling process has no existing unwaited-for child processes.
275.\" ===========
276.It Bq Er EFAULT
277The
278.Fa status
279or
280.Fa rusage
281argument points to an illegal address
282(may not be detected before the exit of a child process).
283.\" ===========
284.It Bq Er EINVAL
285Invalid or undefined flags are passed in the
286.Fa options
287argument.
288.El
289.Pp
290The
291.Fn wait3
292and
293.Fn waitpid
294calls will fail and return immediately if:
295.Bl -tag -width Er
296.\" ===========
297.It Bq Er ECHILD
298The process specified by
299.Fa pid
300does not exist or is not a child of the calling process,
301or the process group specified by
302.Fa pid
303does not exist or does not have any member process
304that is a child of the calling process.
305.El
306.Pp
307The
308.Fn waitpid
309call will fail and return immediately if:
310.Bl -tag -width Er
311.\" ===========
312.It Bq Er EINVAL
313The options argument is not valid.
314.El
315.Pp
316Any of these calls will fail and return immediately if:
317.Bl -tag -width Er
318.\" ===========
319.It Bq Er EINTR
320The call is interrupted by a caught signal
321or the signal does not have the
322.Dv SA_RESTART
323flag set.
324.El
325.Sh STANDARDS
326The
327.Fn wait
328and
329.Fn waitpid
330functions are defined by POSIX;
331.Fn wait3
332and
333.Fn wait4
334are not specified by POSIX.
335The
336.Fn WCOREDUMP
337macro
338and the ability to restart a pending
339.Fn wait
340call are extensions to the POSIX interface.
341.Sh LEGACY SYNOPSIS
342.Fd #include <sys/types.h>
343.Fd #include <sys/wait.h>
344.Pp
345The include file
346.In sys/types.h
347is necessary.
348.Sh SEE ALSO
349.Xr sigaction 2 ,
350.Xr exit 3 ,
351.Xr compat 5
352.Sh HISTORY
353A
354.Fn wait
355function call appeared in
356.At v6 .