Tweaks to the wait(2) manpage

[Konstantin Belousov]

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.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 834 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20130914/52d947e3/attachment.sig>