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 August 29, 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. 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 94Display CPU statistics. 95This is on by default, unless 96.Fl d 97or 98.Fl x 99is specified. 100.It Fl c 101Repeat the display 102.Ar count 103times. 104If no repeat 105.Ar count 106is specified, the default depends on whether 107.Fl w 108is specified. 109With 110.Fl w 111the default repeat count is infinity, otherwise it 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 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 140Extract the name list from the specified system instead of the default 141.Dq Pa /boot/kernel/kernel . 142.It Fl n 143Display up to 144.Ar devs 145number of devices. 146The 147.Nm 148utility will display fewer devices if there are not 149.Ar devs 150devices present. 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 162Display TTY statistics. 163This is on by default, unless 164.Fl d 165or 166.Fl x 167is specified. 168.It Fl t 169Specify which types of devices to display. 170There are three different categories of devices: 171.Pp 172.Bl -tag -width indent -compact 173.It device type: 174.Bl -tag -width 9n -compact 175.It da 176Direct Access devices 177.It sa 178Sequential Access devices 179.It printer 180Printers 181.It proc 182Processor devices 183.It worm 184Write Once Read Multiple devices 185.It cd 186CD devices 187.It scanner 188Scanner devices 189.It optical 190Optical Memory devices 191.It changer 192Medium Changer devices 193.It comm 194Communication devices 195.It array 196Storage Array devices 197.It enclosure 198Enclosure Services devices 199.It floppy 200Floppy devices 201.El 202.Pp 203.It interface: 204.Bl -tag -width 9n -compact 205.It IDE 206Integrated Drive Electronics devices 207.It SCSI 208Small Computer System Interface devices 209.It other 210Any other device interface 211.El 212.Pp 213.It passthrough: 214.Bl -tag -width 9n -compact 215.It pass 216Passthrough devices 217.El 218.El 219.Pp 220The user must specify at least one device type, and may specify at most 221one device type from each category. 222Multiple device types in a single device type statement must be separated by 223commas. 224.Pp 225Any number of 226.Fl t 227arguments may be specified on the command line. 228All 229.Fl t 230arguments are ORed together to form a matching expression against which 231all devices in the system are compared. 232Any device that fully matches any 233.Fl t 234argument will be included in the 235.Nm 236output, up to the number of devices that can be displayed in 23780 columns, or the maximum number of devices specified by the user. 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.El 271.Pp 272The 273.Nm 274utility displays its information in the following format: 275.Bl -tag -width flag 276.It tty 277.Bl -tag -width indent -compact 278.It tin 279characters read from terminals 280.It tout 281characters written to terminals 282.El 283.It devices 284Device operations. 285The header of the field is the device name and unit number. 286The 287.Nm 288utility 289will display as many devices as will fit in a standard 80 column screen, or 290the maximum number of devices in the system, whichever is smaller. 291If 292.Fl n 293is specified on the command line, 294.Nm 295will display the smaller of the 296requested number of devices, and the maximum number of devices in the system. 297To force 298.Nm 299to display specific drives, their names may be supplied on the command 300line. 301The 302.Nm 303utility 304will not display more devices than will fit in an 80 column screen, unless 305the 306.Fl n 307argument is given on the command line to specify a maximum number of 308devices to display. 309If fewer devices are specified on the command line than will fit in an 80 310column screen, 311.Nm 312will show only the specified devices. 313.Pp 314The standard 315.Nm 316device display shows the following statistics: 317.Pp 318.Bl -tag -width indent -compact 319.It KB/t 320kilobytes per transfer 321.It tps 322transfers per second 323.It MB/s 324megabytes per second 325.El 326.Pp 327The standard 328.Nm 329device display, with the 330.Fl I 331flag specified, shows the following statistics: 332.Pp 333.Bl -tag -width indent -compact 334.It KB/t 335kilobytes per transfer 336.It xfrs 337total number of transfers 338.It MB 339total number of megabytes transferred 340.El 341.Pp 342The extended 343.Nm 344device display, with the 345.Fl x 346flag specified, shows the following statistics: 347.Pp 348.Bl -tag -width indent -compact 349.It r/s 350read operations per second 351.It w/s 352write operations per second 353.It kr/s 354kilobytes read per second 355.It kw/s 356kilobytes write per second 357.It qlen 358transactions queue length 359.It ms/r 360average duration of read transactions, in milliseconds 361.It ms/w 362average duration of write transactions, in milliseconds 363.It ms/o 364average duration of all other transactions, in milliseconds 365.It ms/t 366average duration of all transactions, in milliseconds 367.It %b 368% of time the device had one or more outstanding transactions 369.El 370.Pp 371The extended 372.Nm 373device display, with the 374.Fl x 375and 376.Fl I 377flags specified, shows the following statistics: 378.Pp 379.Bl -tag -width indent -compact 380.It r/i 381read operations per time period 382.It w/i 383write operations per time period 384.It kr/i 385kilobytes read per time period 386.It kw/i 387kilobytes write per time period 388.It qlen 389transactions queue length 390.It tsvc_t/i 391total duration of transactions per time period, in seconds 392.It sb/i 393total time the device had one or more outstanding transactions per 394time period, in seconds 395.El 396.Pp 397The old-style 398.Nm 399display (using 400.Fl o ) 401shows the following statistics: 402.Pp 403.Bl -tag -width indent -compact 404.It sps 405sectors transferred per second 406.It tps 407transfers per second 408.It msps 409average milliseconds per transaction 410.El 411.Pp 412The old-style 413.Nm 414display, with the 415.Fl I 416flag specified, shows the following statistics: 417.Pp 418.Bl -tag -width indent -compact 419.It blk 420total blocks/sectors transferred 421.It xfr 422total transfers 423.It msps 424average milliseconds per transaction 425.El 426.It cpu 427.Bl -tag -width indent -compact 428.It \&us 429% of cpu time in user mode 430.It \&ni 431% of cpu time in user mode running niced processes 432.It \&sy 433% of cpu time in system mode 434.It \&in 435% of cpu time in interrupt mode 436.It \&id 437% of cpu time in idle mode 438.El 439.El 440.Sh FILES 441.Bl -tag -width /boot/kernel/kernel -compact 442.It Pa /boot/kernel/kernel 443Default kernel namelist. 444.It Pa /dev/kmem 445Default memory file. 446.El 447.Sh EXAMPLES 448.Dl iostat -w 1 da0 da1 cd0 449.Pp 450Display statistics for the first two Direct Access devices and the first 451CDROM device every second ad infinitum. 452.Pp 453.Dl iostat -c 2 454.Pp 455Display the statistics for the first four devices in the system twice, with 456a one second display interval. 457.Pp 458.Dl iostat -t da -t cd -w 1 459.Pp 460Display statistics for all CDROM and Direct Access devices every second 461ad infinitum. 462.Pp 463.Dl iostat -t da,scsi,pass -t cd,scsi,pass 464.Pp 465Display statistics once for all SCSI passthrough devices that provide access 466to either Direct Access or CDROM devices. 467.Pp 468.Dl iostat -h -n 8 -w 1 469.Pp 470Display up to 8 devices with the most I/O every second ad infinitum. 471.Pp 472.Dl iostat -dh -t da -w 1 473.Pp 474Omit the TTY and CPU displays, show devices in order of performance and 475show only Direct Access devices every second ad infinitum. 476.Pp 477.Dl iostat -Iw 3 478.Pp 479Display total statistics every three seconds ad infinitum. 480.Pp 481.Dl iostat -odICTw 2 -c 9 482.Pp 483Display total statistics using the old-style output format 9 times, with 484a two second interval between each measurement/display. 485The 486.Fl d 487flag generally disables the TTY and CPU displays, but since the 488.Fl T 489and 490.Fl C 491flags are given, the TTY and CPU displays will be displayed. 492.Sh SEE ALSO 493.Xr fstat 1 , 494.Xr netstat 1 , 495.Xr nfsstat 1 , 496.Xr ps 1 , 497.Xr systat 1 , 498.Xr devstat 3 , 499.Xr ctlstat 8 , 500.Xr gstat 8 , 501.Xr pstat 8 , 502.Xr vmstat 8 503.Pp 504The sections starting with ``Interpreting system activity'' in 505.%T "Installing and Operating 4.3BSD" . 506.Sh HISTORY 507This version of 508.Nm 509first appeared in 510.Fx 3.0 . 511.Sh AUTHORS 512.An Kenneth Merry Aq Mt ken@FreeBSD.org 513.Sh BUGS 514The use of 515.Nm 516as a debugging tool for crash dumps is probably limited because there is 517currently no way to get statistics that only cover the time immediately before 518the crash. 519