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 d19d772..88f95f1 100644 (file)
--- a/usr/src/lib/libc/sys/wait.2
+++ b/usr/src/lib/libc/sys/wait.2
@@ -1,84 +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      4.1 (Berkeley) %G%
+.\" %sccs.include.redist.man%

 .\"
 .\"

-.TH WAIT 2 
-.UC 4
-.SH NAME
-wait \- wait for process to terminate
-.SH SYNOPSIS
-.nf
-.B wait(status)
-.B int *status;
-.fi
-.PP
-.B wait(0)
-.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
-.I wait,
-return is immediate;
-if there are no children, return is immediate with
-the error bit set
-(resp. with a value of \-1 returned).
-The normal return yields the process ID of the terminated child.
-In the case of several children several
-.I wait
-calls are needed
-to learn of all the deaths.
-.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 
+.Fn wait
+call, 
+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
 If

-.RI (int) status
-is nonzero, the high byte of the word pointed to
-receives the low byte of the
-argument of
-.I exit
-when the child terminated.
-The low byte
-receives the termination status
-of the process.
-See
-.IR signal (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.
+.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).
+.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 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 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
-There is another entry
-.IR wait3 (2)
-which is provides additional options needed by the shell
-.IR csh (1)
-to do job control.
-.SH "SEE ALSO"
-wait3(2), exit(2), fork(2), signal(2)
-.SH DIAGNOSTICS
-Returns
-\-1 if there are no children not previously waited for.
-.SH "ASSEMBLER (PDP-11)"
-(wait = 7.)
-.br
-.B sys  wait
-.br
-(process ID in r0)
-.br
-(status in r1)
-.PP
-The high byte of the status is
-the low byte of r0 in the child at termination.
+.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 wait4 ,
+.Fn wait3
+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
+.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.
+.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.