bin/153012: iostat(8) requires an argument to -c option

[Bruce Evans]

On Tue, 14 Dec 2010, Alexander Best wrote:

> how do you feel about the wording of the vmstat(8) manual? it would be possible
> to re-use it for the iostat(8) manual. of course just the -c and -w part.

It's even worse than in iostat(8), mainly due to it being more verbose and
having a similar density of bugs.

%      -c      Repeat the display count times.  The first display is for the
%              time since a reboot and each subsequent report is for the time
%              period since the last display.  If no repeat count is specified,
%              and -w is specified, the default is infinity, otherwise the
%              default is one.

[col -bx stripped the markup, so things like "display count times" are
ungrammatical here.]

"time" should probably be "time interval" or just "interval".

"a reboot" should "the system was booted".  I copied this wording from
systat(1).  The interval between the last reboot and this boot is not
covered as is claimed here, and more so for the interval between any
other reboot than the last one.

"repeat count" gives the same bug as in iostat.  It almost makes sense
in the above (you can read it as "the repeat count specified using -c
or in the normal undocumented way of putting it at the end after the
drives and the undocumented wait count at the end), but before col -bx
strips the markup, `count' is highlighted it can only refer to -c's
count arg.  But as stated in the PR, not specifying thsis count is
a syntax error.  This can be fixed by saying something like "-c option"
instead of "repeat count", but that is insufficient since the repeat
<unhighlighted>count can also be specified in the normal way without -c.

", otherwise" is a grammar error (comma splice).  It should be something
like "; otherwise," or ".  Otherwise,".

"one" is missing units (seconds) and should be spelled "1", giving
"1 second".

The normal syntax for the wait and count options is undocumented here
too.  It especially needs documentation since it is unusual.  It is
documented as "vmstat ... [drives] [wait [count]] in a comment in
iostat's usage() but not in vmstat's usage().  4.4BSD apparently tried
to kill this traditional syntax by putting it under BACKWARDS_COMPATIBILITY
ifdefs and removing it from man pages, but FreeBSD made its support
unconditional.  4.4BSD vmstat also has less-broken checking than 4.4BSD
iostat for counts and intervals of 0 (these should be allowed), but more-
broken for counts and intervals of < 0 (these should be disallowed).

% 
%      -w      Pause wait seconds between each display.  If no repeat wait
%              interval is specified, the default is 1 second.  The vmstat com-
%              mand will accept and honor a non-integer number of seconds.

"repeat wait interval" is even harder to parse than "repeat count",
especially when the markup of `wait' is restored.  It means the interval
between repetitions, which is the non-marked-up wait interval that may
be specified using -w or in the normal undocumented way.

This spells "1 second" correctly.

This is not as verbose as iostat(1) about the resolution and caveats
for "non-integer" numbers.  Neither says what the format of these
numbers is (it is any floating point format accepted by atof(3)).

This fails to specify the interaction of -w with -c.  This is not needed,
since the description of -c gives it.  However, -w is used more often than
-c, and the interaction starting with -w is simpler, so describing it here
too would be clearer.

Bruce