xref: /dragonfly/usr.sbin/iostat/iostat.8 (revision 6bd457ed) 
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.3 2004/12/22 11:01:49 joerg 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 h
114Put
115.Nm
116in
117.Sq top
118mode.
119In this mode,
120.Nm
121will show devices in order from highest to lowest bytes
122per measurement cycle.
123.It Fl I
124Display total statistics for a given time period, rather than average
125statistics for each second during that time period.
126.It Fl K
127In the blocks transferred display (-o), display block count in kilobytes rather
128then the device native block size.
129.It Fl n
130Display up to
131.Ar devs
132number of devices.
133.Nm
134will display fewer devices if there aren't
135.Ar devs
136devices present.
137.It Fl o
138Display old-style
139.Nm
140device statistics.
141Sectors per second, transfers per second, and milliseconds per seek are
142displayed.
143If
144.Fl I
145is specified, total blocks/sectors, total transfers, and
146milliseconds per seek are displayed.
147.It Fl t
148Specify which types of devices to display.
149There are three different categories of devices:
150.Pp
151.Bl -tag -width indent -compact
152.It device type:
153.Bl -tag -width 9n -compact
154.It da
155Direct Access devices
156.It sa
157Sequential Access devices
158.It printer
159Printers
160.It proc
161Processor devices
162.It worm
163Write Once Read Multiple devices
164.It cd
165CD devices
166.It scanner
167Scanner devices
168.It optical
169Optical Memory devices
170.It changer
171Medium Changer devices
172.It comm
173Communication devices
174.It array
175Storage Array devices
176.It enclosure
177Enclosure Services devices
178.It floppy
179Floppy devices
180.El
181.Pp
182.It interface:
183.Bl -tag -width 9n -compact
184.It IDE
185Integrated Drive Electronics devices
186.It SCSI
187Small Computer System Interface devices
188.It other
189Any other device interface
190.El
191.Pp
192.It passthrough:
193.Bl -tag -width 9n -compact
194.It pass
195Passthrough devices
196.El
197.El
198.Pp
199The user must specify at least one device type, and may specify at most
200one device type from each category.
201Multiple device types in a single device type statement must be separated by
202commas.
203.Pp
204Any number of
205.Fl t
206arguments may be specified on the command line.
207All
208.Fl t
209arguments are ORed together to form a matching expression against which
210all devices in the system are compared.
211Any device that fully matches any
212.Fl t
213argument will be included in the
214.Nm
215output, up to the number of devices that can be displayed in
21680 columns, or the maximum number of devices specified by the user.
217.It Fl T
218Display TTY statistics.
219This is on by default, unless
220.Fl d
221is specified.
222.It Fl w
223Pause
224.Ar wait
225seconds between each display.
226If no repeat
227.Ar count
228is specified, the default is infinity.
229.It Fl ?\&
230Display a usage statement and exit.
231.El
232.Pp
233.Nm Iostat
234displays its information in the following format:
235.Bl -tag -width flag
236.It tty
237.Bl -tag -width indent -compact
238.It tin
239characters read from terminals
240.It tout
241characters written to terminals
242.El
243.It devices
244Device operations.
245The header of the field is the device name and unit number.
246.Nm
247will display as many devices as will fit in a standard 80 column screen, or
248the maximum number of devices in the system, whichever is smaller.
249If
250.Fl n
251is specified on the command line,
252.Nm
253will display the smaller of the
254requested number of devices, and the maximum number of devices in the system.
255To force
256.Nm
257to display specific drives, their names may be supplied on the command
258line.
259.Nm
260will not display more devices than will fit in an 80 column screen, unless
261the
262.Fl n
263argument is given on the command line to specify a maximum number of
264devices to display.
265If fewer devices are specified on the command line than will fit in an 80
266column screen,
267.Nm
268will show only the specified devices.
269.Pp
270The standard
271.Nm
272device display shows the following statistics:
273.Pp
274.Bl -tag -width indent -compact
275.It KB/t
276kilobytes per transfer
277.It tps
278transfers per second
279.It MB/s
280megabytes per second
281.El
282.Pp
283The standard
284.Nm
285device display, with the
286.Fl I
287flag specified, shows the following statistics:
288.Pp
289.Bl -tag -width indent -compact
290.It KB/t
291kilobytes per transfer
292.It xfrs
293total number of transfers
294.It MB
295total number of megabytes transferred
296.El
297.Pp
298The old-style
299.Nm
300display (using
301.Fl o )
302shows the following statistics:
303.Pp
304.Bl -tag -width indent -compact
305.It sps
306sectors transferred per second
307.It tps
308transfers per second
309.It msps
310average milliseconds per transaction
311.El
312.Pp
313The old-style
314.Nm
315display, with the
316.Fl I
317flag specified, shows the following statistics:
318.Pp
319.Bl -tag -width indent -compact
320.It blk
321total blocks/sectors transferred
322.It xfr
323total transfers
324.It msps
325average milliseconds per transaction
326.El
327.It cpu
328.Bl -tag -width indent -compact
329.It \&us
330% of cpu time in user mode
331.It \&ni
332% of cpu time in user mode running niced processes
333.It \&sy
334% of cpu time in system mode
335.It \&in
336% of cpu time in interrupt mode
337.It \&id
338% of cpu time in idle mode
339.El
340.El
341.Sh EXAMPLES
342.Dl iostat -w 1 da0 da1 cd0
343.Pp
344Display statistics for the first two Direct Access devices and the first
345CDROM device every second ad infinitum.
346.Pp
347.Dl iostat -c 2
348.Pp
349Display the statistics for the first four devices in the system twice, with
350a one second display interval.
351.Pp
352.Dl iostat -t da -t cd -w 1
353.Pp
354Display statistics for all CDROM and Direct Access devices every second
355ad infinitum.
356.Pp
357.Dl iostat -t da,scsi,pass -t cd,scsi,pass
358.Pp
359Display statistics once for all SCSI passthrough devices that provide access
360to either Direct Access or CDROM devices.
361.Pp
362.Dl iostat -h -n 8 -w 1
363.Pp
364Display up to 8 devices with the most I/O every second ad infinitum.
365.Pp
366.Dl iostat -dh -t da -w 1
367.Pp
368Omit the TTY and CPU displays, show devices in order of performance and
369show only Direct Access devices every second ad infinitum.
370.Pp
371.Dl iostat -Iw 3
372.Pp
373Display total statistics every three seconds ad infinitum.
374.Pp
375.Dl iostat -odICTw 2 -c 9
376.Pp
377Display total statistics using the old-style output format 9 times, with
378a two second interval between each measurement/display.
379The
380.Fl d
381flag generally disables the TTY and CPU displays, but since the
382.Fl T
383and
384.Fl C
385flags are given, the TTY and CPU displays will be displayed.
386.Sh SEE ALSO
387.Xr fstat 1 ,
388.Xr netstat 1 ,
389.Xr nfsstat 1 ,
390.Xr ps 1 ,
391.Xr systat 1 ,
392.Xr pstat 8 ,
393.Xr vmstat 8
394.Pp
395The sections starting with ``Interpreting system activity'' in
396.%T "Installing and Operating 4.3BSD" .
397.Sh HISTORY
398This version of
399.Nm
400first appeared in
401.Fx 3.0 .
402.Sh AUTHORS
403.An Kenneth Merry Aq ken@FreeBSD.org
404