On Thu, Sep 12, 2013 at 04:43:46PM -0400, John Baldwin wrote: > 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 I did not liked the introductory sentence above, but was not able to formulate the idea better. Specifically, I do not like the narrative tone, and think that 'broadest' and 'distinction' should be expressed better.
> 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
s/zero/NULL/ ?
> -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.
pgpdSg2m22biM.pgp
Description: PGP signature
