From owner-freebsd-bugs@FreeBSD.ORG Wed Dec 15 11:51:14 2010 Return-Path: Delivered-To: freebsd-bugs@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 4543A106566C; Wed, 15 Dec 2010 11:51:14 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from mail02.syd.optusnet.com.au (mail02.syd.optusnet.com.au [211.29.132.183]) by mx1.freebsd.org (Postfix) with ESMTP id D5ADD8FC17; Wed, 15 Dec 2010 11:51:13 +0000 (UTC) Received: from c211-30-187-99.carlnfd1.nsw.optusnet.com.au (c211-30-187-99.carlnfd1.nsw.optusnet.com.au [211.30.187.99]) by mail02.syd.optusnet.com.au (8.13.1/8.13.1) with ESMTP id oBFBp9GM004530 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Wed, 15 Dec 2010 22:51:11 +1100 Date: Wed, 15 Dec 2010 22:51:09 +1100 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Alexander Best In-Reply-To: <201012142220.oBEMKBxX089760@freefall.freebsd.org> Message-ID: <20101215215715.S1124@besplex.bde.org> References: <201012142220.oBEMKBxX089760@freefall.freebsd.org> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Cc: freebsd-bugs@FreeBSD.org Subject: Re: Re: bin/153012: iostat(8) requires an argument to -c option X-BeenThere: freebsd-bugs@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Bug reports List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 15 Dec 2010 11:51:14 -0000 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 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