Document wait6() and waitid().

PR:	standards/170346
Submitted by:	"Jukka A. Ukkonen" <jau@iki.fi>
MFC after:	1 month

1 files changed, 280 insertions, 31 deletions

diff --git a/lib/libc/sys/wait.2 b/lib/libc/sys/wait.2
index 71bd529..0c494bb 100644
--- a/lib/libc/sys/wait.2
+++ b/lib/libc/sys/wait.2
@@ -28,15 +28,17 @@
 .\"     @(#)wait.2	8.2 (Berkeley) 4/19/94
 .\" $FreeBSD$
 .\"
-.Dd November 12, 2005
+.Dd November 10, 2012
 .Dt WAIT 2
 .Os
 .Sh NAME
 .Nm wait ,
+.Nm waitid ,
 .Nm waitpid ,
+.Nm wait3 ,
 .Nm wait4 ,
-.Nm wait3
-.Nd wait for process termination
+.Nm wait6
+.Nd wait for processes to change status
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -46,12 +48,17 @@
 .Fn wait "int *status"
 .Ft pid_t
 .Fn waitpid "pid_t wpid" "int *status" "int options"
+.In sys/signal.h
+.Ft int
+.Fn waitid "idtype_t idtype" "id_t id" "siginfo_t *info" "int options"
 .In sys/time.h
 .In sys/resource.h
 .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"
+.Ft pid_t
+.Fn wait6 "idtype_t idtype" "id_t id" "int *status" "int options" "struct __wrusage *wrusage" "siginfo_t *infop"
 .Sh DESCRIPTION
 The
 .Fn wait
@@ -86,28 +93,172 @@ system 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 broadest interface of all functions in this family is
+.Fn wait6
+which is otherwise very much like
+.Fn wait4
+but with a few very important distinctions.
+To wait for exited processes, the option flag
+.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
+.Bd -literal
+struct __wrusage {
+	struct rusage   wru_self;
+	struct rusage   wru_children;
+};
+.Ed
+can be passed.
+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 .
+The last argument
+.Fa infop
+must be either
+.Dv NULL
+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
+.Fa idtype
+and
+.Fa id .
+The separate
+.Fa idtype
+and
+.Fa id
+arguments allows to support many other types of
+IDs  as well in addition to PID and PGID.
+.Bl -bullet -offset indent
+.It
+If
+.Fa idtype
+is
+.Dv P_PID ,
+.Fn waitid
+and
+.Fn wait6
+wait for the child process with a process ID equal to
+.Dv (pid_t)id .
+.It
+If
+.Fa idtype
+is
+.Dv P_PGID ,
+.Fn waitid
+and
+.Fn wait6
+wait for the child process with a process group ID equal to
+.Dv (pid_t)id .
+.It
+If
+.Fa idtype
+is
+.Dv P_ALL ,
+.Fn waitid
+and
+.Fn wait6
+wait for any child process and the
+.Dv id
+is ignored.
+.It
+If
+.Fa idtype
+is
+.Dv P_PID
+or
+.Dv P_PGID
+and the
+.Dv id
+is zero,
+.Fn waitid
+and
+.Fn wait6
+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
+implementation of
+.Fn waitid
+and
+.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 .
+.El
+.Pp
+For
+.Fn wait ,
+.Fn wait3 ,
+and
+.Fn wait4
+functions, the single
 .Fa wpid
 argument specifies the set of child processes for which to wait.
+.Bl -bullet -offset indent
+.It
 If
 .Fa wpid
 is -1, the call waits for any child process.
+.It
 If
 .Fa wpid
 is 0,
 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
 .Fa wpid .
+.It
 If
 .Fa wpid
 is less than -1, the call waits for any process whose process group id
 equals the absolute value of
 .Fa wpid .
+.El
 .Pp
 The
 .Fa status
@@ -116,41 +267,102 @@ argument is defined below.
 The
 .Fa options
 argument contains the bitwise OR of any of the following options.
-The
-.Dv WCONTINUED
-option indicates that children of the current process that
+.Bl -tag -width Ds
+.It Dv WCONTINUED
+indicates that children of the current process that
 have continued from a job control stop, by receiving a
 .Dv SIGCONT
 signal, should also have their status reported.
-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
+.It Dv WNOHANG
+is used to indicate that the call should 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
 .Dv SIGTTIN , SIGTTOU , SIGTSTP ,
 or
 .Dv SIGSTOP
-signal also have their status reported.
-The
-.Dv WSTOPPED
-option is an alias for
+signal shall have their status reported.
+.It Dv WSTOPPED
+is an alias for
 .Dv WUNTRACED .
-The
-.Dv WNOWAIT
-option keeps the process whose status is returned in a waitable state.
+.It Dv WTRAPPED
+allows waiting for processes which have trapped or reached a breakpoint.
+.It Dv WEXITED
+indicates that the caller is wants to receive status reports from
+terminated processes.
+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 the
+.Fa options ,
+if status reports from terminated processes are expected.
+.It Dv WNOWAIT
+keeps the process whose status is returned in a waitable state.
 The process may be waited for again after this call completes.
+.El
+.sp
+For the
+.Fn waitid
+and
+.Fn wait6
+functions, at least one of the options
+.Dv WEXITED ,
+.Dv WUNTRACED ,
+.Dv WSTOPPED ,
+.Dv WTRAPPED ,
+or
+.Dv WCONTINUED
+must be specified.
+Otherwise there will be no events for the call to report.
+To avoid hanging indefinitely in such a case these functions
+return -1 with
+.Dv errno
+set to
+.Dv EINVAL .
 .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 or continued processes).
+is non-NULL, a summary of the resources used by the terminated
+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.
+.Pp
+If
+.Fa infop
+is non-NULL, it must point to a
+.Dv siginfo_t
+structure which is filled on return such that the
+.Dv si_signo
+field is always
+.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
+.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
+.Fn waitid
+is be zero as it is for any successful return from
+.Fn waitid .
 .Pp
 When the
 .Dv WNOHANG
@@ -175,6 +387,20 @@ call is the same as
 with a
 .Fa wpid
 value of -1.
+The
+.Fn wait6
+call, with the bits
+.Dv WEXITED
+and
+.Dv WTRAPPED
+set in the
+.Fa options
+and with
+.Fa infop
+set to
+.Dv NULL ,
+is similar to
+.Fn wait4 .
 .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:
@@ -284,6 +510,7 @@ is returned and
 is set to indicate the error.
 .Pp
 If
+.Fn wait6 ,
 .Fn wait4 ,
 .Fn wait3 ,
 or
@@ -306,6 +533,18 @@ a value of -1
 is returned and
 .Va errno
 is set to indicate the error.
+.Pp
+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
+.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.
 .Sh ERRORS
 The
 .Fn wait
@@ -335,6 +574,14 @@ The call was interrupted by a caught signal,
 or the signal did not have the
 .Dv SA_RESTART
 flag set.
+.It Bq Er EINVAL
+An invalid value was specified for
+.Fa options ,
+or
+.Fa idtype
+and
+.Fa id
+do not specify a valid set of processes.
 .El
 .Sh SEE ALSO
 .Xr _exit 2 ,
@@ -344,11 +591,13 @@ flag set.
 .Xr siginfo 3
 .Sh STANDARDS
 The
-.Fn wait
+.Fn wait ,
+.Fn waitpid ,
 and
-.Fn waitpid
+.Fn waitid
 functions are defined by POSIX;
-.Fn wait4
+.Fn wait6 ,
+.Fn wait4 ,
 and
 .Fn wait3
 are not specified by POSIX.