1 files changed, 614 insertions, 0 deletions

diff --git a/lib/libc/sys/wait.2 b/lib/libc/sys/wait.2
new file mode 100644
index 0000000..0c494bb
--- /dev/null
+++ b/lib/libc/sys/wait.2
@@ -0,0 +1,614 @@
+.\" Copyright (c) 1980, 1991, 1993, 1994
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)wait.2	8.2 (Berkeley) 4/19/94
+.\" $FreeBSD$
+.\"
+.Dd November 10, 2012
+.Dt WAIT 2
+.Os
+.Sh NAME
+.Nm wait ,
+.Nm waitid ,
+.Nm waitpid ,
+.Nm wait3 ,
+.Nm wait4 ,
+.Nm wait6
+.Nd wait for processes to change status
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/wait.h
+.Ft pid_t
+.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
+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.
+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,
+that need resource utilization statistics accumulated by child processes,
+or that require options.
+.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
+argument is defined below.
+.Pp
+The
+.Fa options
+argument contains the bitwise OR of any of the following options.
+.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.
+.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 shall have their status reported.
+.It Dv WSTOPPED
+is an alias for
+.Dv WUNTRACED .
+.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-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
+option is specified and no processes
+wish to report status,
+.Fn wait4
+returns a
+process id
+of 0.
+.Pp
+The
+.Fn waitpid
+function 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.
+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:
+.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).
+.It Fn WIFEXITED status
+True if the process terminated normally by a call to
+.Xr _exit 2
+or
+.Xr exit 3 .
+.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 3
+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
+.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 are pending,
+the call may be interrupted or restarted when the signal-catching routine
+returns,
+depending on the options in effect for the signal;
+see discussion of
+.Dv SA_RESTART
+in
+.Xr sigaction 2 .
+.Pp
+The implementation queues one
+.Dv SIGCHLD
+signal for each child process whose
+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
+be discarded.
+Any other pending
+.Dv SIGCHLD
+signals remain pending.
+.Pp
+If
+.Dv SIGCHLD
+is blocked,
+.Fn wait
+returns because the status of a child process is available, the pending
+.Dv SIGCHLD
+signal will be cleared unless another status of the child process
+is available.
+.Sh RETURN VALUES
+If
+.Fn wait
+returns due to a stopped, continued,
+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 wait6 ,
+.Fn wait4 ,
+.Fn wait3 ,
+or
+.Fn waitpid
+returns due to a stopped, continued,
+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
+.Er ECHILD .
+Otherwise, if
+.Dv WNOHANG
+is specified and there are
+no stopped, continued 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.
+.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
+function
+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 ECHILD
+No status from the terminated child process is available
+because the calling process has asked the system to discard
+such status by ignoring the signal
+.Dv SIGCHLD
+or setting the flag
+.Dv SA_NOCLDWAIT
+for that signal.
+.It Bq Er EFAULT
+The
+.Fa status
+or
+.Fa rusage
+argument points 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.
+.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 ,
+.Xr ptrace 2 ,
+.Xr sigaction 2 ,
+.Xr exit 3 ,
+.Xr siginfo 3
+.Sh STANDARDS
+The
+.Fn wait ,
+.Fn waitpid ,
+and
+.Fn waitid
+functions are defined by POSIX;
+.Fn wait6 ,
+.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 HISTORY
+The
+.Fn wait
+function appeared in
+.At v6 .