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