xref: /dragonfly/usr.sbin/iostat/iostat.8 (revision 8af44722) 
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.\"
30.\" Copyright (c) 1985, 1991, 1993
31.\"	The Regents of the University of California.  All rights reserved.
32.\"
33.\" Redistribution and use in source and binary forms, with or without
34.\" modification, are permitted provided that the following conditions
35.\" are met:
36.\" 1. Redistributions of source code must retain the above copyright
37.\"    notice, this list of conditions and the following disclaimer.
38.\" 2. Redistributions in binary form must reproduce the above copyright
39.\"    notice, this list of conditions and the following disclaimer in the
40.\"    documentation and/or other materials provided with the distribution.
41.\" 3. Neither the name of the University nor the names of its contributors
42.\"    may be used to endorse or promote products derived from this software
43.\"    without specific prior written permission.
44.\"
45.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
46.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
47.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
48.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
49.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
50.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
51.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
52.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
53.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
54.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
55.\" SUCH DAMAGE.
56.\"
57.\"	@(#)iostat.8	8.1 (Berkeley) 6/6/93
58.\"
59.Dd December 22, 1997
60.Dt IOSTAT 8
61.Os
62.Sh NAME
63.Nm iostat
64.Nd report
65.Tn I/O
66statistics
67.Sh SYNOPSIS
68.Nm
69.Op Fl CdhKIoT
70.Op Fl c Ar count
71.Op Fl n Ar devs
72.Oo
73.Fl t
74.Sm off
75.Ar type , if , pass
76.Sm on
77.Oc
78.Op Fl w Ar wait
79.Op Ar drives
80.Sh DESCRIPTION
81.Nm Iostat
82displays kernel
83.Tn I/O
84statistics on terminal, device and cpu
85operations.
86.Pp
87The options are as follows:
88.Bl -tag -width flag
89.It Fl c
90Repeat the display
91.Ar count
92times.
93If no
94.Ar wait
95interval is specified, the default is 1 second.
96.It Fl C
97Display CPU statistics.
98This is on by default, unless
99.Fl d
100is specified.
101.It Fl d
102Display only device statistics.
103If this flag is turned on, only device statistics will be displayed, unless
104.Fl C
105or
106.Fl T
107is also specified to enable the display of CPU or TTY statistics.
108.It Fl D
109Display more details.
110If this flag is turned on, details on read and write statistics will be
111displayed as MBw/s (Megabyte written per second), MBr/s (Megabyte read per second),
112rtps (read transactions per second) and wtps (write transactions per second).
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
216available columns (80 minimum), or the maximum number of devices specified
217by 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 available columns (80 minimum),
247or the 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 available columns (80 columns
260minimum), unless the
261.Fl n
262argument is given on the command line to specify a maximum number of
263devices to display.
264Fewer devices may be displayed.
265.Pp
266The standard
267.Nm
268device display shows the following statistics:
269.Pp
270.Bl -tag -width indent -compact
271.It KB/t
272kilobytes per transfer
273.It tps
274transfers per second
275.It MB/s
276megabytes per second
277.El
278.Pp
279The standard
280.Nm
281device display, with the
282.Fl I
283flag specified, shows the following statistics:
284.Pp
285.Bl -tag -width indent -compact
286.It KB/t
287kilobytes per transfer
288.It xfrs
289total number of transfers
290.It MB
291total number of megabytes transferred
292.El
293.Pp
294The old-style
295.Nm
296display (using
297.Fl o )
298shows the following statistics:
299.Pp
300.Bl -tag -width indent -compact
301.It sps
302sectors transferred per second
303.It tps
304transfers per second
305.It msps
306average milliseconds per transaction
307.El
308.Pp
309The old-style
310.Nm
311display, with the
312.Fl I
313flag specified, shows the following statistics:
314.Pp
315.Bl -tag -width indent -compact
316.It blk
317total blocks/sectors transferred
318.It xfr
319total transfers
320.It msps
321average milliseconds per transaction
322.El
323.It cpu
324.Bl -tag -width indent -compact
325.It \&us
326% of cpu time in user mode
327.It \&ni
328% of cpu time in user mode running niced processes
329.It \&sy
330% of cpu time in system mode
331.It \&in
332% of cpu time in interrupt mode
333.It \&id
334% of cpu time in idle mode
335.El
336.El
337.Sh EXAMPLES
338.Dl iostat -w 1 da0 da1 cd0
339.Pp
340Display statistics for the first two Direct Access devices and the first
341CDROM device every second ad infinitum.
342.Pp
343.Dl iostat -c 2
344.Pp
345Display the statistics for the first four devices in the system twice, with
346a one second display interval.
347.Pp
348.Dl iostat -t da -t cd -w 1
349.Pp
350Display statistics for all CDROM and Direct Access devices every second
351ad infinitum.
352.Pp
353.Dl iostat -t da,scsi,pass -t cd,scsi,pass
354.Pp
355Display statistics once for all SCSI passthrough devices that provide access
356to either Direct Access or CDROM devices.
357.Pp
358.Dl iostat -h -n 8 -w 1
359.Pp
360Display up to 8 devices with the most I/O every second ad infinitum.
361.Pp
362.Dl iostat -dh -t da -w 1
363.Pp
364Omit the TTY and CPU displays, show devices in order of performance and
365show only Direct Access devices every second ad infinitum.
366.Pp
367.Dl iostat -Iw 3
368.Pp
369Display total statistics every three seconds ad infinitum.
370.Pp
371.Dl iostat -odICTw 2 -c 9
372.Pp
373Display total statistics using the old-style output format 9 times, with
374a two second interval between each measurement/display.
375The
376.Fl d
377flag generally disables the TTY and CPU displays, but since the
378.Fl T
379and
380.Fl C
381flags are given, the TTY and CPU displays will be displayed.
382.Sh SEE ALSO
383.Xr fstat 1 ,
384.Xr netstat 1 ,
385.Xr nfsstat 1 ,
386.Xr ps 1 ,
387.Xr systat 1 ,
388.Xr pstat 8 ,
389.Xr vmstat 8
390.Pp
391The sections starting with ``Interpreting system activity'' in
392.%T "Installing and Operating 4.3BSD" .
393.Sh HISTORY
394This version of
395.Nm
396first appeared in
397.Fx 3.0 .
398.Sh AUTHORS
399.An Kenneth Merry Aq Mt ken@FreeBSD.org
400