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