Various updates and tweaks to the wait(2) manpage.

PR:		docs/183904
Submitted by:	Michael Galassi <michaelgalassi@gmail.com>
Reviewed by:	kib, wblock (earlier version)

1 files changed, 174 insertions, 132 deletions

diff --git a/lib/libc/sys/wait.2 b/lib/libc/sys/wait.2
index 5aa53dd..0374585 100644
--- a/lib/libc/sys/wait.2
+++ b/lib/libc/sys/wait.2
@@ -28,7 +28,7 @@
 .\"     @(#)wait.2	8.2 (Berkeley) 4/19/94
 .\" $FreeBSD$
 .\"
-.Dd September 7, 2013
+.Dd December 3, 2013
 .Dt WAIT 2
 .Os
 .Sh NAME
@@ -62,63 +62,76 @@
 .Sh DESCRIPTION
 The
 .Fn wait
-function suspends execution of its calling process until
+function suspends execution of its calling thread until
 .Fa status
-information is available for a terminated child process,
+information is available for a 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
+area contains information about the process that reported a status change
 as defined below.
-The
-.Fn wait
-call is the same as
-.Fn wait4
-with a
-.Fa wpid
-value of -1,
-with an
-.Fa options
-value of zero,
-and a
-.Fa rusage
-value of zero.
 .Pp
 The
 .Fn wait4
-system call provides a more general interface for programs
-that need to wait for certain child processes,
+and
+.Fn wait6
+system calls provide a more general interface for programs
+that need to wait for specific child processes,
 that need resource utilization statistics accumulated by child processes,
 or that require options.
+The other wait functions are implemented using either
+.Fn wait4
+or
+.Fn wait6 .
 .Pp
-The broadest interface of all functions in this family is
+The
 .Fn wait6
-which is otherwise very much like
+function is the most general function in this family and its distinct
+features are:
+.Pp
+All of the desired process statuses to be waited on must be explicitly
+specified in
+.Fa options .
+The
+.Fn wait ,
+.Fn waitpid ,
+.Fn wait3 ,
+and
 .Fn wait4
-but with a few very important distinctions.
-To wait for exited processes, the option flag
+functions all implicitly wait for exited and trapped processes,
+but the
+.Fn waitid 
+and
+.Fn wait6
+functions require the corresponding
 .Dv WEXITED
-need to be explicitly specified.
-This allows for waiting for processes which have experienced other
-status changes without having to handle also the exit status from
-the terminated processes.
-Instead of the traditional
-.Dv rusage
-argument, a pointer to a new structure
+and
+.Dv WTRAPPED
+flags to be explicitly specified.
+This allows waiting for processes which have experienced other
+status changes without having to also handle the exit status from
+terminated processes.
+.Pp
+The
+.Fn wait6
+function accepts a
+.Fa wrusage
+argument which points to a structure defined as:
 .Bd -literal
 struct __wrusage {
 	struct rusage   wru_self;
 	struct rusage   wru_children;
 };
 .Ed
-can be passed.
+.Pp
 This allows the calling process to collect resource usage statistics
 from both its own child process as well as from its grand children.
 When no resource usage statistics are needed this pointer can be
 .Dv NULL .
+.Pp
 The last argument
 .Fa infop
 must be either
@@ -126,11 +139,13 @@ must be either
 or a pointer to a
 .Fa siginfo_t
 structure.
-When specified, the structure is filled the same as for
-.Dv SIGNCHLD
-signal, delivered at the process state change.
-.br
-The process, which state is queried, is specified by two arguments
+If
+.Pf non- Dv NULL ,
+the structure is filled with the same data as for a
+.Dv SIGCHLD
+signal delivered when the process changed state.
+.Pp
+The set of child processes to be queried is specified by the arguments
 .Fa idtype
 and
 .Fa id .
@@ -138,8 +153,8 @@ The separate
 .Fa idtype
 and
 .Fa id
-arguments allows to support many other types of
-IDs  as well in addition to PID and PGID.
+arguments support many other types of
+identifers in addition to process IDs and process group IDs.
 .Bl -bullet -offset indent
 .It
 If
@@ -188,50 +203,33 @@ and
 wait for any child process in the same process group as the caller.
 .El
 .Pp
-Non-standard specifiers for the process to wait for, supported by this
+Non-standard identifier types supported by this 
 implementation of
 .Fn waitid
 and
-.Fn wait6 ,
+.Fn wait6
 are:
-.Bl -bullet -offset indent
-.It
-The
-.Fa idtype
-value
-.Dv P_UID
-waits for processes which effective UID is equal to
-.Dv (uid_t)id .
-.It
-The
-.Fa idtype
-value
-.Dv P_GID
-waits for processes which effective GID is equal to
-.Dv (gid_t)id .
-.It
-The
-.Fa idtype
-value
-.Dv P_SID
-waits for processes which session ID is equal to
-.Dv id .
-In case the child process started its own new session,
-SID will be the same as its own PID.
-Otherwise the SID of a child process will match the caller's SID.
-.It
-The
-.Fa idtype
-value
-.Dv P_JAILID
-waits for processes within a jail which jail identifier is equal
-to
-.Dv id .
+.Bl -tag -width P_JAILID
+.It Dv P_UID
+Wait for processes whose effective user ID is equal to
+.Dv (uid_t) Fa id .
+.It Dv P_GID
+Wait for processes whose effective group ID is equal to
+.Dv (gid_t) Fa id .
+.It Dv P_SID
+Wait for processes whose session ID is equal to
+.Fa id .
+.\" This is just how sessions work, not sure this needs to be documented here
+If the child process started its own session,
+its session ID will be the same as its process ID.
+Otherwise the session ID of a child process will match the caller's session ID.
+.It Dv P_JAILID
+Waits for processes within a jail whose jail identifier is equal to
+.Fa id .
 .El
 .Pp
-For
-.Fn wait ,
-.Fn wait3 ,
+For the
+.Fn waitpid
 and
 .Fn wait4
 functions, the single
@@ -250,12 +248,12 @@ the call waits for any child process in the process group of the caller.
 .It
 If
 .Fa wpid
-is greater than zero, the call waits for the process with process id
+is greater than zero, the call waits for the process with process ID
 .Fa wpid .
 .It
 If
 .Fa wpid
-is less than -1, the call waits for any process whose process group id
+is less than -1, the call waits for any process whose process group ID
 equals the absolute value of
 .Fa wpid .
 .El
@@ -267,30 +265,44 @@ argument is defined below.
 The
 .Fa options
 argument contains the bitwise OR of any of the following options.
-.Bl -tag -width Ds
+.Bl -tag -width WCONTINUED
 .It Dv WCONTINUED
-indicates that children of the current process that
-have continued from a job control stop, by receiving a
+Report the status of selected processes that
+have continued from a job control stop by receiving a
 .Dv SIGCONT
-signal, should also have their status reported.
+signal.
 .It Dv WNOHANG
-is used to indicate that the call should not block when
+Do not block when
 there are no processes wishing to report status.
 .It Dv WUNTRACED
-indicates that children of the current process which are stopped
-due to a
+Report the status of selected processes which are stopped due to a
 .Dv SIGTTIN , SIGTTOU , SIGTSTP ,
 or
 .Dv SIGSTOP
-signal shall have their status reported.
+signal.
 .It Dv WSTOPPED
-is an alias for
+An alias for
 .Dv WUNTRACED .
 .It Dv WTRAPPED
-allows waiting for processes which have trapped or reached a breakpoint.
+Report the status of selected processes which are being traced via
+.Xr ptrace 2
+and have trapped or reached a breakpoint.
+This flag is implicitly set for the functions
+.Fn wait ,
+.Fn waitpid ,
+.Fn wait3 ,
+and
+.Fn wait4 .
+.br
+For the
+.Fn waitid
+and
+.Fn wait6
+functions, the flag has to be explicitly included in
+.Fa options
+if status reports from trapped processes are expected.
 .It Dv WEXITED
-indicates that the caller is wants to receive status reports from
-terminated processes.
+Report the status of selected processes which have terminated.
 This flag is implicitly set for the functions
 .Fn wait ,
 .Fn waitpid ,
@@ -302,11 +314,11 @@ For the
 .Fn waitid
 and
 .Fn wait6
-functions, the flag has to be explicitly included in the
-.Fa options ,
+functions, the flag has to be explicitly included in
+.Fa options
 if status reports from terminated processes are expected.
 .It Dv WNOWAIT
-keeps the process whose status is returned in a waitable state.
+Keep the process whose status is returned in a waitable state.
 The process may be waited for again after this call completes.
 .El
 .sp
@@ -336,50 +348,68 @@ process and all its children is returned.
 .Pp
 If
 .Fa wrusage
-argument is non-NULL, a resource usage statistics
-from both its own child process as well as from its grand children
-is returned.
+is non-NULL, separate summaries are returned for the resources used
+by the terminated process and the resources used by all its children.
 .Pp
 If
 .Fa infop
-is non-NULL, it must point to a
+is non-NULL, a
 .Dv siginfo_t
-structure which is filled on return such that the
-.Dv si_signo
-field is always
+structure is returned with the
+.Fa si_signo
+field set to
 .Dv SIGCHLD
-and the field
-.Dv si_pid
-if be non-zero, if there is a status change to report.
-If there are no status changes to report and WNOHANG is applied,
-both of these fields are returned zero.
-When using the
-.Fn waitid
-function with the
+and the
+.Fa si_pid
+field set to the process ID of the process reporting status.
+.Pp
+When the
 .Dv WNOHANG
-option set, checking these fields is the only way to know whether
-there were any status changes to report, because the return value
-from
+option is specified and no processes
+wish to report status,
 .Fn waitid
-is be zero as it is for any successful return from
-.Fn waitid .
+sets the
+.Fa si_signo
+and
+.Fa si_pid
+fields in
+.Fa infop
+to zero.
+Checking these fields is the only way to know if a status change was reported.
 .Pp
 When the
 .Dv WNOHANG
 option is specified and no processes
 wish to report status,
 .Fn wait4
-returns a
+and
+.Fn wait6
+return a
 process id
 of 0.
 .Pp
 The
+.Fn wait
+call is the same as
+.Fn wait4
+with a
+.Fa wpid
+value of -1,
+with an
+.Fa options
+value of zero,
+and a
+.Fa rusage
+value of
+.Dv NULL .
+The
 .Fn waitpid
 function is identical to
 .Fn wait4
 with an
 .Fa rusage
-value of zero.
+value of
+.Dv NULL .
 The older
 .Fn wait3
 call is the same as
@@ -388,29 +418,31 @@ with a
 .Fa wpid
 value of -1.
 The
+.Fn wait4
+function is identical to
 .Fn wait6
-call, with the bits
+with the flags
 .Dv WEXITED
 and
 .Dv WTRAPPED
-set in the
+set in
 .Fa options
-and with
+and
 .Fa infop
 set to
-.Dv NULL ,
-is similar to
-.Fn wait4 .
+.Dv NULL .
 .Pp
-The following macros may be used to test the manner of exit of the process.
-One of the first four macros will evaluate to a non-zero (true) value:
+The following macros may be used to test the current status of the process.
+Exactly one of the following four macros will evaluate to a non-zero
+.Pq true
+value:
 .Bl -tag -width Ds
 .It Fn WIFCONTINUED status
 True if the process has not terminated, and
 has continued after a job control stop.
 This macro can be true only if the wait call specified the
 .Dv WCONTINUED
-option).
+option.
 .It Fn WIFEXITED status
 True if the process terminated normally by a call to
 .Xr _exit 2
@@ -481,7 +513,7 @@ in
 The implementation queues one
 .Dv SIGCHLD
 signal for each child process whose
-status has changed, if
+status has changed; if
 .Fn wait
 returns because the status of a child process is available, the pending
 SIGCHLD signal associated with the process ID of the child process will
@@ -492,7 +524,7 @@ signals remain pending.
 .Pp
 If
 .Dv SIGCHLD
-is blocked,
+is blocked and
 .Fn wait
 returns because the status of a child process is available, the pending
 .Dv SIGCHLD
@@ -538,13 +570,23 @@ If
 .Fn waitid
 returns because one or more processes have a state change to report,
 0 is returned.
-To indicate an error, -1 will be returned and
-.Dv errno
-set to an appropriate value.
+If an error is detected,
+a value of -1
+is returned and
+.Va errno
+is set to indicate the error.
 If
 .Dv WNOHANG
-was used, 0 can be returned indicating no error, but no processes
-may have changed state either, if si_signo and/or si_pid are zero.
+is specified and there are
+no stopped, continued or exited children,
+0 is returned.
+The
+.Fa si_signo
+and
+.Fa si_pid
+fields of
+.Fa infop
+must be checked against zero to determine if a process reported status.
 .Sh ERRORS
 The
 .Fn wait
@@ -620,7 +662,7 @@ requires
 .Fn waitid
 to return the full 32 bits passed to
 .Xr _exit 2 ;
-this implementation only returns 8 bits like in the other calls.
+this implementation only returns 8 bits like the other calls.
 .Sh HISTORY
 The
 .Fn wait