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. 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 May 22, 2015 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 ms/r 364average duration of read transactions, in milliseconds 365.It ms/w 366average duration of write transactions, in milliseconds 367.It ms/o 368average duration of all other transactions, in milliseconds 369.It ms/t 370average duration of all transactions, in milliseconds 371.It %b 372% of time the device had one or more outstanding transactions 373.El 374.Pp 375The extended 376.Nm 377device display, with the 378.Fl x 379and 380.Fl I 381flags specified, shows the following statistics: 382.Pp 383.Bl -tag -width indent -compact 384.It r/i 385read operations per time period 386.It w/i 387write operations per time period 388.It kr/i 389kilobytes read per time period 390.It kw/i 391kilobytes write per time period 392.It qlen 393transactions queue length 394.It tsvc_t/i 395total duration of transactions per time period, in seconds 396.It sb/i 397total time the device had one or more outstanding transactions per 398time period, in seconds 399.El 400.Pp 401The old-style 402.Nm 403display (using 404.Fl o ) 405shows the following statistics: 406.Pp 407.Bl -tag -width indent -compact 408.It sps 409sectors transferred per second 410.It tps 411transfers per second 412.It msps 413average milliseconds per transaction 414.El 415.Pp 416The old-style 417.Nm 418display, with the 419.Fl I 420flag specified, shows the following statistics: 421.Pp 422.Bl -tag -width indent -compact 423.It blk 424total blocks/sectors transferred 425.It xfr 426total transfers 427.It msps 428average milliseconds per transaction 429.El 430.It cpu 431.Bl -tag -width indent -compact 432.It \&us 433% of cpu time in user mode 434.It \&ni 435% of cpu time in user mode running niced processes 436.It \&sy 437% of cpu time in system mode 438.It \&in 439% of cpu time in interrupt mode 440.It \&id 441% of cpu time in idle mode 442.El 443.El 444.Sh FILES 445.Bl -tag -width /boot/kernel/kernel -compact 446.It Pa /boot/kernel/kernel 447Default kernel namelist. 448.It Pa /dev/kmem 449Default memory file. 450.El 451.Sh EXAMPLES 452.Dl iostat -w 1 da0 da1 cd0 453.Pp 454Display statistics for the first two Direct Access devices and the first 455CDROM device every second ad infinitum. 456.Pp 457.Dl iostat -c 2 458.Pp 459Display the statistics for the first four devices in the system twice, with 460a one second display interval. 461.Pp 462.Dl iostat -t da -t cd -w 1 463.Pp 464Display statistics for all CDROM and Direct Access devices every second 465ad infinitum. 466.Pp 467.Dl iostat -t da,scsi,pass -t cd,scsi,pass 468.Pp 469Display statistics once for all SCSI passthrough devices that provide access 470to either Direct Access or CDROM devices. 471.Pp 472.Dl iostat -h -n 8 -w 1 473.Pp 474Display up to 8 devices with the most I/O every second ad infinitum. 475.Pp 476.Dl iostat -dh -t da -w 1 477.Pp 478Omit the TTY and CPU displays, show devices in order of performance and 479show only Direct Access devices every second ad infinitum. 480.Pp 481.Dl iostat -Iw 3 482.Pp 483Display total statistics every three seconds ad infinitum. 484.Pp 485.Dl iostat -odICTw 2 -c 9 486.Pp 487Display total statistics using the old-style output format 9 times, with 488a two second interval between each measurement/display. 489The 490.Fl d 491flag generally disables the TTY and CPU displays, but since the 492.Fl T 493and 494.Fl C 495flags are given, the TTY and CPU displays will be displayed. 496.Sh SEE ALSO 497.Xr fstat 1 , 498.Xr netstat 1 , 499.Xr nfsstat 1 , 500.Xr ps 1 , 501.Xr systat 1 , 502.Xr devstat 3 , 503.Xr ctlstat 8 , 504.Xr gstat 8 , 505.Xr pstat 8 , 506.Xr vmstat 8 507.Pp 508The sections starting with ``Interpreting system activity'' in 509.%T "Installing and Operating 4.3BSD" . 510.Sh HISTORY 511This version of 512.Nm 513first appeared in 514.Fx 3.0 . 515.Sh AUTHORS 516.An Kenneth Merry Aq Mt ken@FreeBSD.org 517.Sh BUGS 518The use of 519.Nm 520as a debugging tool for crash dumps is probably limited because there is 521currently no way to get statistics that only cover the time immediately before 522the crash. 523