diff options
Diffstat (limited to 'static/netbsd/man2/wait.2')
| -rw-r--r-- | static/netbsd/man2/wait.2 | 662 |
1 files changed, 662 insertions, 0 deletions
diff --git a/static/netbsd/man2/wait.2 b/static/netbsd/man2/wait.2 new file mode 100644 index 00000000..2933d017 --- /dev/null +++ b/static/netbsd/man2/wait.2 @@ -0,0 +1,662 @@ +.\" $NetBSD: wait.2,v 1.42 2022/12/04 11:25:09 uwe 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 October 17, 2022 +.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 +.Er 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 the 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, +0 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, +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 +.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 v1 . |