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. All advertising materials mentioning features or use of this software 42.\" must display the following acknowledgement: 43.\" This product includes software developed by the University of 44.\" California, Berkeley and its contributors. 45.\" 4. Neither the name of the University nor the names of its contributors 46.\" may be used to endorse or promote products derived from this software 47.\" without specific prior written permission. 48.\" 49.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 50.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 51.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 52.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 53.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 54.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 55.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 56.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 57.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 58.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 59.\" SUCH DAMAGE. 60.\" 61.\" @(#)iostat.8 8.1 (Berkeley) 6/6/93 62.\" 63.Dd December 22, 1997 64.Dt IOSTAT 8 65.Os FreeBSD 3.0 66.Sh NAME 67.Nm iostat 68.Nd report 69.Tn I/O 70statistics 71.Sh SYNOPSIS 72.Nm iostat 73.Op Fl CdhKIoT? 74.Op Fl c Ar count 75.Op Fl M Ar core 76.Op Fl n Ar devs 77.Op Fl N Ar system 78.Op Fl t Ar type,if,pass 79.Op Fl w Ar wait 80.Op Ar drives 81.Sh DESCRIPTION 82.Nm Iostat 83displays kernel 84.Tn I/O 85statistics on terminal, device and cpu 86operations. 87.Pp 88The options are as follows: 89.Bl -tag -width flag 90.It Fl c 91Repeat the display 92.Ar count 93times. If no 94.Ar wait 95interval is specified, the default is 1 second. 96.It Fl C 97Display CPU statistics. This is on by default, unless 98.Fl d 99is specified. 100.It Fl d 101Display only device statistics. If this flag is turned on, only device 102statistics will be displayed, unless 103.Fl C 104or 105.Fl T 106is also specfied to enable the display of CPU or TTY statistics. 107.It Fl h 108Put iostat in 109.Sq top 110mode. In this mode, iostat will show devices in order from highest to 111lowest bytes per measurement cycle. 112.It Fl I 113Display total statstics for a given time period, rather than average 114statistics for each second during that time period. 115.It Fl K 116In the blocks transfered display (-o), display block count in kilobytes rather 117then the device native block size. 118.It Fl M 119Extract values associated with the name list from the specified core 120instead of the default 121.Dq Pa /dev/kmem . 122.It Fl n 123Display up to 124.Ar devs 125number of devices. 126.Nm iostat 127will display fewer devices if there aren't 128.Ar devs 129devices present. 130.It Fl N 131Extract the name list from the specified system instead of the default 132.Dq Pa /kernel . 133.It Fl o 134Display old-style 135.Nm iostat 136device statistics. Sectors per second, transfers per second, and miliseconds 137per seek are displayed. If 138.Fl I 139is specified, total blocks/sectors, total transfers, and 140miliseconds per seek are displayed. 141.It Fl t 142Specify which types of devices to display. There are three different 143categories of devices: 144 145.Bl -tag -width indent -compact 146.It device type: 147.Bl -tag -width 123456789 -compact 148.It da 149Direct Access devices 150.It sa 151Sequential Access devices 152.It printer 153Printers 154.It proc 155Processor devices 156.It worm 157Write Once Read Multiple devices 158.It cd 159CD devices 160.It scanner 161Scanner devices 162.It optical 163Optical Memory devices 164.It changer 165Medium Changer devices 166.It comm 167Communication devices 168.It array 169Storage Array devices 170.It enclosure 171Enclosure Services devices 172.It floppy 173Floppy devices 174.El 175.Pp 176.It interface: 177.Bl -tag -width 123456789 -compact 178.It IDE 179Integrated Drive Electronics devices 180.It SCSI 181Small Computer System Interface devices 182.It other 183Any other device interface 184.El 185.Pp 186.It passthrough: 187.Bl -tag -width 123456789 -compact 188.It pass 189Passthrough devices 190.El 191.El 192.Pp 193The user must specify at least one device type, and may specify at most 194one device type from each category. Multiple device types in a single 195device type statement must be separated by commas. 196.Pp 197Any number of 198.Fl t 199arguments may be specified on the command line. All 200.Fl t 201arguments are ORed together to form a matching expression against which 202all devices in the system are compared. Any device that fully matches 203any 204.Fl t 205argument will be included in the 206.Nm iostat 207output, up to the number of devices that can be displayed in 20880 columns, or the maximum number of devices specified by the user. 209.It Fl T 210Display TTY statistics. This is on by default, unless 211.Fl d 212is specified. 213.It Fl w 214Pause 215.Ar wait 216seconds between each display. 217If no repeat 218.Ar count 219is specified, the default is infinity. 220.It Fl ? 221Display a usage statement and exit. 222.El 223.Pp 224.Nm Iostat 225displays its information in the following format: 226.Bl -tag -width flag 227.It tty 228.Bl -tag -width indent -compact 229.It tin 230characters read from terminals 231.It tout 232characters written to terminals 233.El 234.It devices 235Device operations. The header of the field is the device name and unit number. 236.Nm iostat 237will display as many devices as will fit in a standard 80 column screen, or 238the maximum number of devices in the system, whichever is smaller. If 239.Fl n 240is specified on the command line, iostat will display the smaller of the 241requested number of devices, and the maximum number of devices in the system. 242To force 243.Nm iostat 244to display specific drives, their names may be supplied on the command 245line. 246.Nm iostat 247will not display more devices than will fit in an 80 column screen, unless 248the 249.Fl n 250argument is given on the command line to specify a maximum number of 251devices to display. If fewer devices are specified on the command line 252than will fit in an 80 column screen, iostat will show only the specified 253devices. 254.Pp 255The standard 256.Nm iostat 257device display shows the following statistics: 258.Pp 259.Bl -tag -width indent -compact 260.It KB/t 261kilobytes per transfer 262.It tps 263transfers per second 264.It MB/s 265megabytes per second 266.El 267.Pp 268The standard 269.Nm iostat 270device display, with the 271.Fl I 272flag specified, shows the following statistics: 273.Pp 274.Bl -tag -width indent -compact 275.It KB/t 276kilobytes per transfer 277.It xfrs 278total number of transfers 279.It MB 280total number of megabytes transferred 281.El 282.Pp 283The old-style 284.Nm iostat 285display (using 286.Fl o ) 287shows the following statistics: 288.Pp 289.Bl -tag -width indent -compact 290.It sps 291sectors transferred per second 292.It tps 293transfers per second 294.It msps 295average milliseconds per transaction 296.El 297.Pp 298The old-style 299.Nm iostat 300display, with the 301.Fl I 302flag specified, shows the following statistics: 303.Pp 304.Bl -tag -width indent -compact 305.It blk 306total blocks/sectors transferred 307.It xfr 308total transfers 309.It msps 310average milliseconds per transaction 311.El 312.It cpu 313.Bl -tag -width indent -compact 314.It \&us 315% of cpu time in user mode 316.It \&ni 317% of cpu time in user mode running niced processes 318.It \&sy 319% of cpu time in system mode 320.It \&in 321% of cpu time in interrupt mode 322.It \&id 323% of cpu time in idle mode 324.El 325.El 326.Sh FILES 327.Bl -tag -width /dev/kmem -compact 328.It Pa /kernel 329Default kernel namelist. 330.It Pa /dev/kmem 331Default memory file. 332.El 333.Sh EXAMPLES 334.Dl iostat -w 1 da0 da1 cd0 335.Pp 336Display statistics for the first two Direct Access devices and the first 337CDROM device every second ad infinitum. 338.Pp 339.Dl iostat -c 2 340.Pp 341Display the statistics for the first four devices in the system twice, with 342a one second display interval. 343.Pp 344.Dl iostat -t da -t cd -w 1 345.Pp 346Display statistics for all CDROM and Direct Access devices every second 347ad infinitum. 348.Pp 349.Dl iostat -t da,scsi,pass -t cd,scsi,pass 350.Pp 351Display statistics once for all SCSI passthrough devices that provide access 352to either Direct Access or CDROM devices. 353.Pp 354.Dl iostat -h -n 8 -w 1 355.Pp 356Display up to 8 devices with the most I/O every second ad infinitum. 357.Pp 358.Dl iostat -dh -t da -w 1 359.Pp 360Omit the TTY and CPU displays, show devices in order of performance and 361show only Direct Access devices every second ad infinitum. 362.Pp 363.Dl iostat -Iw 3 364.Pp 365Display total statistics every three seconds ad infinitum. 366.Pp 367.Dl iostat -odICTw 2 -c 9 368.Pp 369Display total statistics using the old-style output format 9 times, with 370a two second interval between each measurement/display. The 371.Fl d 372flag generally disables the TTY and CPU displays, but since the 373.Fl T 374and 375.Fl C 376flags are given, the TTY and CPU displays will be displayed. 377.Sh SEE ALSO 378.Xr fstat 1 , 379.Xr netstat 1 , 380.Xr nfsstat 1 , 381.Xr ps 1 , 382.Xr systat 1 , 383.Xr pstat 8 , 384.Xr vmstat 8 385.Pp 386The sections starting with ``Interpreting system activity'' in 387.%T "Installing and Operating 4.3BSD" . 388.Sh HISTORY 389This version of 390.Nm iostat 391first appeared in 392.Fx 3.0 . 393.Sh BUGS 394.Pp 395You cannot display device statistics for a non-running system, due to the 396fact that the new device statistics interface is accessible only via 397.Xr sysctl 3 , 398which does not provide a way to access non-running systems. 399.Sh AUTHORS 400.An Kenneth Merry Aq ken@FreeBSD.org 401