Tweaks to the wait(2) manpage
John Baldwin
jhb at freebsd.org
Thu Sep 12 21:10:25 UTC 2013
I have some tweaks to the wait(2) manpage, in particular to the sections on
wait6() and idtypes. I did also change two other places to use uppercase for
ID since that seems to be what we do in other pages. The alternate rendered
text is below followed by the diff. One structural change I chose to make was
using a tagged list for the non-standard idtypes. Our manpages in general
prefer tagged lists to bullet lists for enumerations. I left the list of
standard types as-is as it includes a fourth bullet point that would not have
an associated tag (though one could perhaps move that into the paragraph
introducing the list of standard types if a tagged list was desired). I kept
reading this page as I was writing this e-mail and changed more bits to
attempt to be more consisent with existing paragraphs, etc.:
The broadest interface of all functions in this family is wait6() which
is otherwise very much like wait4() but with a few very important dis-
tinctions. To wait for exited processes the option flag WEXITED must be
explicitly specified. This allows waiting for processes which have expe-
rienced other status changes without having to also handle the exit sta-
tus from terminated processes. Instead of the traditional rusage argu-
ment, the wrusage arguments points to a structure defined as:
struct __wrusage {
struct rusage wru_self;
struct rusage wru_children;
};
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 NULL. The last
argument infop must be either NULL or a pointer to a siginfo_t structure.
If non-NULL, the structure is filled with the same data as for a SIGCHLD
signal delivered when the process changed state.
The set of child processes to be queried is specified by the arguments
idtype and id. The separate idtype and id arguments support many other
types of identifers in addition to process IDs and process group IDs.
o If idtype is P_PID, waitid() and wait6() wait for the child
process with a process ID equal to (pid_t)id.
o If idtype is P_PGID, waitid() and wait6() wait for the child
process with a process group ID equal to (pid_t)id.
o If idtype is P_ALL, waitid() and wait6() wait for any child
process and the id is ignored.
o If idtype is P_PID or P_PGID and the id is zero, waitid() and
wait6() wait for any child process in the same process group as
the caller.
Non-standard identifier types supported by this implementation of
waitid() and wait6() are:
P_UID Wait for processes whose effective user ID is equal to (uid_t)
id.
P_GID Wait for processes whose effective group ID is equal to (gid_t)
id.
P_SID Wait for processes whose session ID is equal to id. 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.
P_JAILID Waits for processes within a jail whose jail identifier is
equal to id.
For the wait(), wait3(), and wait4() functions, the single wpid argument
specifies the set of child processes for which to wait.
o If wpid is -1, the call waits for any child process.
o If wpid is 0, the call waits for any child process in the
process group of the caller.
o If wpid is greater than zero, the call waits for the process
with process ID wpid.
o If wpid is less than -1, the call waits for any process whose
process group ID equals the absolute value of wpid.
....
If wrusage is non-NULL, separate summaries are returned for the resources
used by the terminated process and the resources used by all its chil-
dren.
If infop is non-NULL, a siginfo_t structure is returned with the si_signo
field set to SIGCHLD and the si_pid field set to the process ID of the
process reporting status.
When the WNOHANG option is specified and no processes wish to report sta-
tus, waitid() sets the si_signo and si_pid fields in infop to zero.
Checking these fields is the only way to know if a status change was
reported.
When the WNOHANG option is specified and no processes wish to report sta-
tus, wait4() and wait6() return a process id of 0.
The waitpid() function is identical to wait4() with an rusage value of
zero. The older wait3() call is the same as wait4() with a wpid value of
-1. The wait4() function is identical to wait6() with the flags WEXITED
and WTRAPPED set in options and infop set to NULL.
....
The implementation queues one SIGCHLD signal for each child process whose
status has changed; if 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
SIGCHLD signals remain pending.
If SIGCHLD is blocked and wait() returns because the status of a child
process is available, the pending SIGCHLD signal will be cleared unless
another status of the child process is available.
....
If 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 errno is set to indicate the error. If WNOHANG is specified
and there are no stopped, continued or exited children, 0 is returned.
The si_signo and si_pid fields of infop must be checked against zero to
determine if a process reported status.
Diff:
Index: wait.2
===================================================================
--- wait.2 (revision 255488)
+++ wait.2 (working copy)
@@ -99,15 +99,17 @@ The broadest interface of all functions in this fa
which is otherwise very much like
.Fn wait4
but with a few very important distinctions.
-To wait for exited processes, the option flag
+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.
+must 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.
Instead of the traditional
-.Dv rusage
-argument, a pointer to a new structure
+.Fa rusage
+argument, the
+.Fa wrusage
+arguments points to a structure defined as:
.Bd -literal
struct __wrusage {
struct rusage wru_self;
@@ -114,7 +116,7 @@ struct __wrusage {
struct rusage wru_children;
};
.Ed
-can be passed.
+.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
@@ -126,11 +128,13 @@ must be either
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
+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 .
@@ -138,8 +142,8 @@ The separate
.Fa idtype
and
.Fa id
-arguments allows to support many other types of
-IDs as well in addition to PID and PGID.
+arguments support many other types of
+identifers in addition to process IDs and process group IDs.
.Bl -bullet -offset indent
.It
If
@@ -188,48 +192,32 @@ and
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
+Non-standard identifier types supported by this
implementation of
.Fn waitid
and
-.Fn wait6 ,
+.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 .
+.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
+For the
.Fn wait ,
.Fn wait3 ,
and
@@ -250,12 +238,12 @@ the call waits for any child process in the proces
.It
If
.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 .
.It
If
.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
.Fa wpid .
.El
@@ -336,33 +324,34 @@ 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.
+is non-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 non-NULL, it must point to a
+is non-NULL, a
.Dv siginfo_t
-structure which is filled on return such that the
-.Dv si_signo
-field is always
+structure is returned with the
+.Fa si_signo
+field set to
.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
+and the
+.Fa si_pid
+field set to the process ID of the process reporting status.
+.Pp
+When 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
+option is specified and no processes
+wish to report status,
.Fn waitid
-is be zero as it is for any successful return from
-.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
@@ -369,7 +358,9 @@ When the
option is specified and no processes
wish to report status,
.Fn wait4
-returns a
+and
+.Fn wait6
+return a
process id
of 0.
.Pp
@@ -388,19 +379,19 @@ with a
.Fa wpid
value of -1.
The
+.Fn wait4
+function is identical to
.Fn wait6
-call, with the bits
+with the flags
.Dv WEXITED
and
.Dv WTRAPPED
-set in the
+set in
.Fa options
-and with
+and
.Fa infop
set to
-.Dv NULL ,
-is similar to
-.Fn wait4 .
+.Dv NULL .
.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:
@@ -481,7 +472,7 @@ in
The implementation queues one
.Dv SIGCHLD
signal for each child process whose
-status has changed, if
+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
@@ -492,7 +483,7 @@ signals remain pending.
.Pp
If
.Dv SIGCHLD
-is blocked,
+is blocked and
.Fn wait
returns because the status of a child process is available, the pending
.Dv SIGCHLD
@@ -538,13 +529,23 @@ 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 an error is detected,
+a value of -1
+is returned and
+.Va errno
+is set to indicate the error.
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.
+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
The
.Fn wait
--
John Baldwin
More information about the freebsd-doc
mailing list