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