Date: Sat, 14 Sep 2013 11:11:44 +0300 From: Konstantin Belousov <kostikbel@gmail.com> To: John Baldwin <jhb@freebsd.org> Cc: doc@freebsd.org Subject: Re: Tweaks to the wait(2) manpage Message-ID: <20130914081144.GZ41229@kib.kiev.ua> In-Reply-To: <201309121643.46422.jhb@freebsd.org>
index | next in thread | previous in thread | raw e-mail
[-- Attachment #1 --]
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.
[-- Attachment #2 --]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.21 (FreeBSD)
iQIcBAEBAgAGBQJSNBo/AAoJEJDCuSvBvK1BQ/MP+gNdpVfYwIaUPEHxz4fcNJui
Rkg7zC1xdA4Cb9AP9WswJkNyVFF7MoN6Zc+beCmuAM9cX6KzGyaampuruEp+Y4k+
KUra3yLPV+FaASbCtuKs48hiuGNQDP1WmsKP9Y0n30Fp4YBK8sqjbwTEycBmi35U
h8NzCEbpIgGNZ8VsxnvjsUbiIACsXpI4cWj+6papfPSnR+7kP4Piv4Oy7jIupZIZ
b4VKpv/WOVx88K7zNh4xF4eF402fEsfO0YcwZBX3XP3xGZyzODcdQgnBOnhfGSEf
hgTc02HYPwxcpCisMsnCilG1cRmohMpwXYe3WZisH4fttBE494yUnKNxue/1YckO
uIS6k8xuZH7RPxq3GE8sK18L3tbrOWBarToSQqBP1zIqUpOYb2EO+nsQICGI+xxG
xfLh1h9Ofy/a2NRE6KCAuMFZm3IETtZptE5wJ6zsYYiE4/ptj9iaCc5lbj9oW++E
vngAiTi/6JAkNfsKjJOBQOYcyQpYVVvQamCuJ4cy7F5GC11HX2q/6YL7ZTj0wsuh
pRX3Vd/RIfGHGx2HSiMnBCuBisuY81jy13YnaqoeUPiu5xmBlL30PAONfEqcPC6q
UamTVXWMAmBT5rYI+Uuw+fC92rLNK2OCJvAJH/5yai/OvmAEESX2bm6QLvcM1F2S
W7CL+59XQjrrbQT75397
=GZDk
-----END PGP SIGNATURE-----
home |
help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20130914081144.GZ41229>