 @@ -1,662 +1,662 @@
-.\"	$NetBSD: wait.2,v 1.39 2016/11/20 09:38:37 wiz Exp $
+.\"	$NetBSD: wait.2,v 1.40 2019/09/02 00:12:11 sevan Exp $
 .\"
 .\" 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.
 .\" 3. 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
 .\"
-.Dd November 10, 2016
+.Dd September 2, 2019
 .Dt WAIT 2
 .Os
 .Sh NAME
 .Nm wait ,
 .Nm waitid ,
 .Nm waitpid ,
 .Nm wait6 ,
 .Nm wait4 ,
 .Nm wait3
 .Nd wait for process termination
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In sys/wait.h
 .Ft pid_t
 .Fn wait "int *status"
 .Ft pid_t
 .Fn waitpid "pid_t wpid" "int *status" "int options"
 .Ft int
 .Fn waitid "idtype_t idtype" "id_t id" "siginfo_t *info" "int options"
 .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.
 .Pp
 The
 .Fn wait4
 and
 .Fn wait6
 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 .
 or
 .Fn wait6 .
 .Pp
 The
 .Fn wait6
 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
 functions all implicitly wait for exited and trapped processes,
 but the
 .Fn waitid
 and
 .Fn wait6
 functions require the corresponding
 .Dv WEXITED
 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
 .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
 .Dv NULL
 or a pointer to a
 .Fa siginfo_t
 structure.
 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 .
 The separate
 .Fa idtype
 and
 .Fa id
 arguments support many other types of
 identifiers in addition to process IDs and process group IDs.
 .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 identifier types supported by this
 implementation of
 .Fn waitid
 and
 .Fn wait6
 are:
 .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 the
 .Fn waitpid
 and
 .Fn wait4
 functions, the single
 .Fa wpid
 argument specifies the set of child processes for which to wait.
 The following symbolic constants are defined in
 .In sys/wait.h
 .Bd -literal -offset indent
 #define WAIT_ANY        (-1)    /* any process */
 #define WAIT_MYPGRP     0       /* any process in my process group */
 .Ed
 .Bl -bullet -offset indent
 .It
 If
 .Fa wpid
 is
 .Dv WAIT_ANY ,
 the call waits for any child process.
 .It
 If
 .Fa wpid
 is
 .Dv WAIT_MYPGRP ,
 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 WCONTINUED
 .It Dv WALLSIG
 If this option is specified, the call will wait for all children regardless
 of what exit signal they post.
 .It Dv WALTSIG
 If this option is specified, the call will wait only for processes that
 are configured to post a signal other than
 .Dv SIGCHLD
 when they exit.
 If
 .Dv WALTSIG
 is not specified, the call will wait only for processes that
 are configured to post
 .Dv SIGCHLD .
 .It Dv WCONTINUED
 Report the status of selected processes that
 have continued from a job control stop by receiving a
 .Dv SIGCONT
 signal.
 .It Dv WEXITED
 Report the status of selected processes which have terminated.
 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 terminated processes are expected.
 .It Dv WNOHANG
 Do not block when
 there are no processes wishing to report status.
 .It Dv WNOWAIT
 Keep the process whose status is returned in a waitable state.
 The process may be waited for again after this call completes.
 .It Dv WNOZOMBIE
 Exclude zombie processes from the child selection criteria.
 .It Dv WSTOPPED
 An alias for
 .Dv WUNTRACED .
 .It Dv WTRAPPED
 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 WUNTRACED
 Report the status of selected processes which are stopped due to a
 .Dv SIGTTIN , SIGTTOU , SIGTSTP ,
 or
 .Dv SIGSTOP
 signal.
 .It Dv __WALL
 This is an alias for
 .Dv WALLSIG .
 It is provided for compatibility with the Linux
 .Xr clone 2
 API .
 .It Dv __WCLONE
 This is an alias for
 .Dv WALTSIG .
 It is provided for compatibility with the Linux
 .Xr clone 2
 API.
 .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
 .Pf non- Dv NULL ,
 a summary of the resources used by the terminated
 process and all its children is returned.
 .Pp
 If
 .Fa wrusage
 is
 .Pf non- Dv 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
 .Pf non- Dv NULL ,
+a
 .Dv siginfo_t
 structure is returned with the
 .Fa si_signo
 field set to
 .Dv SIGCHLD
 and the
 .Fa si_pid
 field set to the process ID of the process reporting status.
 For the exited process, the
 .Fa si_status
 field of the
 .Dv siginfo_t
 structure contains the full 32 bit exit status passed to
 .Xr _exit 2 ;
 the
 .Fa status
 argument of other calls only returns 8 lowest bits of the exit status.
 .Pp
 When the
 .Dv WNOHANG
 option is specified and no processes
 wish to report status,
 .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
 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.
 Note that these macros expect the
 .Fa status
 value itself, not a pointer to the
 .Fa status
 value.
 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 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 ) .
 .It Fn WIFCONTINUED status
 True if the process has not terminated, but has been continued via the
 delivery of the
 .Dv SIGCONT
 signal.
 This macro can be true only if the wait call specified the
 .Dv WCONTINUED
 option.
 .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 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 siginterrupt 3 .
 .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 wait6 ,
 .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.
 .Pp
 If
 .Fn waitid
 returns because one or more processes have a state change to report,
 is returned.
 If an error is detected,
 a value of -1
 is returned and
 .Va errno
 is set to indicate the error.
 If
 .Dv WNOHANG
 is specified and there are
 no stopped, continued or exited children,
 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
 .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; or
 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
 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
 .Pp
 In addition,
 .Fn wait6 ,
 .Fn wait3 ,
 .Fn wait4 ,
 .Fn waitid ,
 and
 .Fn waitpid
 will fail and return immediately if:
 .Bl -tag -width Er
 .It Bq Er EINVAL
 An invalid value was specified for
 .Fa options .
 .El
 .Sh SEE ALSO
 .Xr _exit 2 ,
 .Xr fork 2 ,
 .Xr ptrace 2 ,
 .Xr sigaction 2 ,
 .Xr siginfo 2 ,
 .Xr exit 3 ,
 .Xr siginterrupt 3
 .Sh STANDARDS
 The
 .Fn wait
 and
 .Fn waitpid
 functions conform to
 .St -p1003.1-90 ;
 the
 .Fn waitid
 function conforms to
 .St -p1003.1-2004 ;
 the
 .Fn wait3
 function conforms to
 .St -xpg4 ;
 .Fn wait4
 is an extension.
 The
 .Fn WCOREDUMP
 macro
 and the ability to restart a pending
 .Fn wait
 call are extensions to the POSIX interface.
 .Sh HISTORY
+A
 .Fn wait
 function call appeared in
-.At v2 .
+.At v1 .