Date: Wed, 15 Dec 2010 22:51:09 +1100 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Alexander Best <arundel@FreeBSD.org> Cc: freebsd-bugs@FreeBSD.org Subject: Re: Re: bin/153012: iostat(8) requires an argument to -c option Message-ID: <20101215215715.S1124@besplex.bde.org> In-Reply-To: <201012142220.oBEMKBxX089760@freefall.freebsd.org> References: <201012142220.oBEMKBxX089760@freefall.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20101215215715.S1124>