date and time created 91/04/12 13:40:31 by bostic

[unix-history] / usr / src / lib / libc / sys / wait.2

diff --git a/usr/src/lib/libc/sys/wait.2 b/usr/src/lib/libc/sys/wait.2
index f7f1116..88f95f1 100644 (file)
--- a/usr/src/lib/libc/sys/wait.2
+++ b/usr/src/lib/libc/sys/wait.2
@@ -1,139 +1,269 @@
-.\" Copyright (c) 1980 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1980, 1991 Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.\"    @(#)wait.2      5.1 (Berkeley) %G%
+.\" %sccs.include.redist.man%

 .\"
 .\"

-.TH WAIT 2 "27 July 1983"
-.UC 4
-.SH NAME
-wait, wait3 \- wait for process to terminate
-.SH SYNOPSIS
-.ft B
-.nf
-#include <sys/wait.h>
-.PP
-.ft B
-pid = wait(status)
-int pid;
-union wait *status;
-.PP
-.ft B
-pid = wait(0)
-int pid;
-.PP
-.ft B
-#include <sys/time.h>
-#include <sys/resource.h>
-.PP
-.ft B
-pid = wait3(status, options, rusage)
-int pid;
-union wait *status;
-int options;
-struct rusage *rusage;
-.fi
-.SH DESCRIPTION
-.I Wait
-causes its caller to delay until a signal is received or
-one of its child
-processes terminates.
-If any child has died since the last
-.IR wait ,
-return is immediate, returning the process id and
-exit status of one of the terminated
-children.
-If there are no children, return is immediate with
-the value \-1 returned.
-.PP
+.\"     @(#)wait.2     6.5 (Berkeley) %G%
+.\"
+.Dd 
+.Dt WAIT 2
+.Os BSD 4
+.Sh NAME
+.Nm wait ,
+.Nm waitpid ,
+.Nm wait4 ,
+.Nm wait3
+.Nd wait for process terminatation
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/wait.h>
+.Ft pid_t
+.Fn wait "int *status"
+.Fd #include <sys/time.h>
+.Fd #include <sys/resource.h>
+.Ft pid_t
+.Fn waitpid "pid_t wpid" "int *status" "int options"
+.Ft pid_t
+.Fn wait3 "int *status" "int options" "struct rusage *rusage"
+.Ft pid_t
+.Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage"
+.Sh DESCRIPTION
+The
+.Fn wait
+function suspends execution of its calling process until
+.Fa status
+information is available for a terminated child process,
+or a signal is received.

 On return from a successful 
 On return from a successful 

-.I wait
+.Fn wait

 call, 
 call, 

-.I status
-is nonzero, and the high byte of 
-.I status
-contains the low byte of the argument to
-.I exit
-supplied by the child process;
-the low byte of 
-.I status
-contains the termination status of the process.
-A more precise definition of the
-.I status
-word is given in
-.RI < sys/wait.h >.
-.PP
-.I Wait3
-provides an alternate interface for programs
-which must not block when collecting the status
-of child processes.  The
-.I status
-parameter is defined as above.  The
-.I options
-parameter is used to indicate the call should not block if
-there are no processes which wish to report status (WNOHANG),
-and/or that only children of the current process which are stopped
-due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal should have
-their status reported (WUNTRACED).  If
-.I rusage
+the
+.Fa status
+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 accummulated by child processes,
+or that require options.
+The other wait functions are implemented using
+.Fn wait4 .
+.Pp
+The
+.Fa wpid
+parameter specifies the set of child processes for which to wait.
+If
+.Fa wpid
+is -1, the call waits for any child process.
+If
+.Fa wpid
+is 0,
+the call waits for any child process in the process group of the caller.
+If
+.Fa wpid
+is greater than zero, the call waits for the process with process id
+.Fa wpid .
+If
+.Fa wpid
+is less than -1, the call waits for any process whose process group id
+equals the absolute value of
+.Fa wpid .
+.Pp
+The
+.Fa status
+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).
 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 WNOHANG option is specified and no processes
+.Pp
+When the
+.Dv WNOHANG
+option is specified and no processes

 wish to report status, 
 wish to report status, 

-.I wait3
+.Fn wait4

 returns a 
 returns a 

-.I pid
-of 0.  The WNOHANG and WUNTRACED options may be combined by 
-.IR or 'ing
-the two values.
-.SH NOTES
+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 wpid
+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 2 .
+.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 2
+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
 See

-.IR sigvec (2)
-for a list of termination statuses (signals);
-0 status indicates normal termination.
-A special status (0177) is returned for a stopped process
-which has not terminated and can be restarted;
+.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
 see

-.IR ptrace (2).
-If the 0200 bit of the termination status
-is set,
-a core image of the process was produced
-by the system.
-.PP
-If the parent process terminates without
-waiting on its children,
-the initialization process
-(process ID = 1)
-inherits the children.
-.PP
-.I Wait
-and
-.I wait3
-are automatically restarted when a process receives a
-signal while awaiting termination of a child process.
-.SH "RETURN VALUE
-If \fIwait\fP returns due to a stopped
+.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 wait4 ,
+.Fn wait3
+or
+.Fn waitpid
+returns due to a stopped

 or terminated child process, the process ID of the child
 or terminated child process, the process ID of the child

-is returned to the calling process.  Otherwise, a value of \-1
-is returned and \fIerrno\fP is set to indicate the error.
-.PP
-.I Wait3
-returns \-1 if there are no children not previously waited
-for;  0 is returned if WNOHANG is specified and there are
-no stopped or exited children.
-.SH ERRORS
-.I Wait
-will fail and return immediately if one or more of the following
-are true:
-.TP 15
-[ECHILD]
+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
+.Fn Wait
+will fail and return immediately if:
+.Bl -tag -width Er
+.It Bq Er ECHILD

 The calling process has no existing unwaited-for
 child processes.
 The calling process has no existing unwaited-for
 child processes.

-.TP 15
-[EFAULT]
-The \fIstatus\fP or \fIrusage\fP arguments point to an illegal address.
-.SH "SEE ALSO"
-exit(2)
+.It Bq Er EFAULT
+The
+.Fa status
+or
+.Fa rusage
+arguments point to an illegal address.
+(May not be detected before exit of a child process.)
+.It Bq Er EINTR
+The call was interrupted by a caught signal,
+or the signal did not have the
+.Dv SA_RESTART
+flag set.
+.El
+.Sh STANDARDS
+The
+.Fn wait
+and
+.Fn waitpid
+functions are defined by POSIX;
+.Fn wait4
+and
+.Fn wait3
+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 SEE ALSO
+.Xr exit 2 ,
+.Xr sigaction 2
+.Sh HISTORY
+A
+.Nm
+function call appeared in Version 6 AT&T UNIX.