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
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
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
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
Responsible Changed From-To: freebsd-bugs->arundel I'm working on fixing some iostat(8) manual page issues reported by Bruce Evans.
does the following patch solve the issues entirely? cheers. alex -- a13x
Responsible Changed From-To: arundel->freebsd-doc Maybe by assigning this PR to freebsd-doc, it will get a bit more attention.
Responsible Changed From-To: freebsd-doc->gjb 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@. cheers. alex -- a13x
State Changed From-To: open->analyzed 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. cheers. alex -- a13x
Class Changed From-To: sw-bug->doc-bug sw-bug -> doc-bug
this is the revised and hopefully final patch in order to fix the iostat(8) man page. cheers. alex -- a13x
now here's the final final final patch. ;) -- a13x
Responsible Changed From-To: gjb->freebsd-doc Back to the pool for now due to lack of time for the next few weeks.
Moving to newly created component "Manual Pages"
I created a differential for it, but the man page has been updated a while ago, so the patch is only included in partial.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=502e8f44fcc18bfc6dadca56801d66cbce4c07ec commit 502e8f44fcc18bfc6dadca56801d66cbce4c07ec Author: Gordon Bergling <gbe@FreeBSD.org> AuthorDate: 2023-11-26 18:30:58 +0000 Commit: Gordon Bergling <gbe@FreeBSD.org> CommitDate: 2023-11-26 18:30:58 +0000 iostat.8: Better wording for some use cases The iostat(8) manual page should be more specific when using options. Also extented the BUGS section. PR: 153012 Reviewed by: bcr MFC after: 1 week Differential Revision: https://reviews.freebsd.org/D42633 usr.sbin/iostat/iostat.8 | 64 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 18 deletions(-)
A commit in branch stable/14 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=9c452f50784f5dddc406508d57a5ed288493f78d commit 9c452f50784f5dddc406508d57a5ed288493f78d Author: Gordon Bergling <gbe@FreeBSD.org> AuthorDate: 2023-11-26 18:30:58 +0000 Commit: Gordon Bergling <gbe@FreeBSD.org> CommitDate: 2023-12-17 14:51:53 +0000 iostat.8: Better wording for some use cases The iostat(8) manual page should be more specific when using options. Also extented the BUGS section. PR: 153012 Reviewed by: bcr Differential Revision: https://reviews.freebsd.org/D42633 (cherry picked from commit 502e8f44fcc18bfc6dadca56801d66cbce4c07ec) usr.sbin/iostat/iostat.8 | 64 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 18 deletions(-)
A commit in branch stable/13 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=f5f993f6c9134530fbeac712589b3a6363a37286 commit f5f993f6c9134530fbeac712589b3a6363a37286 Author: Gordon Bergling <gbe@FreeBSD.org> AuthorDate: 2023-11-26 18:30:58 +0000 Commit: Gordon Bergling <gbe@FreeBSD.org> CommitDate: 2023-12-17 14:52:21 +0000 iostat.8: Better wording for some use cases The iostat(8) manual page should be more specific when using options. Also extented the BUGS section. PR: 153012 Reviewed by: bcr Differential Revision: https://reviews.freebsd.org/D42633 (cherry picked from commit 502e8f44fcc18bfc6dadca56801d66cbce4c07ec) usr.sbin/iostat/iostat.8 | 64 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 18 deletions(-)