xref: /dragonfly/usr.sbin/iostat/iostat.8 (revision 783d47c4) 
1.\"
2.\" Copyright (c) 1997 Kenneth D. Merry.
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\" 3. The name of the author may not be used to endorse or promote products
14.\"    derived from this software without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" $FreeBSD: src/usr.sbin/iostat/iostat.8,v 1.11.2.9 2002/12/29 16:35:41 schweikh Exp $
29.\" $DragonFly: src/usr.sbin/iostat/iostat.8,v 1.4 2005/09/01 19:08:38 swildner Exp $
30.\"
31.\" Copyright (c) 1985, 1991, 1993
32.\"	The Regents of the University of California.  All rights reserved.
33.\"
34.\" Redistribution and use in source and binary forms, with or without
35.\" modification, are permitted provided that the following conditions
36.\" are met:
37.\" 1. Redistributions of source code must retain the above copyright
38.\"    notice, this list of conditions and the following disclaimer.
39.\" 2. Redistributions in binary form must reproduce the above copyright
40.\"    notice, this list of conditions and the following disclaimer in the
41.\"    documentation and/or other materials provided with the distribution.
42.\" 3. All advertising materials mentioning features or use of this software
43.\"    must display the following acknowledgement:
44.\"	This product includes software developed by the University of
45.\"	California, Berkeley and its contributors.
46.\" 4. Neither the name of the University nor the names of its contributors
47.\"    may be used to endorse or promote products derived from this software
48.\"    without specific prior written permission.
49.\"
50.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
51.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
52.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
53.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
54.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
55.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
56.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
57.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
58.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
59.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
60.\" SUCH DAMAGE.
61.\"
62.\"	@(#)iostat.8	8.1 (Berkeley) 6/6/93
63.\"
64.Dd December 22, 1997
65.Dt IOSTAT 8
66.Os
67.Sh NAME
68.Nm iostat
69.Nd report
70.Tn I/O
71statistics
72.Sh SYNOPSIS
73.Nm
74.Op Fl CdhKIoT
75.Op Fl c Ar count
76.Op Fl n Ar devs
77.Oo
78.Fl t
79.Sm off
80.Ar type , if , pass
81.Sm on
82.Oc
83.Op Fl w Ar wait
84.Op Ar drives
85.Sh DESCRIPTION
86.Nm Iostat
87displays kernel
88.Tn I/O
89statistics on terminal, device and cpu
90operations.
91.Pp
92The options are as follows:
93.Bl -tag -width flag
94.It Fl c
95Repeat the display
96.Ar count
97times.
98If no
99.Ar wait
100interval is specified, the default is 1 second.
101.It Fl C
102Display CPU statistics.
103This is on by default, unless
104.Fl d
105is specified.
106.It Fl d
107Display only device statistics.
108If this flag is turned on, only device statistics will be displayed, unless
109.Fl C
110or
111.Fl T
112is also specified to enable the display of CPU or TTY statistics.
113.It Fl D
114Display more details.
115If this flag is turned on, details on read and write statistics will be
116displayed as MBw/s (Megabyte written per second), MBr/s (Megabyte read per second),
117rtps (read transactions per second) and wtps (write transactions per second).
118.It Fl h
119Put
120.Nm
121in
122.Sq top
123mode.
124In this mode,
125.Nm
126will show devices in order from highest to lowest bytes
127per measurement cycle.
128.It Fl I
129Display total statistics for a given time period, rather than average
130statistics for each second during that time period.
131.It Fl K
132In the blocks transferred display (-o), display block count in kilobytes rather
133then the device native block size.
134.It Fl n
135Display up to
136.Ar devs
137number of devices.
138.Nm
139will display fewer devices if there aren't
140.Ar devs
141devices present.
142.It Fl o
143Display old-style
144.Nm
145device statistics.
146Sectors per second, transfers per second, and milliseconds per seek are
147displayed.
148If
149.Fl I
150is specified, total blocks/sectors, total transfers, and
151milliseconds per seek are displayed.
152.It Fl t
153Specify which types of devices to display.
154There are three different categories of devices:
155.Pp
156.Bl -tag -width indent -compact
157.It device type:
158.Bl -tag -width 9n -compact
159.It da
160Direct Access devices
161.It sa
162Sequential Access devices
163.It printer
164Printers
165.It proc
166Processor devices
167.It worm
168Write Once Read Multiple devices
169.It cd
170CD devices
171.It scanner
172Scanner devices
173.It optical
174Optical Memory devices
175.It changer
176Medium Changer devices
177.It comm
178Communication devices
179.It array
180Storage Array devices
181.It enclosure
182Enclosure Services devices
183.It floppy
184Floppy devices
185.El
186.Pp
187.It interface:
188.Bl -tag -width 9n -compact
189.It IDE
190Integrated Drive Electronics devices
191.It SCSI
192Small Computer System Interface devices
193.It other
194Any other device interface
195.El
196.Pp
197.It passthrough:
198.Bl -tag -width 9n -compact
199.It pass
200Passthrough devices
201.El
202.El
203.Pp
204The user must specify at least one device type, and may specify at most
205one device type from each category.
206Multiple device types in a single device type statement must be separated by
207commas.
208.Pp
209Any number of
210.Fl t
211arguments may be specified on the command line.
212All
213.Fl t
214arguments are ORed together to form a matching expression against which
215all devices in the system are compared.
216Any device that fully matches any
217.Fl t
218argument will be included in the
219.Nm
220output, up to the number of devices that can be displayed in
22180 columns, or the maximum number of devices specified by the user.
222.It Fl T
223Display TTY statistics.
224This is on by default, unless
225.Fl d
226is specified.
227.It Fl w
228Pause
229.Ar wait
230seconds between each display.
231If no repeat
232.Ar count
233is specified, the default is infinity.
234.El
235.Pp
236.Nm Iostat
237displays its information in the following format:
238.Bl -tag -width flag
239.It tty
240.Bl -tag -width indent -compact
241.It tin
242characters read from terminals
243.It tout
244characters written to terminals
245.El
246.It devices
247Device operations.
248The header of the field is the device name and unit number.
249.Nm
250will display as many devices as will fit in a standard 80 column screen, or
251the maximum number of devices in the system, whichever is smaller.
252If
253.Fl n
254is specified on the command line,
255.Nm
256will display the smaller of the
257requested number of devices, and the maximum number of devices in the system.
258To force
259.Nm
260to display specific drives, their names may be supplied on the command
261line.
262.Nm
263will not display more devices than will fit in an 80 column screen, unless
264the
265.Fl n
266argument is given on the command line to specify a maximum number of
267devices to display.
268If fewer devices are specified on the command line than will fit in an 80
269column screen,
270.Nm
271will show only the specified devices.
272.Pp
273The standard
274.Nm
275device display shows the following statistics:
276.Pp
277.Bl -tag -width indent -compact
278.It KB/t
279kilobytes per transfer
280.It tps
281transfers per second
282.It MB/s
283megabytes per second
284.El
285.Pp
286The standard
287.Nm
288device display, with the
289.Fl I
290flag specified, shows the following statistics:
291.Pp
292.Bl -tag -width indent -compact
293.It KB/t
294kilobytes per transfer
295.It xfrs
296total number of transfers
297.It MB
298total number of megabytes transferred
299.El
300.Pp
301The old-style
302.Nm
303display (using
304.Fl o )
305shows the following statistics:
306.Pp
307.Bl -tag -width indent -compact
308.It sps
309sectors transferred per second
310.It tps
311transfers per second
312.It msps
313average milliseconds per transaction
314.El
315.Pp
316The old-style
317.Nm
318display, with the
319.Fl I
320flag specified, shows the following statistics:
321.Pp
322.Bl -tag -width indent -compact
323.It blk
324total blocks/sectors transferred
325.It xfr
326total transfers
327.It msps
328average milliseconds per transaction
329.El
330.It cpu
331.Bl -tag -width indent -compact
332.It \&us
333% of cpu time in user mode
334.It \&ni
335% of cpu time in user mode running niced processes
336.It \&sy
337% of cpu time in system mode
338.It \&in
339% of cpu time in interrupt mode
340.It \&id
341% of cpu time in idle mode
342.El
343.El
344.Sh EXAMPLES
345.Dl iostat -w 1 da0 da1 cd0
346.Pp
347Display statistics for the first two Direct Access devices and the first
348CDROM device every second ad infinitum.
349.Pp
350.Dl iostat -c 2
351.Pp
352Display the statistics for the first four devices in the system twice, with
353a one second display interval.
354.Pp
355.Dl iostat -t da -t cd -w 1
356.Pp
357Display statistics for all CDROM and Direct Access devices every second
358ad infinitum.
359.Pp
360.Dl iostat -t da,scsi,pass -t cd,scsi,pass
361.Pp
362Display statistics once for all SCSI passthrough devices that provide access
363to either Direct Access or CDROM devices.
364.Pp
365.Dl iostat -h -n 8 -w 1
366.Pp
367Display up to 8 devices with the most I/O every second ad infinitum.
368.Pp
369.Dl iostat -dh -t da -w 1
370.Pp
371Omit the TTY and CPU displays, show devices in order of performance and
372show only Direct Access devices every second ad infinitum.
373.Pp
374.Dl iostat -Iw 3
375.Pp
376Display total statistics every three seconds ad infinitum.
377.Pp
378.Dl iostat -odICTw 2 -c 9
379.Pp
380Display total statistics using the old-style output format 9 times, with
381a two second interval between each measurement/display.
382The
383.Fl d
384flag generally disables the TTY and CPU displays, but since the
385.Fl T
386and
387.Fl C
388flags are given, the TTY and CPU displays will be displayed.
389.Sh SEE ALSO
390.Xr fstat 1 ,
391.Xr netstat 1 ,
392.Xr nfsstat 1 ,
393.Xr ps 1 ,
394.Xr systat 1 ,
395.Xr pstat 8 ,
396.Xr vmstat 8
397.Pp
398The sections starting with ``Interpreting system activity'' in
399.%T "Installing and Operating 4.3BSD" .
400.Sh HISTORY
401This version of
402.Nm
403first appeared in
404.Fx 3.0 .
405.Sh AUTHORS
406.An Kenneth Merry Aq ken@FreeBSD.org
407