Bug 153012 - [patch] iostat(8) requires an argument to -c option
Summary: [patch] iostat(8) requires an argument to -c option
Status: In Progress
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Only Me
Assignee: freebsd-bugs (Nobody)
URL:
Keywords: patch
Depends on:
Blocks:
 
Reported: 2010-12-11 00:00 UTC by Warren Block
Modified: 2018-08-05 06:50 UTC (History)
1 user (show)

See Also:


Attachments
iostat.8.diff (1.43 KB, patch)
2011-01-30 16:34 UTC, Alexander Best
no flags Details | Diff
iostat.8.diff (2.54 KB, patch)
2011-03-24 20:01 UTC, Alexander Best
no flags Details | Diff
iostat.8.diff (5.05 KB, patch)
2011-04-04 20:25 UTC, Alexander Best
no flags Details | Diff
iostat.8.diff (5.78 KB, patch)
2011-05-09 21:50 UTC, Alexander Best
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Warren Block 2010-12-11 00:00:19 UTC
iostat(8) says:

-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
Comment 1 Alexander Best freebsd_committer 2010-12-11 08:58:04 UTC
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.

cheers.
alex

-- 
a13x
Comment 2 Bruce Evans freebsd_committer 2010-12-11 10:23:19 UTC
On Fri, 10 Dec 2010, Warren Block wrote:

>> Description:
> 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
optional.

> 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".

Bruce
Comment 3 Alexander Best freebsd_committer 2010-12-14 22:10:13 UTC
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.

cheers.
alex

-- 
a13x
Comment 4 Alexander Best freebsd_committer 2010-12-26 21:16:51 UTC
Responsible Changed
From-To: freebsd-bugs->arundel

I'm working on fixing some iostat(8) manual page issues reported by Bruce Evans.
Comment 5 Alexander Best freebsd_committer 2011-01-30 16:34:49 UTC
does the following patch solve the issues entirely?

cheers.
alex

-- 
a13x
Comment 6 Alexander Best freebsd_committer 2011-02-08 13:36:53 UTC
Responsible Changed
From-To: arundel->freebsd-doc

Maybe by assigning this PR to freebsd-doc, it will get a bit more attention.
Comment 7 Glen Barber freebsd_committer 2011-02-10 13:06:05 UTC
Responsible Changed
From-To: freebsd-doc->gjb

I'll take a look at this.
Comment 8 Alexander Best freebsd_committer 2011-03-24 20:01:17 UTC
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@.

cheers.
alex
-- 
a13x
Comment 9 Alexander Best freebsd_committer 2011-03-24 20:01:27 UTC
State Changed
From-To: open->analyzed

Problem has been analyzed and discussed thoroughly. A patch was submitted.
Comment 10 Alexander Best freebsd_committer 2011-04-01 10:35:32 UTC
i've discovered several other issues in the iostat(8) man page. i'll submit a
new patch shortly. please disregard any previous patches.

cheers.
alex

-- 
a13x
Comment 11 Alexander Best freebsd_committer 2011-04-01 10:35:42 UTC
Class Changed
From-To: sw-bug->doc-bug

sw-bug -> doc-bug
Comment 12 Alexander Best freebsd_committer 2011-04-04 20:25:06 UTC
this is the revised and hopefully final patch in order to fix the iostat(8) man
page.

cheers.
alex

-- 
a13x
Comment 13 Alexander Best freebsd_committer 2011-05-09 21:50:02 UTC
now here's the final final final patch. ;)

-- 
a13x
Comment 14 Glen Barber freebsd_committer 2011-05-17 04:03:35 UTC
Responsible Changed
From-To: gjb->freebsd-doc

Back to the pool for now due to lack of time for the next few weeks.
Comment 15 Oleksandr Tymoshenko freebsd_committer freebsd_triage 2018-04-09 03:22:54 UTC
Moving to newly created component "Manual Pages"