Attachment #111705 for bug #153012




.\"
.\"	@(#)iostat.8	8.1 (Berkeley) 6/6/93
.\"
.Dd April 4, 2011
.Dt IOSTAT 8
.Os
.Sh NAME

.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

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

Repeat the display
.Ar count
times.
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.
With
.Fl w
the default repeat count is infinity, otherwise it is 1.
.It Fl C
Display CPU statistics.
This is on by default, unless

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
.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

number of devices.
The
.Nm
utility will display fewer devices if there are less than
.Ar devs
devices present.
.It Fl N

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 and are ANDed together.
.Pp
Any number of
.Fl t

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
.Pq Fl n
specified by the user.
.It Fl T
Display TTY statistics.
This is on by default, unless

Pause
.Ar wait
seconds between each display.
If
.Fl w
is not specified, the default interval is 1 second.
.Pp
The
.Nm

.Pp
The extended
.Nm
device display
.Pq Fl x
shows the following statistics:
.Pp
.Bl -tag -width indent -compact
.It r/s

% 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
device display
.Pq Fl o
shows the following statistics:
.Pp
.Bl -tag -width indent -compact

.Pp
The old-style
.Nm
device display
.Pq Fl o ,
with the
.Fl I
flag specified, shows the following statistics:
.Pp

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.

Return to bug 153012

Lines 56-62 Link Here

(-)b/usr.sbin/iostat/iostat.8 (-26 / +79 lines)
56	.\"	56	.\"
57	.\" @(#)iostat.8 8.1 (Berkeley) 6/6/93	57	.\" @(#)iostat.8 8.1 (Berkeley) 6/6/93
58	.\"	58	.\"
59	.Dd November 24, 2010	59	.Dd April 4, 2011
60	.Dt IOSTAT 8	60	.Dt IOSTAT 8
61	.Os	61	.Os
62	.Sh NAME	62	.Sh NAME
Lines 69-76 statistics Link Here
69	.Op Fl CdhIKoTxz?\&	69	.Op Fl CdhIKoTxz?\&
70	.Op Fl c Ar count	70	.Op Fl c Ar count
71	.Op Fl M Ar core	71	.Op Fl M Ar core
72	.Op Fl n Ar devs
73	.Op Fl N Ar system	72	.Op Fl N Ar system
		73	.Op Fl n Ar devs
74	.Oo	74	.Oo
75	.Fl t	75	.Fl t
76	.Sm off	76	.Sm off
Lines 85-92 The Link Here
85	utility displays kernel	85	utility displays kernel
86	.Tn I/O	86	.Tn I/O
87	statistics on terminal, device and cpu operations.	87	statistics on terminal, device and cpu operations.
88	The first statistics that are printed are averaged over the system uptime.	88	The first statistics that are printed are averaged over the system uptime
89	To get information about the current activity, a suitable wait time should	89	(unless
		90	.Fl I
		91	is specified).
		92	Any references to repetitions in this man page implicitly include the first
		93	statistics output.
		94	To get information about the ongoing activity, a suitable wait time should
90	be specified, so that the subsequent sets of printed statistics will be	95	be specified, so that the subsequent sets of printed statistics will be
91	averaged over that time.	96	averaged over that time.
92	.Pp	97	.Pp
Lines 96-109 The options are as follows: Link Here
96	Repeat the display	101	Repeat the display
97	.Ar count	102	.Ar count
98	times.	103	times.
99	If no repeat	104	If
100	.Ar count	105	.Fl c
101	is specified, the default depends on whether	106	is not specified and a wait interval is specified,
102	.Fl w	107	the default repeat count is infinity.
103	is specified.	108	If no wait interval is specified, the default repeat count is 1.
104	With
105	.Fl w
106	the default repeat count is infinity, otherwise it is 1.
107	.It Fl C	109	.It Fl C
108	Display CPU statistics.	110	Display CPU statistics.
109	This is on by default, unless	111	This is on by default, unless
Lines 132-139 per measurement cycle. Link Here
132	Display total statistics for a given time period, rather than average	134	Display total statistics for a given time period, rather than average
133	statistics for each second during that time period.	135	statistics for each second during that time period.
134	.It Fl K	136	.It Fl K
135	In the blocks transferred display (-o), display block count in kilobytes rather	137	In the blocks transferred display
136	then the device native block size.	138	.Pq Fl o ,
		139	display block count in kilobytes rather than the device native block size.
137	.It Fl M	140	.It Fl M
138	Extract values associated with the name list from the specified core	141	Extract values associated with the name list from the specified core
139	instead of the default	142	instead of the default
Lines 144-150 Display up to Link Here
144	number of devices.	147	number of devices.
145	The	148	The
146	.Nm	149	.Nm
147	utility will display fewer devices if there are not	150	utility will display fewer devices if there are less than
148	.Ar devs	151	.Ar devs
149	devices present.	152	devices present.
150	.It Fl N	153	.It Fl N
Lines 215-221 Passthrough devices Link Here
215	The user must specify at least one device type, and may specify at most	218	The user must specify at least one device type, and may specify at most
216	one device type from each category.	219	one device type from each category.
217	Multiple device types in a single device type statement must be separated by	220	Multiple device types in a single device type statement must be separated by
218	commas.	221	commas and are ANDed together.
219	.Pp	222	.Pp
220	Any number of	223	Any number of
221	.Fl t	224	.Fl t
Lines 229-235 Any device that fully matches any Link Here
229	argument will be included in the	232	argument will be included in the
230	.Nm	233	.Nm
231	output, up to the number of devices that can be displayed in	234	output, up to the number of devices that can be displayed in
232	80 columns, or the maximum number of devices specified by the user.	235	80 columns, or the maximum number of devices
		236	.Pq Fl n
		237	specified by the user.
233	.It Fl T	238	.It Fl T
234	Display TTY statistics.	239	Display TTY statistics.
235	This is on by default, unless	240	This is on by default, unless
Lines 241-249 is specified. Link Here
241	Pause	246	Pause
242	.Ar wait	247	.Ar wait
243	seconds between each display.	248	seconds between each display.
244	If no	249	If
245	.Ar wait	250	.Fl w
246	interval is specified, the default is 1 second.	251	is not specified, the default interval is 1 second.
247	.Pp	252	.Pp
248	The	253	The
249	.Nm	254	.Nm
Lines 345-353 total number of megabytes transferred Link Here
345	.Pp	350	.Pp
346	The extended	351	The extended
347	.Nm	352	.Nm
348	device display, with the	353	device display
349	.Fl x	354	.Pq Fl x
350	flag specified, shows the following statistics:	355	shows the following statistics:
351	.Pp	356	.Pp
352	.Bl -tag -width indent -compact	357	.Bl -tag -width indent -compact
353	.It r/s	358	.It r/s
Lines 366-375 average duration of transactions, in milliseconds Link Here
366	% of time the device had one or more outstanding transactions	371	% of time the device had one or more outstanding transactions
367	.El	372	.El
368	.Pp	373	.Pp
		374	The extended
		375	.Nm
		376	device display
		377	.Pq Fl x ,
		378	with the
		379	.Fl I
		380	flag specified, shows the following statistics:
		381	.Pp
		382	.Bl -tag -width indent -compact
		383	.It r/i
		384	total number of read operations
		385	.It w/i
		386	total number of write operations
		387	.It kr/i
		388	total number of kilobytes read
		389	.It kw/i
		390	total number of kilobytes written
		391	.It qlen
		392	transactions queue length
		393	.It svc_t
		394	average duration of transactions, in milliseconds
		395	.It %b
		396	% of time the device had one or more outstanding transactions
		397	.El
		398	.Pp
369	The old-style	399	The old-style
370	.Nm	400	.Nm
371	display (using	401	device display
372	.Fl o )	402	.Pq Fl o
373	shows the following statistics:	403	shows the following statistics:
374	.Pp	404	.Pp
375	.Bl -tag -width indent -compact	405	.Bl -tag -width indent -compact
Lines 383-389 average milliseconds per transaction Link Here
383	.Pp	413	.Pp
384	The old-style	414	The old-style
385	.Nm	415	.Nm
386	display, with the	416	device display
		417	.Pq Fl o ,
		418	with the
387	.Fl I	419	.Fl I
388	flag specified, shows the following statistics:	420	flag specified, shows the following statistics:
389	.Pp	421	.Pp
Lines 487-489 The use of Link Here
487	as a debugging tool for crash dumps is probably limited because there is	519	as a debugging tool for crash dumps is probably limited because there is
488	currently no way to get statistics that only cover the time immediately before	520	currently no way to get statistics that only cover the time immediately before
489	the crash.	521	the crash.
		522	.Pp
		523	Each
		524	.Ar drives
		525	argument is passed to
		526	.Fn isdigit .
		527	If
		528	.Fn isdigit
		529	returns true,
		530	.Nm
		531	switches into an undocumented traditional syntax and subsequent arguments,
		532	if any, will not be interpreted as drive names.
		533	This behavior collides with the one documented in this man page and prevents
		534	specifying drive names starting with a number.
		535	E.g., the following
		536	.Bd -literal -offset indent
		537	iostat ada0 ada1 2 3 cd0
		538	.Ed
		539	.Pp
		540	This document's use of
		541	.Dq device type
		542	is misleading.