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