mirror of https://github.com/mkerrisk/man-pages
210 lines
5.8 KiB
Groff
210 lines
5.8 KiB
Groff
|
.\" Hey Emacs! This file is -*- nroff -*- source.
|
||
|
.\"
|
||
|
.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
|
||
|
.\"
|
||
|
.\" Permission is granted to make and distribute verbatim copies of this
|
||
|
.\" manual provided the copyright notice and this permission notice are
|
||
|
.\" preserved on all copies.
|
||
|
.\"
|
||
|
.\" Permission is granted to copy and distribute modified versions of this
|
||
|
.\" manual under the conditions for verbatim copying, provided that the
|
||
|
.\" entire resulting derived work is distributed under the terms of a
|
||
|
.\" permission notice identical to this one.
|
||
|
.\"
|
||
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
||
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
||
|
.\" responsibility for errors or omissions, or for damages resulting from
|
||
|
.\" the use of the information contained herein. The author(s) may not
|
||
|
.\" have taken the same level of care in the production of this manual,
|
||
|
.\" which is licensed free of charge, as they might when working
|
||
|
.\" professionally.
|
||
|
.\"
|
||
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
||
|
.\" the source, must acknowledge the copyright and authors of this work.
|
||
|
.\" License.
|
||
|
.\"
|
||
|
.\" Modified Sat Jul 24 13:32:44 1993 by Rik Faith (faith@cs.unc.edu)
|
||
|
.\" Modified Mon Jun 23 14:09:52 1997 by aeb - add EINTR.
|
||
|
.\" Modified Tue Jul 7 12:26:42 1998 by aeb - changed return value wait3
|
||
|
.\"
|
||
|
.TH WAIT4 2 1997-06-23 "Linux" "Linux Programmer's Manual"
|
||
|
.SH NAME
|
||
|
wait3, wait4 \- wait for process termination, BSD style
|
||
|
.SH SYNOPSIS
|
||
|
.nf
|
||
|
.B #include <sys/types.h>
|
||
|
.B #include <sys/time.h>
|
||
|
.B #include <sys/resource.h>
|
||
|
.B #include <sys/wait.h>
|
||
|
.sp 2
|
||
|
.BI "pid_t wait3(int *" "status" ", int " options ,
|
||
|
.BI " struct rusage *" rusage );
|
||
|
.sp
|
||
|
.BI "pid_t wait4(pid_t " pid ", int *" status ", int " options ,
|
||
|
.BI " struct rusage *" rusage );
|
||
|
.fi
|
||
|
.SH DESCRIPTION
|
||
|
The
|
||
|
.B wait3
|
||
|
function suspends execution of the current process until a child has
|
||
|
exited, or until a signal is delivered whose action is to terminate
|
||
|
the current process or to call a signal handling function. If a child
|
||
|
has already exited by the time of the call (a so\-called "zombie"
|
||
|
process), the function returns immediately. Any system resources used
|
||
|
by the child are freed.
|
||
|
|
||
|
The
|
||
|
.B wait4
|
||
|
function suspends execution of the current process until a
|
||
|
child as specified by the
|
||
|
.I pid
|
||
|
argument has exited, or until a signal is delivered whose action is to
|
||
|
terminate the current process or to call a signal handling function.
|
||
|
If a child as requested by
|
||
|
.I pid
|
||
|
has already exited by the time of the call (a so\-called "zombie"
|
||
|
process), the function returns immediately. Any system resources used
|
||
|
by the child are freed.
|
||
|
|
||
|
The value of
|
||
|
.I pid
|
||
|
can be one of:
|
||
|
.IP "< \-1"
|
||
|
which means to wait for any child process whose process group ID is
|
||
|
equal to the absolute value of
|
||
|
.IR pid .
|
||
|
.IP \-1
|
||
|
which means to wait for any child process; this is equivalent to
|
||
|
calling
|
||
|
.BR wait3 .
|
||
|
.IP 0
|
||
|
which means to wait for any child process whose process group ID is
|
||
|
equal to that of the calling process.
|
||
|
.IP "> 0"
|
||
|
which means to wait for the child whose process ID is equal to the
|
||
|
value of
|
||
|
.IR pid .
|
||
|
.PP
|
||
|
The value of
|
||
|
.I options
|
||
|
is a bitwise OR of zero or more of the following constants:
|
||
|
.TP
|
||
|
.B WNOHANG
|
||
|
which means to return immediately if no child is there to be waited
|
||
|
for.
|
||
|
.TP
|
||
|
.B WUNTRACED
|
||
|
which means to also return for children which are stopped, and whose
|
||
|
status has not been reported.
|
||
|
.PP
|
||
|
If
|
||
|
.I status
|
||
|
is not
|
||
|
.BR NULL ,
|
||
|
.B wait3
|
||
|
or
|
||
|
.B wait4
|
||
|
store status information in the location pointed to by
|
||
|
.IR status .
|
||
|
.PP
|
||
|
This status can be evaluated with the following macros (these macros take
|
||
|
the stat buffer (an \fBint\fR) as an argument \(em not a pointer to the
|
||
|
buffer!):
|
||
|
.TP
|
||
|
.BI WIFEXITED( status )
|
||
|
is non\-zero if the child exited normally.
|
||
|
.TP
|
||
|
.BI WEXITSTATUS( status )
|
||
|
evaluates to the least significant eight bits of the return code of
|
||
|
the child which terminated, which may have been set as the argument to
|
||
|
a call to
|
||
|
.B exit()
|
||
|
or as the argument for a
|
||
|
.B return
|
||
|
statement in the main program. This macro can only be evaluated if
|
||
|
.B WIFEXITED
|
||
|
returned non\-zero.
|
||
|
.TP
|
||
|
.BI WIFSIGNALED( status )
|
||
|
returns true if the child process exited because of a signal which was
|
||
|
not caught.
|
||
|
.TP
|
||
|
.BI WTERMSIG( status )
|
||
|
returns the number of the signal that caused the child process to
|
||
|
terminate. This macro can only be evaluated if
|
||
|
.B WIFSIGNALED
|
||
|
returned non\-zero.
|
||
|
.TP
|
||
|
.BI WIFSTOPPED( status )
|
||
|
returns true if the child process which caused the return is currently
|
||
|
stopped; this is only possible if the call was done using
|
||
|
.BR WUNTRACED .
|
||
|
.TP
|
||
|
.BI WSTOPSIG( status )
|
||
|
returns the number of the signal which caused the child to stop. This
|
||
|
macro can only be evaluated if
|
||
|
.B WIFSTOPPED
|
||
|
returned non\-zero.
|
||
|
.PP
|
||
|
If
|
||
|
.I rusage
|
||
|
is not
|
||
|
.BR NULL ,
|
||
|
the
|
||
|
.B struct rusage
|
||
|
as defined in
|
||
|
.I <sys/resource.h>
|
||
|
it points to will be filled with accounting information. See
|
||
|
.BR getrusage (2)
|
||
|
for details.
|
||
|
.SH "RETURN VALUE"
|
||
|
The process ID of the child which exited, \-1 on error
|
||
|
(in particular, when no unwaited-for child processes
|
||
|
of the specified kind exist)
|
||
|
or zero if
|
||
|
.B WNOHANG
|
||
|
was used and no child was available yet.
|
||
|
In the latter two cases
|
||
|
.I errno
|
||
|
will be set appropriately.
|
||
|
.SH ERRORS
|
||
|
.TP
|
||
|
.B ECHILD
|
||
|
No unwaited-for child process as specified does exist.
|
||
|
.TP
|
||
|
.B EINTR
|
||
|
if
|
||
|
.B WNOHANG
|
||
|
was not set and an unblocked signal or a
|
||
|
.B SIGCHLD
|
||
|
was caught.
|
||
|
.TP
|
||
|
.B EINVAL
|
||
|
Invalid value for
|
||
|
.I options
|
||
|
given for wait4.
|
||
|
.SH NOTES
|
||
|
Including
|
||
|
.I <sys/time.h>
|
||
|
is not required these days, but increases portability.
|
||
|
(Indeed,
|
||
|
.I <sys/resource.h>
|
||
|
defines the
|
||
|
.I rusage
|
||
|
structure with fields of type
|
||
|
.I struct timeval
|
||
|
defined in
|
||
|
.IR <sys/time.h> .)
|
||
|
.LP
|
||
|
The prototype for these functions is only available if
|
||
|
.B _BSD_SOURCE
|
||
|
is defined (either explicitly, or implicitly, by not defining
|
||
|
_POSIX_SOURCE or compiling with the -ansi flag).
|
||
|
.SH "CONFORMING TO"
|
||
|
SVr4, POSIX.1
|
||
|
.SH "SEE ALSO"
|
||
|
.BR getrusage (2),
|
||
|
.BR signal (2),
|
||
|
.BR wait (2),
|
||
|
.BR signal (7)
|