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