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