git: 502e8f44fcc1 - main - iostat.8: Better wording for some use cases

The branch main has been updated by gbe:

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(-)

diff --git a/usr.sbin/iostat/iostat.8 b/usr.sbin/iostat/iostat.8
index a08a62dc694d..a749b410d071 100644
--- a/usr.sbin/iostat/iostat.8
+++ b/usr.sbin/iostat/iostat.8
@@ -54,7 +54,7 @@
 .\"
 .\"	@(#)iostat.8	8.1 (Berkeley) 6/6/93
 .\"
-.Dd August 29, 2023
+.Dd November 26, 2023
 .Dt IOSTAT 8
 .Os
 .Sh NAME
@@ -83,7 +83,12 @@ 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.
+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 current activity, a suitable wait time should
 be specified, so that the subsequent sets of printed statistics will be
 averaged over that time.
@@ -101,14 +106,11 @@ is specified.
 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 d
 Display only device statistics.
 If this flag is turned on, only device statistics will be displayed, unless
@@ -130,8 +132,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
@@ -145,7 +150,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 o
@@ -222,7 +227,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
@@ -236,14 +241,16 @@ 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 w
 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
@@ -518,3 +525,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.