-c Repeat the display count times. If no repeat count is specified,
the default is infinity.
But if you try to run it without a repeat count:
% iostat -c
iostat: option requires an argument -- c
usage: iostat [-CdhIKoTxz?] [-c count] [-M core] [-n devs] [-N system]
[-t type,if,pass] [-w wait] [drives]
How-To-Repeat: %iostat -c
the wording might need to be changed. what this iostat(8) description actually
tries to document is that *not* using the -c switch implies -c 1.
On Fri, 10 Dec 2010, Warren Block wrote:
> iostat(8) says:
> -c Repeat the display count times. If no repeat count is specified,
> the default is infinity.
This used to be correct. It said "if no wait interval is specified, then
the default [for the wait interval] is 1 second". This was a bit confusing
since it didn't say that the default is for the wait interval. Now it is
just broken, since it is the -c option and not its repeat count that is
> But if you try to run it without a repeat count:
> % iostat -c
> iostat: option requires an argument -- c
> usage: iostat [-CdhIKoTxz?] [-c count] [-M core] [-n devs] [-N system]
> [-t type,if,pass] [-w wait] [drives]
The synopsis and usage message correctly specify that -c must have an arg.
The -w option has the complement of this breakage.
Either -w wait or the the normal way using the undocumented alias for this
("iostat wait", where `wait is a number') must be used to specifiy the wait
time for -c. Not documenting this may be intentional, but it became
especially broken when the `drives' option was added, since according to
the synopsis and usage message "iostat 1" says to give statistics for the
drive named "1", but it is actually an alias for "iostat -w 1".
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.
I'm working on fixing some iostat(8) manual page issues reported by Bruce Evans.
does the following patch solve the issues entirely?
Maybe by assigning this PR to freebsd-doc, it will get a bit more attention.
I'll take a look at this.
after a very thorough discussion with bde@ i think the following patch should
be alright to commit.
the iostat(8) man page can then pose as a draft for improving other *stat man
pages, such as vmstat(8) or systat(8) in the future.
also please note that specifying a repeat count requires "[-c count]" and *not*
"[-c | -c count]". hence the term "if no repeat count is specifyed" refers to a
situation where "-c count" wasn't used.
however i admit that finding the proper wording so no confusion will ever come
up is nearly impossible. the current patch tries to be as precise as possible,
yet still some cases and switches can be interpreted differently than what is
being implied by the man page.
thanks go out to bde@ and gjb@.
Problem has been analyzed and discussed thoroughly. A patch was submitted.
i've discovered several other issues in the iostat(8) man page. i'll submit a
new patch shortly. please disregard any previous patches.
sw-bug -> doc-bug
this is the revised and hopefully final patch in order to fix the iostat(8) man
now here's the final final final patch. ;)
Back to the pool for now due to lack of time for the next few weeks.
Moving to newly created component "Manual Pages"