[apple/xnu.git] / bsd / man / man2 / wait.2

.\"	$NetBSD: wait.2,v 1.6 1995/02/27 12:39:37 cgd Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993, 1994
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)wait.2	8.2 (Berkeley) 4/19/94
.\"
.Dd April 19, 1994
.Dt WAIT 2
.Os BSD 4
.Sh NAME
.Nm wait ,
.Nm wait3 ,
.Nm wait4 ,
.Nm waitpid
.Nd wait for process termination
.Sh SYNOPSIS
.Fd #include <sys/wait.h>
.Ft pid_t
.Fo wait
.Fa "int *stat_loc"
.Fc
.Ft pid_t
.Fo wait3
.Fa "int *stat_loc"
.Fa "int options"
.Fa "struct rusage *rusage"
.Fc
.Ft pid_t
.Fo wait4
.Fa "pid_t pid"
.Fa "int *stat_loc"
.Fa "int options"
.Fa "struct rusage *rusage"
.Fc
.Ft pid_t
.Fo waitpid
.Fa "pid_t pid"
.Fa "int *stat_loc"
.Fa "int options"
.Fc
.Sh DESCRIPTION
The
.Fn wait
function suspends execution of its calling process until
.Fa stat_loc
information is available for a terminated child process,
or a signal is received.
On return from a successful 
.Fn wait
call, 
the
.Fa stat_loc
area contains termination information about the process that exited
as defined below.
.Pp
The
.Fn wait4
call provides a more general interface for programs
that need to wait for certain child processes,
that need resource utilization statistics accumulated by child processes,
or that require options.
The other wait functions are implemented using
.Fn wait4 .
.Pp
The
.Fa pid
parameter specifies the set of child processes for which to wait.
If
.Fa pid
is -1, the call waits for any child process.
If
.Fa pid
is 0,
the call waits for any child process in the process group of the caller.
If
.Fa pid
is greater than zero, the call waits for the process with process id
.Fa pid .
If
.Fa pid
is less than -1, the call waits for any process whose process group id
equals the absolute value of
.Fa pid .
.Pp
The
.Fa stat_loc
parameter is defined below.  The
.Fa options
parameter contains the bitwise OR of any of the following options.
The
.Dv WNOHANG
option
is used to indicate that the call should not block if
there are no processes that wish to report status.
If the
.Dv WUNTRACED
option is set,
children of the current process that are stopped
due to a
.Dv SIGTTIN , SIGTTOU , SIGTSTP ,
or
.Dv SIGSTOP
signal also have
their status reported.
.Pp
If
.Fa rusage
is non-zero, a summary of the resources used by the terminated
process and all its
children is returned (this information is currently not available
for stopped processes).
.Pp
When the
.Dv WNOHANG
option is specified and no processes
wish to report status, 
.Fn wait4
returns a 
process id
of 0.
.Pp
The
.Fn waitpid
call is identical to
.Fn wait4
with an
.Fa rusage
value of zero.
The older
.Fn wait3
call is the same as
.Fn wait4
with a
.Fa pid
value of -1.
.Pp
The following macros may be used to test the manner of exit of the process.
One of the first three macros will evaluate to a non-zero (true) value:
.Bl -tag -width Ds
.It Fn WIFEXITED status
True if the process terminated normally by a call to
.Xr _exit 2
or
.Xr exit 3 .
.It Fn WIFSIGNALED status
True if the process terminated due to receipt of a signal.
.It Fn WIFSTOPPED status
True if the process has not terminated, but has stopped and can be restarted.
This macro can be true only if the wait call specified the
.Dv WUNTRACED
option
or if the child process is being traced (see
.Xr ptrace 2 ) .
.El
.Pp
Depending on the values of those macros, the following macros
produce the remaining status information about the child process:
.Bl -tag -width Ds
.It Fn WEXITSTATUS status
If
.Fn WIFEXITED status
is true, evaluates to the low-order 8 bits
of the argument passed to
.Xr _exit 2
or
.Xr exit 3
by the child.
.It Fn WTERMSIG status
If
.Fn WIFSIGNALED status
is true, evaluates to the number of the signal
that caused the termination of the process.
.It Fn WCOREDUMP status
If
.Fn WIFSIGNALED status
is true, evaluates as true if the termination
of the process was accompanied by the creation of a core file
containing an image of the process when the signal was received.
.It Fn WSTOPSIG status
If
.Fn WIFSTOPPED status
is true, evaluates to the number of the signal
that caused the process to stop.
.El
.Sh NOTES
See
.Xr sigaction 2
for a list of termination signals.
A status of 0 indicates normal termination.
.Pp
If a parent process terminates without
waiting for all of its child processes to terminate,
the remaining child processes are assigned the parent
process 1 ID (the init process ID).
.Pp
If a signal is caught while any of the
.Fn wait
calls is pending,
the call may be interrupted or restarted when the signal-catching routine
returns,
depending on the options in effect for the signal;
see
.Xr intro 2 ,
System call restart.
.Sh RETURN VALUES
If
.Fn wait
returns due to a stopped
or terminated child process, the process ID of the child
is returned to the calling process.  Otherwise, a value of -1
is returned and
.Va errno
is set to indicate the error.
.Pp
If
.Fn wait3 ,
.Fn wait4 ,
or
.Fn waitpid
returns due to a stopped
or terminated child process, the process ID of the child
is returned to the calling process.
If there are no children not previously awaited,
-1 is returned with
.Va errno
set to
.Bq Er ECHILD .
Otherwise, if
.Dv WNOHANG
is specified and there are
no stopped or exited children,
0 is returned.
If an error is detected or a caught signal aborts the call,
a value of -1
is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn wait
system call will fail and return immediately if:
.Bl -tag -width Er
.\" ===========
.It Bq Er ECHILD
The calling process has no existing unwaited-for child processes.
.\" ===========
.It Bq Er EFAULT
The
.Fa status
or
.Fa rusage
argument points to an illegal address
(may not be detected before the exit of a child process).
.\" ===========
.It Bq Er EINVAL
Invalid or undefined flags are passed in the
.Fa options
argument.
.El
.Pp
The
.Fn wait3
and
.Fn waitpid
calls will fail and return immediately if:
.Bl -tag -width Er
.\" ===========
.It Bq Er ECHILD
The process specified by
.Fa pid
does not exist or is not a child of the calling process,
or the process group specified by
.Fa pid
does not exist or does not have any member process
that is a child of the calling process.
.El
.Pp
The
.Fn waitpid
call will fail and return immediately if:
.Bl -tag -width Er
.\" ===========
.It Bq Er EINVAL
The options argument is not valid.
.El
.Pp
Any of these calls will fail and return immediately if:
.Bl -tag -width Er
.\" ===========
.It Bq Er EINTR
The call is interrupted by a caught signal
or the signal does not have the
.Dv SA_RESTART
flag set.
.El
.Sh STANDARDS
The
.Fn wait
and
.Fn waitpid
functions are defined by POSIX;
.Fn wait3
and
.Fn wait4
are not specified by POSIX.
The
.Fn WCOREDUMP
macro
and the ability to restart a pending
.Fn wait
call are extensions to the POSIX interface.
.Sh LEGACY SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/wait.h>
.Pp
The include file
.In sys/types.h
is necessary.
.Sh SEE ALSO
.Xr sigaction 2 ,
.Xr exit 3 ,
.Xr compat 5
.Sh HISTORY
A
.Fn wait
function call appeared in 
.At v6 .
Commit	Line	Data
9bccf70c A	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 ,
2d21ac55	41	.Nm wait3 ,
9bccf70c	42	.Nm wait4 ,
2d21ac55	43	.Nm waitpid
9bccf70c A	44	.Nd wait for process termination
9bccf70c A	45	.Sh SYNOPSIS
9bccf70c A	46	.Fd #include <sys/wait.h>
9bccf70c A	47	.Ft pid_t
2d21ac55 A	48	.Fo wait
	49	.Fa "int *stat_loc"
	50	.Fc
9bccf70c	51	.Ft pid_t
2d21ac55 A	52	.Fo wait3
	53	.Fa "int *stat_loc"
	54	.Fa "int options"
	55	.Fa "struct rusage *rusage"
	56	.Fc
9bccf70c	57	.Ft pid_t
2d21ac55 A	58	.Fo wait4
	59	.Fa "pid_t pid"
	60	.Fa "int *stat_loc"
	61	.Fa "int options"
	62	.Fa "struct rusage *rusage"
	63	.Fc
9bccf70c	64	.Ft pid_t
2d21ac55 A	65	.Fo waitpid
	66	.Fa "pid_t pid"
	67	.Fa "int *stat_loc"
	68	.Fa "int options"
	69	.Fc
9bccf70c A	70	.Sh DESCRIPTION
	71	The
	72	.Fn wait
	73	function suspends execution of its calling process until
2d21ac55	74	.Fa stat_loc
9bccf70c A	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
2d21ac55	81	.Fa stat_loc
9bccf70c A	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
2d21ac55	95	.Fa pid
9bccf70c A	96	parameter specifies the set of child processes for which to wait.
9bccf70c A	97	If
2d21ac55	98	.Fa pid
9bccf70c A	99	is -1, the call waits for any child process.
9bccf70c A	100	If
2d21ac55	101	.Fa pid
9bccf70c A	102	is 0,
	103	the call waits for any child process in the process group of the caller.
	104	If
2d21ac55	105	.Fa pid
9bccf70c	106	is greater than zero, the call waits for the process with process id
2d21ac55	107	.Fa pid .
9bccf70c	108	If
2d21ac55	109	.Fa pid
9bccf70c A	110	is less than -1, the call waits for any process whose process group id
9bccf70c A	111	equals the absolute value of
2d21ac55	112	.Fa pid .
9bccf70c A	113	.Pp
9bccf70c A	114	The
2d21ac55	115	.Fa stat_loc
9bccf70c A	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
2d21ac55	163	.Fa pid
9bccf70c A	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
55e303ae	173	.Xr exit 3 .
9bccf70c A	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
55e303ae	195	.Xr exit 3
9bccf70c A	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
2d21ac55	245	.Fn wait3 ,
9bccf70c	246	.Fn wait4 ,
9bccf70c A	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
2d21ac55 A	268	The
	269	.Fn wait
	270	system call will fail and return immediately if:
9bccf70c	271	.Bl -tag -width Er
2d21ac55	272	.\" ===========
9bccf70c	273	.It Bq Er ECHILD
2d21ac55 A	274	The calling process has no existing unwaited-for child processes.
2d21ac55 A	275	.\" ===========
9bccf70c A	276	.It Bq Er EFAULT
	277	The
	278	.Fa status
	279	or
	280	.Fa rusage
2d21ac55 A	281	argument points to an illegal address
	282	(may not be detected before the exit of a child process).
	283	.\" ===========
9bccf70c	284	.It Bq Er EINVAL
2d21ac55	285	Invalid or undefined flags are passed in the
9bccf70c A	286	.Fa options
	287	argument.
	288	.El
2d21ac55 A	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
9bccf70c A	325	.Sh STANDARDS
	326	The
	327	.Fn wait
	328	and
	329	.Fn waitpid
	330	functions are defined by POSIX;
9bccf70c	331	.Fn wait3
2d21ac55 A	332	and
2d21ac55 A	333	.Fn wait4
9bccf70c A	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.
2d21ac55 A	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.
9bccf70c	348	.Sh SEE ALSO
2d21ac55	349	.Xr sigaction 2 ,
55e303ae	350	.Xr exit 3 ,
2d21ac55	351	.Xr compat 5
9bccf70c A	352	.Sh HISTORY
	353	A
	354	.Fn wait
	355	function call appeared in
	356	.At v6 .