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