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> References: <201309121643.46422.jhb@freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
--xFkczX7rH1pKA3aV
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
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=20
> wait6() and idtypes. I did also change two other places to use uppercase=
for=20
> ID since that seems to be what we do in other pages. The alternate rende=
red=20
> text is below followed by the diff. One structural change I chose to mak=
e was=20
> using a tagged list for the non-standard idtypes. Our manpages in genera=
l=20
> prefer tagged lists to bullet lists for enumerations. I left the list of=
=20
> standard types as-is as it includes a fourth bullet point that would not =
have=20
> an associated tag (though one could perhaps move that into the paragraph=
=20
> 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=
=20
> attempt to be more consisent with existing paragraphs, etc.:
>=20
> The broadest interface of all functions in this family is wait6() wh=
ich
> is otherwise very much like wait4() but with a few very important di=
s-
> tinctions. To wait for exited processes the option flag WEXITED mus=
t 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 ar=
gu-
> ment, the wrusage arguments points to a structure defined as:
>=20
> struct __wrusage {
> struct rusage wru_self;
> struct rusage wru_children;
> };
>=20
> 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 struc=
ture.
> If non-NULL, the structure is filled with the same data as for a SIG=
CHLD
> signal delivered when the process changed state.
>=20
> The set of child processes to be queried is specified by the argumen=
ts
> idtype and id. The separate idtype and id arguments support many ot=
her
> types of identifers in addition to process IDs and process group IDs.
>=20
> o If idtype is P_PID, waitid() and wait6() wait for the child
> process with a process ID equal to (pid_t)id.
>=20
> o If idtype is P_PGID, waitid() and wait6() wait for the chi=
ld
> process with a process group ID equal to (pid_t)id.
>=20
> o If idtype is P_ALL, waitid() and wait6() wait for any child
> process and the id is ignored.
>=20
> 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 gro=
up as
> the caller.
>=20
> Non-standard identifier types supported by this implementation of
> waitid() and wait6() are:
>=20
> P_UID Wait for processes whose effective user ID is equal to (ui=
d_t)
> id.
>=20
> P_GID Wait for processes whose effective group ID is equal to (g=
id_t)
> id.
>=20
> 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.
>=20
> P_JAILID Waits for processes within a jail whose jail identifier is
> equal to id.
>=20
> For the wait(), wait3(), and wait4() functions, the single wpid argu=
ment
> specifies the set of child processes for which to wait.
>=20
> o If wpid is -1, the call waits for any child process.
>=20
> o If wpid is 0, the call waits for any child process in the
> process group of the caller.
>=20
> o If wpid is greater than zero, the call waits for the proce=
ss
> with process ID wpid.
>=20
> o If wpid is less than -1, the call waits for any process wh=
ose
> process group ID equals the absolute value of wpid.
>=20
> ....
>=20
> If wrusage is non-NULL, separate summaries are returned for the reso=
urces
> used by the terminated process and the resources used by all its chi=
l-
> dren.
>=20
> 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 t=
he
> process reporting status.
>=20
> 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.
>=20
> When the WNOHANG option is specified and no processes wish to report=
sta-
> tus, wait4() and wait6() return a process id of 0.
>=20
> 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 val=
ue of
s/zero/NULL/ ?
> -1. The wait4() function is identical to wait6() with the flags WEX=
ITED
> and WTRAPPED set in options and infop set to NULL.
>=20
> ....
>=20
> 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.
>=20
> If SIGCHLD is blocked and wait() returns because the status of a chi=
ld
> process is available, the pending SIGCHLD signal will be cleared unl=
ess
> another status of the child process is available.
>=20
> ....
>=20
> If waitid() returns because one or more processes have a state chang=
e 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 spec=
ified
> and there are no stopped, continued or exited children, 0 is returne=
d.
> The si_signo and si_pid fields of infop must be checked against zero=
to
> determine if a process reported status.
--xFkczX7rH1pKA3aV
Content-Type: application/pgp-signature
-----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-----
--xFkczX7rH1pKA3aV--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20130914081144.GZ41229>