Document wait6() and waitid().
PR: standards/170346 Submitted by: "Jukka A. Ukkonen" <jau@iki.fi> MFC after: 1 month
This commit is contained in:
parent
eb3d4e1fbd
commit
0b92b54045
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=242961
@ -217,5 +217,6 @@ MLINKS+=timer_settime.2 timer_getoverrun.2 timer_settime.2 timer_gettime.2
|
||||
MLINKS+=truncate.2 ftruncate.2
|
||||
MLINKS+=unlink.2 unlinkat.2
|
||||
MLINKS+=utimes.2 futimes.2 utimes.2 futimesat.2 utimes.2 lutimes.2
|
||||
MLINKS+=wait.2 wait3.2 wait.2 wait4.2 wait.2 waitpid.2
|
||||
MLINKS+=wait.2 wait3.2 wait.2 wait4.2 wait.2 waitpid.2 \
|
||||
wait.2 waitid.2 wait.2 wait6.2
|
||||
MLINKS+=write.2 pwrite.2 write.2 pwritev.2 write.2 writev.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.
|
||||
|
Loading…
Reference in New Issue
Block a user