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