From nobody@FreeBSD.org  Fri Dec 10 23:59:17 2010
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 64552106566C
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 10 Dec 2010 23:59:17 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from red.freebsd.org (unknown [IPv6:2001:4f8:fff6::22])
	by mx1.freebsd.org (Postfix) with ESMTP id 541AC8FC08
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 10 Dec 2010 23:59:17 +0000 (UTC)
Received: from red.freebsd.org (localhost [127.0.0.1])
	by red.freebsd.org (8.14.4/8.14.4) with ESMTP id oBANxHax027356
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 10 Dec 2010 23:59:17 GMT
	(envelope-from nobody@red.freebsd.org)
Received: (from nobody@localhost)
	by red.freebsd.org (8.14.4/8.14.4/Submit) id oBANxHIs027355;
	Fri, 10 Dec 2010 23:59:17 GMT
	(envelope-from nobody)
Message-Id: <201012102359.oBANxHIs027355@red.freebsd.org>
Date: Fri, 10 Dec 2010 23:59:17 GMT
From: Warren Block <wblock@wonkity.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: iostat(8) requires an argument to -c option
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         153012
>Category:       docs
>Synopsis:       [patch] iostat(8) requires an argument to -c option
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          analyzed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat Dec 11 00:00:19 UTC 2010
>Closed-Date:    
>Last-Modified:  Tue May 17 03:04:11 UTC 2011
>Originator:     Warren Block
>Release:        8.2-PRERELEASE
>Organization:
>Environment:
FreeBSD lightning 8.2-PRERELEASE FreeBSD 8.2-PRERELEASE #0: Mon Dec  6 08:56:09 MST 2010     root@lightning:/usr/obj/usr/src/sys/LIGHTNING  i386
>Description:
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
>Fix:


>Release-Note:
>Audit-Trail:

From: Alexander Best <arundel@freebsd.org>
To: bug-followup@freebsd.org
Cc:  
Subject: Re: bin/153012: iostat(8) requires an argument to -c option
Date: Sat, 11 Dec 2010 08:58:04 +0000

 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

From: Bruce Evans <brde@optusnet.com.au>
To: Warren Block <wblock@wonkity.com>
Cc: freebsd-gnats-submit@FreeBSD.org, freebsd-bugs@FreeBSD.org
Subject: Re: bin/153012: iostat(8) requires an argument to -c option
Date: Sat, 11 Dec 2010 21:23:19 +1100 (EST)

 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

From: Alexander Best <arundel@freebsd.org>
To: bug-followup@freebsd.org
Cc:  
Subject: Re: Re: bin/153012: iostat(8) requires an argument to -c option
Date: Tue, 14 Dec 2010 22:10:13 +0000

 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 
Responsible-Changed-By: arundel 
Responsible-Changed-When: Sun Dec 26 21:16:51 UTC 2010 
Responsible-Changed-Why:  
I'm working on fixing some iostat(8) manual page issues reported by Bruce Evans. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=153012 

From: Alexander Best <arundel@freebsd.org>
To: bug-followup@freebsd.org
Cc:  
Subject: Re: bin/153012: iostat(8) requires an argument to -c option
Date: Sun, 30 Jan 2011 16:34:49 +0000

 --X1bOJ3K7DJ5YkBrT
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 
 does the following patch solve the issues entirely?
 
 cheers.
 alex
 
 -- 
 a13x
 
 --X1bOJ3K7DJ5YkBrT
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: attachment; filename="iostat.8.diff"
 
 diff --git a/usr.sbin/iostat/iostat.8 b/usr.sbin/iostat/iostat.8
 index d8957ef..a69e499 100644
 --- a/usr.sbin/iostat/iostat.8
 +++ b/usr.sbin/iostat/iostat.8
 @@ -96,14 +96,18 @@ The options are as follows:
  Repeat the display
  .Ar count
  times.
 -If no repeat
 -.Ar count
 -is specified, the default depends on whether
 +If the
 +.Fl c
 +option has not been specified, the default behavior depends on whether
  .Fl w
 -is specified.
 -With
 +was specified.
 +With the
 +.Fl w
 +option set it is infinity; without the
  .Fl w
 -the default repeat count is infinity, otherwise it is 1.
 +option set
 +.Ar count
 +defaults to 1.
  .It Fl C
  Display CPU statistics.
  This is on by default, unless
 @@ -241,9 +245,9 @@ is specified.
  Pause
  .Ar wait
  seconds between each display.
 -If no
 -.Ar wait
 -interval is specified, the default is 1 second.
 +If the
 +.Fl w
 +option was not specified, the default interval is 1 second.
  .Pp
  The
  .Nm
 @@ -487,3 +491,14 @@ The use of
  as a debugging tool for crash dumps is probably limited because there is
  currently no way to get statistics that only cover the time immediately before
  the crash.
 +.Pp
 +The
 +.Ar drives
 +arguments get handed over to
 +.Fn isdigit .
 +If a non-zero value gets returned for the (N-1)-th and/or N-th argument,
 +.Nm
 +switches into an undocumented traditional syntax. This behavior collides with
 +the one documented in this manual page and prevents
 +.Nm
 +from operating on devices with an identifier composed only by a number.
 
 --X1bOJ3K7DJ5YkBrT--
Responsible-Changed-From-To: arundel->freebsd-doc 
Responsible-Changed-By: arundel 
Responsible-Changed-When: Tue Feb 8 13:36:53 UTC 2011 
Responsible-Changed-Why:  
Maybe by assigning this PR to freebsd-doc, it will get a bit more attention. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=153012 
Responsible-Changed-From-To: freebsd-doc->gjb 
Responsible-Changed-By: gjb 
Responsible-Changed-When: Thu Feb 10 13:06:05 UTC 2011 
Responsible-Changed-Why:  
I'll take a look at this. 


http://www.freebsd.org/cgi/query-pr.cgi?pr=153012 
State-Changed-From-To: open->analyzed 
State-Changed-By: arundel 
State-Changed-When: Thu Mar 24 20:01:27 UTC 2011 
State-Changed-Why:  
Problem has been analyzed and discussed thoroughly. A patch was submitted. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=153012 

From: Alexander Best <arundel@freebsd.org>
To: bug-followup@freebsd.org
Cc:  
Subject: Re: docs/153012: [patch] iostat(8) requires an argument to -c option
Date: Thu, 24 Mar 2011 20:01:17 +0000

 --EVF5PPMfhYS0aIcm
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 
 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
 
 --EVF5PPMfhYS0aIcm
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: attachment; filename="iostat.8.diff"
 
 diff --git a/usr.sbin/iostat/iostat.8 b/usr.sbin/iostat/iostat.8
 index d8957ef..dba10d9 100644
 --- a/usr.sbin/iostat/iostat.8
 +++ b/usr.sbin/iostat/iostat.8
 @@ -85,8 +85,13 @@ The
  utility displays kernel
  .Tn I/O
  statistics on terminal, device and cpu operations.
 -The first statistics that are printed are averaged over the system uptime.
 -To get information about the current activity, a suitable wait time should
 +The first statistics that are printed are averaged over the system uptime
 +(unless
 +.Fl I
 +is specified).
 +Any references to repetitions in this man page implicitly include the first
 +statistics output.
 +To get information about the ongoing activity, a suitable wait time should
  be specified, so that the subsequent sets of printed statistics will be
  averaged over that time.
  .Pp
 @@ -96,14 +101,14 @@ The options are as follows:
  Repeat the display
  .Ar count
  times.
 -If no repeat
 +If
  .Ar count
 -is specified, the default depends on whether
 -.Fl w
 -is specified.
 -With
 -.Fl w
 -the default repeat count is infinity, otherwise it is 1.
 +is not specified and a
 +.Ar wait
 +interval is specified, the default repeat count is infinity.
 +If no
 +.Ar wait
 +interval is specified, the default repeat count is 1.
  .It Fl C
  Display CPU statistics.
  This is on by default, unless
 @@ -132,7 +137,9 @@ per measurement cycle.
  Display total statistics for a given time period, rather than average
  statistics for each second during that time period.
  .It Fl K
 -In the blocks transferred display (-o), display block count in kilobytes rather
 +In the blocks transferred display
 +.Pq Fl o ,
 +display block count in kilobytes rather
  then the device native block size.
  .It Fl M
  Extract values associated with the name list from the specified core
 @@ -241,9 +248,9 @@ is specified.
  Pause
  .Ar wait
  seconds between each display.
 -If no
 +If
  .Ar wait
 -interval is specified, the default is 1 second.
 +is not specified, the default interval is 1 second.
  .Pp
  The
  .Nm
 @@ -487,3 +494,20 @@ The use of
  as a debugging tool for crash dumps is probably limited because there is
  currently no way to get statistics that only cover the time immediately before
  the crash.
 +.Pp
 +Each
 +.Ar drives
 +argument is passed to
 +.Fn isdigit .
 +If
 +.Fn isdigit
 +returns true,
 +.Nm
 +switches into an undocumented traditional syntax and subsequent arguments,
 +if any, will not be interpreted as drive names.
 +This behavior collides with the one documented in this man page and prevents
 +specifying drive names starting with a number.
 +E.g., the following
 +.Bd -literal -offset indent
 +iostat ada0 ada1 2 3 cd0
 +.Ed
 
 --EVF5PPMfhYS0aIcm--
Class-Changed-From-To: sw-bug->doc-bug 
Class-Changed-By: arundel 
Class-Changed-When: Fri Apr 1 09:35:42 UTC 2011 
Class-Changed-Why:  
sw-bug -> doc-bug 

http://www.freebsd.org/cgi/query-pr.cgi?pr=153012 

From: Alexander Best <arundel@freebsd.org>
To: bug-followup@freebsd.org
Cc:  
Subject: Re: docs/153012: [patch] iostat(8) requires an argument to -c option
Date: Fri, 1 Apr 2011 09:35:32 +0000

 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

From: Alexander Best <arundel@freebsd.org>
To: bug-followup@freebsd.org
Cc:  
Subject: Re: docs/153012: [patch] iostat(8) requires an argument to -c option
Date: Mon, 4 Apr 2011 19:25:06 +0000

 --OgqxwSJOaUobr8KG
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 
 this is the revised and hopefully final patch in order to fix the iostat(8) man
 page.
 
 cheers.
 alex
 
 -- 
 a13x
 
 --OgqxwSJOaUobr8KG
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: attachment; filename="iostat.8.diff"
 
 diff --git a/usr.sbin/iostat/iostat.8 b/usr.sbin/iostat/iostat.8
 index d8957ef..db96306 100644
 --- a/usr.sbin/iostat/iostat.8
 +++ b/usr.sbin/iostat/iostat.8
 @@ -56,7 +56,7 @@
  .\"
  .\"	@(#)iostat.8	8.1 (Berkeley) 6/6/93
  .\"
 -.Dd November 24, 2010
 +.Dd April 4, 2011
  .Dt IOSTAT 8
  .Os
  .Sh NAME
 @@ -69,8 +69,8 @@ statistics
  .Op Fl CdhIKoTxz?\&
  .Op Fl c Ar count
  .Op Fl M Ar core
 -.Op Fl n Ar devs
  .Op Fl N Ar system
 +.Op Fl n Ar devs
  .Oo
  .Fl t
  .Sm off
 @@ -85,8 +85,13 @@ The
  utility displays kernel
  .Tn I/O
  statistics on terminal, device and cpu operations.
 -The first statistics that are printed are averaged over the system uptime.
 -To get information about the current activity, a suitable wait time should
 +The first statistics that are printed are averaged over the system uptime
 +(unless
 +.Fl I
 +is specified).
 +Any references to repetitions in this man page implicitly include the first
 +statistics output.
 +To get information about the ongoing activity, a suitable wait time should
  be specified, so that the subsequent sets of printed statistics will be
  averaged over that time.
  .Pp
 @@ -96,14 +101,11 @@ The options are as follows:
  Repeat the display
  .Ar count
  times.
 -If no repeat
 -.Ar count
 -is specified, the default depends on whether
 -.Fl w
 -is specified.
 -With
 -.Fl w
 -the default repeat count is infinity, otherwise it is 1.
 +If
 +.Fl c
 +is not specified and a wait interval is specified,
 +the default repeat count is infinity.
 +If no wait interval is specified, the default repeat count is 1.
  .It Fl C
  Display CPU statistics.
  This is on by default, unless
 @@ -132,8 +134,9 @@ per measurement cycle.
  Display total statistics for a given time period, rather than average
  statistics for each second during that time period.
  .It Fl K
 -In the blocks transferred display (-o), display block count in kilobytes rather
 -then the device native block size.
 +In the blocks transferred display
 +.Pq Fl o ,
 +display block count in kilobytes rather than the device native block size.
  .It Fl M
  Extract values associated with the name list from the specified core
  instead of the default
 @@ -144,7 +147,7 @@ Display up to
  number of devices.
  The
  .Nm
 -utility will display fewer devices if there are not
 +utility will display fewer devices if there are less than
  .Ar devs
  devices present.
  .It Fl N
 @@ -215,7 +218,7 @@ Passthrough devices
  The user must specify at least one device type, and may specify at most
  one device type from each category.
  Multiple device types in a single device type statement must be separated by
 -commas.
 +commas and are ANDed together.
  .Pp
  Any number of
  .Fl t
 @@ -229,7 +232,9 @@ Any device that fully matches any
  argument will be included in the
  .Nm
  output, up to the number of devices that can be displayed in
 -80 columns, or the maximum number of devices specified by the user.
 +80 columns, or the maximum number of devices
 +.Pq Fl n
 +specified by the user.
  .It Fl T
  Display TTY statistics.
  This is on by default, unless
 @@ -241,9 +246,9 @@ is specified.
  Pause
  .Ar wait
  seconds between each display.
 -If no
 -.Ar wait
 -interval is specified, the default is 1 second.
 +If
 +.Fl w
 +is not specified, the default interval is 1 second.
  .Pp
  The
  .Nm
 @@ -345,9 +350,9 @@ total number of megabytes transferred
  .Pp
  The extended
  .Nm
 -device display, with the
 -.Fl x
 -flag specified, shows the following statistics:
 +device display
 +.Pq Fl x
 +shows the following statistics:
  .Pp
  .Bl -tag -width indent -compact
  .It r/s
 @@ -366,10 +371,35 @@ average duration of transactions, in milliseconds
  % of time the device had one or more outstanding transactions
  .El
  .Pp
 +The extended
 +.Nm
 +device display
 +.Pq Fl x ,
 +with the
 +.Fl I
 +flag specified, shows the following statistics:
 +.Pp
 +.Bl -tag -width indent -compact
 +.It r/i
 +total number of read operations
 +.It w/i
 +total number of write operations
 +.It kr/i
 +total number of kilobytes read
 +.It kw/i
 +total number of kilobytes written
 +.It qlen
 +transactions queue length
 +.It svc_t
 +average duration of transactions, in milliseconds
 +.It %b
 +% of time the device had one or more outstanding transactions
 +.El
 +.Pp
  The old-style
  .Nm
 -display (using
 -.Fl o )
 +device display
 +.Pq Fl o
  shows the following statistics:
  .Pp
  .Bl -tag -width indent -compact
 @@ -383,7 +413,9 @@ average milliseconds per transaction
  .Pp
  The old-style
  .Nm
 -display, with the
 +device display
 +.Pq Fl o ,
 +with the
  .Fl I
  flag specified, shows the following statistics:
  .Pp
 @@ -487,3 +519,24 @@ The use of
  as a debugging tool for crash dumps is probably limited because there is
  currently no way to get statistics that only cover the time immediately before
  the crash.
 +.Pp
 +Each
 +.Ar drives
 +argument is passed to
 +.Fn isdigit .
 +If
 +.Fn isdigit
 +returns true,
 +.Nm
 +switches into an undocumented traditional syntax and subsequent arguments,
 +if any, will not be interpreted as drive names.
 +This behavior collides with the one documented in this man page and prevents
 +specifying drive names starting with a number.
 +E.g., the following
 +.Bd -literal -offset indent
 +iostat ada0 ada1 2 3 cd0
 +.Ed
 +.Pp
 +This document's use of
 +.Dq device type
 +is misleading.
 
 --OgqxwSJOaUobr8KG--

From: Alexander Best <arundel@freebsd.org>
To: bug-followup@freebsd.org
Cc:  
Subject: Re: docs/153012: [patch] iostat(8) requires an argument to -c option
Date: Mon, 9 May 2011 20:50:02 +0000

 --a8Wt8u1KmwUX3Y2C
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 
 now here's the final final final patch. ;)
 
 -- 
 a13x
 
 --a8Wt8u1KmwUX3Y2C
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: attachment; filename="iostat.8.diff"
 
 diff --git a/usr.sbin/iostat/iostat.8 b/usr.sbin/iostat/iostat.8
 index d8957ef..f4d04b1 100644
 --- a/usr.sbin/iostat/iostat.8
 +++ b/usr.sbin/iostat/iostat.8
 @@ -56,7 +56,7 @@
  .\"
  .\"	@(#)iostat.8	8.1 (Berkeley) 6/6/93
  .\"
 -.Dd November 24, 2010
 +.Dd May 9, 2011
  .Dt IOSTAT 8
  .Os
  .Sh NAME
 @@ -69,8 +69,8 @@ statistics
  .Op Fl CdhIKoTxz?\&
  .Op Fl c Ar count
  .Op Fl M Ar core
 -.Op Fl n Ar devs
  .Op Fl N Ar system
 +.Op Fl n Ar devs
  .Oo
  .Fl t
  .Sm off
 @@ -85,8 +85,13 @@ The
  utility displays kernel
  .Tn I/O
  statistics on terminal, device and cpu operations.
 -The first statistics that are printed are averaged over the system uptime.
 -To get information about the current activity, a suitable wait time should
 +The first statistics that are printed are averaged over the system uptime
 +(unless
 +.Fl I
 +is specified).
 +Any references to repetitions in this man page implicitly include the first
 +statistics output.
 +To get information about the ongoing activity, a suitable wait time should
  be specified, so that the subsequent sets of printed statistics will be
  averaged over that time.
  .Pp
 @@ -96,14 +101,11 @@ The options are as follows:
  Repeat the display
  .Ar count
  times.
 -If no repeat
 -.Ar count
 -is specified, the default depends on whether
 -.Fl w
 -is specified.
 -With
 -.Fl w
 -the default repeat count is infinity, otherwise it is 1.
 +If
 +.Fl c
 +is not specified and a wait interval is specified,
 +the default repeat count is infinity.
 +If no wait interval is specified, the default repeat count is 1.
  .It Fl C
  Display CPU statistics.
  This is on by default, unless
 @@ -132,8 +134,11 @@ per measurement cycle.
  Display total statistics for a given time period, rather than average
  statistics for each second during that time period.
  .It Fl K
 -In the blocks transferred display (-o), display block count in kilobytes rather
 -then the device native block size.
 +In the old-style blocks transferred display
 +.Po Fl I
 +and
 +.Fl o Pc ,
 +display block count in kilobytes rather than the device native block size.
  .It Fl M
  Extract values associated with the name list from the specified core
  instead of the default
 @@ -144,7 +149,7 @@ Display up to
  number of devices.
  The
  .Nm
 -utility will display fewer devices if there are not
 +utility will display fewer devices if there are less than
  .Ar devs
  devices present.
  .It Fl N
 @@ -215,7 +220,7 @@ Passthrough devices
  The user must specify at least one device type, and may specify at most
  one device type from each category.
  Multiple device types in a single device type statement must be separated by
 -commas.
 +commas and are ANDed together.
  .Pp
  Any number of
  .Fl t
 @@ -229,7 +234,9 @@ Any device that fully matches any
  argument will be included in the
  .Nm
  output, up to the number of devices that can be displayed in
 -80 columns, or the maximum number of devices specified by the user.
 +80 columns, or the maximum number of devices
 +.Pq Fl n
 +specified by the user.
  .It Fl T
  Display TTY statistics.
  This is on by default, unless
 @@ -241,9 +248,9 @@ is specified.
  Pause
  .Ar wait
  seconds between each display.
 -If no
 -.Ar wait
 -interval is specified, the default is 1 second.
 +If
 +.Fl w
 +is not specified, the default interval is 1 second.
  .Pp
  The
  .Nm
 @@ -345,9 +352,9 @@ total number of megabytes transferred
  .Pp
  The extended
  .Nm
 -device display, with the
 -.Fl x
 -flag specified, shows the following statistics:
 +device display
 +.Pq Fl x
 +shows the following statistics:
  .Pp
  .Bl -tag -width indent -compact
  .It r/s
 @@ -366,10 +373,35 @@ average duration of transactions, in milliseconds
  % of time the device had one or more outstanding transactions
  .El
  .Pp
 +The extended
 +.Nm
 +device display
 +.Pq Fl x ,
 +with the
 +.Fl I
 +flag specified, shows the following statistics:
 +.Pp
 +.Bl -tag -width indent -compact
 +.It r/i
 +total number of read operations
 +.It w/i
 +total number of write operations
 +.It kr/i
 +total number of kilobytes read
 +.It kw/i
 +total number of kilobytes written
 +.It qlen
 +transactions queue length
 +.It svc_t
 +average duration of transactions, in milliseconds
 +.It %b
 +% of time the device had one or more outstanding transactions
 +.El
 +.Pp
  The old-style
  .Nm
 -display (using
 -.Fl o )
 +device display
 +.Pq Fl o
  shows the following statistics:
  .Pp
  .Bl -tag -width indent -compact
 @@ -383,7 +415,9 @@ average milliseconds per transaction
  .Pp
  The old-style
  .Nm
 -display, with the
 +device display
 +.Pq Fl o ,
 +with the
  .Fl I
  flag specified, shows the following statistics:
  .Pp
 @@ -395,6 +429,17 @@ total transfers
  .It msps
  average milliseconds per transaction
  .El
 +.Pp
 +If the
 +.Fl K
 +flag was also specified,
 +.Dq blk
 +shows the following statstics:
 +.Pp
 +.Bl -tag -width indent -compact
 +.It blk
 +total count in kilobytes transferred
 +.El
  .It cpu
  .Bl -tag -width indent -compact
  .It \&us
 @@ -487,3 +532,24 @@ The use of
  as a debugging tool for crash dumps is probably limited because there is
  currently no way to get statistics that only cover the time immediately before
  the crash.
 +.Pp
 +Each
 +.Ar drives
 +argument is passed to
 +.Fn isdigit .
 +If
 +.Fn isdigit
 +returns true,
 +.Nm
 +switches into an undocumented traditional syntax and subsequent arguments,
 +if any, will not be interpreted as drive names.
 +This behavior collides with the one documented in this man page and prevents
 +specifying drive names starting with a number.
 +E.g., the following
 +.Bd -literal -offset indent
 +iostat ada0 ada1 2 3 cd0
 +.Ed
 +.Pp
 +This document's use of
 +.Dq device type
 +is misleading.
 diff --git a/usr.sbin/iostat/iostat.c b/usr.sbin/iostat/iostat.c
 index 87099d9..c34103e 100644
 --- a/usr.sbin/iostat/iostat.c
 +++ b/usr.sbin/iostat/iostat.c
 @@ -159,7 +159,7 @@ usage(void)
  	 * but it is supported.
  	 */
  	fprintf(stderr, "usage: iostat [-CdhIKoTxz?] [-c count] [-M core]"
 -		" [-n devs] [-N system]\n"
 +		" [-N system] [-n devs]\n"
  		"\t      [-t type,if,pass] [-w wait] [drives]\n");
  }
  
 
 --a8Wt8u1KmwUX3Y2C--
Responsible-Changed-From-To: gjb->freebsd-doc 
Responsible-Changed-By: gjb 
Responsible-Changed-When: Tue May 17 03:03:35 UTC 2011 
Responsible-Changed-Why:  
Back to the pool for now due to lack of time for the next few weeks. 


http://www.freebsd.org/cgi/query-pr.cgi?pr=153012 
>Unformatted:
