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