d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
PR:		docs/183904
Submitted by:	Michael Galassi <michaelgalassi@gmail.com>
Reviewed by:	kib, wblock (earlier version)
This commit is contained in:
John Baldwin 2013-12-03 21:00:13 +00:00
parent b952cd584f
commit d4e3c0a2d7
1 changed files with 177 additions and 135 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

312
lib/libc/sys/wait.2
View File

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