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.\" $Id$ 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 CdhIoT? 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 M 116Extract values associated with the name list from the specified core 117instead of the default 118.Dq Pa /dev/kmem . 119.It Fl n 120Display up to 121.Ar devs 122number of devices. 123.Nm iostat 124will display fewer devices if there aren't 125.Ar devs 126devices present. 127.It Fl N 128Extract the name list from the specified system instead of the default 129.Dq Pa /kernel . 130.It Fl o 131Display old-style 132.Nm iostat 133device statistics. Sectors per second, transfers per second, and miliseconds 134per seek are displayed. If 135.Fl I 136is specified, total blocks/sectors, total transfers, and 137miliseconds per seek are displayed. 138.It Fl t 139Specify which types of devices to display. There are three different 140categories of devices: 141 142.Bl -tag -width indent -compact 143.It device type: 144.Bl -tag -width 123456789 -compact 145.It da 146Direct Access devices 147.It sa 148Sequential Access devices 149.It printer 150Printers 151.It proc 152Processor devices 153.It worm 154Write Once Read Multiple devices 155.It cd 156CD devices 157.It scanner 158Scanner devices 159.It optical 160Optical Memory devices 161.It changer 162Medium Changer devices 163.It comm 164Communication devices 165.It array 166Storage Array devices 167.It enclosure 168Enclosure Services devices 169.It floppy 170Floppy devices 171.El 172.Pp 173.It interface: 174.Bl -tag -width 123456789 -compact 175.It IDE 176Integrated Drive Electronics devices 177.It SCSI 178Small Computer System Interface devices 179.It other 180Any other device interface 181.El 182.Pp 183.It passthrough: 184.Bl -tag -width 123456789 -compact 185.It pass 186Passthrough devices 187.El 188.El 189.Pp 190The user must specify at least one device type, and may specify at most 191one device type from each category. Multiple device types in a single 192device type statement must be separated by commas. 193.Pp 194Any number of 195.Fl t 196arguments may be specified on the command line. All 197.Fl t 198arguments are ORed together to form a matching expression against which 199all devices in the system are compared. Any device that fully matches 200any 201.Fl t 202argument will be included in the 203.Nm iostat 204output, up to the number of devices that can be displayed in 20580 columns, or the maximum number of devices specified by the user. 206.It Fl T 207Display TTY statistics. This is on by default, unless 208.Fl d 209is specified. 210.It Fl w 211Pause 212.Ar wait 213seconds between each display. 214If no repeat 215.Ar count 216is specified, the default is infinity. 217.It Fl ? 218Display a usage statement and exit. 219.El 220.Pp 221.Nm Iostat 222displays its information in the following format: 223.Bl -tag -width flag 224.It tty 225.Bl -tag -width indent -compact 226.It tin 227characters read from terminals 228.It tout 229characters written to terminals 230.El 231.It devices 232Device operations. The header of the field is the device name and unit number. 233.Nm iostat 234will display as many devices as will fit in a standard 80 column screen, or 235the maximum number of devices in the system, whichever is smaller. If 236.Fl n 237is specified on the command line, iostat will display the smaller of the 238requested number of devices, and the maximum number of devices in the system. 239To force 240.Nm iostat 241to display specific drives, their names may be supplied on the command 242line. 243.Nm iostat 244will not display more devices than will fit in an 80 column screen, unless 245the 246.Fl n 247argument is given on the command line to specify a maximum number of 248devices to display. If fewer devices are specified on the command line 249than will fit in an 80 column screen, iostat will show only the specified 250devices. 251.Pp 252The standard 253.Nm iostat 254device display shows the following statistics: 255.Pp 256.Bl -tag -width indent -compact 257.It KB/t 258kilobytes per transfer 259.It tps 260transfers per second 261.It MB/s 262megabytes per second 263.El 264.Pp 265The standard 266.Nm iostat 267device display, with the 268.Fl I 269flag specified, shows the following statistics: 270.Pp 271.Bl -tag -width indent -compact 272.It KB/t 273kilobytes per transfer 274.It xfrs 275total number of transfers 276.It MB 277total number of megabytes transferred 278.El 279.Pp 280The old-style 281.Nm iostat 282display (using 283.Fl o ) 284shows the following statistics: 285.Pp 286.Bl -tag -width indent -compact 287.It sps 288sectors transferred per second 289.It tps 290transfers per second 291.It msps 292average milliseconds per transaction 293.El 294.Pp 295The old-style 296.Nm iostat 297display, with the 298.Fl I 299flag specified, shows the following statistics: 300.Pp 301.Bl -tag -width indent -compact 302.It blk 303total blocks/sectors transferred 304.It xfr 305total transfers 306.It msps 307average milliseconds per transaction 308.El 309.It cpu 310.Bl -tag -width indent -compact 311.It \&us 312% of cpu time in user mode 313.It \&ni 314% of cpu time in user mode running niced processes 315.It \&sy 316% of cpu time in system mode 317.It \&in 318% of cpu time in interrupt mode 319.It \&id 320% of cpu time in idle mode 321.El 322.El 323.Sh FILES 324.Bl -tag -width /dev/kmem -compact 325.It Pa /kernel 326Default kernel namelist. 327.It Pa /dev/kmem 328Default memory file. 329.El 330.Sh EXAMPLES 331.Dl iostat -w 1 da0 da1 cd0 332.Pp 333Display statistics for the first two Direct Access devices and the first 334CDROM device every second ad infinitum. 335.Pp 336.Dl iostat -c 2 337.Pp 338Display the statistics for the first four devices in the system twice, with 339a one second display interval. 340.Pp 341.Dl iostat -t da -t cd -w 1 342.Pp 343Display statistics for all CDROM and Direct Access devices every second 344ad infinitum. 345.Pp 346.Dl iostat -t da,scsi,pass -t cd,scsi,pass 347.Pp 348Display statistics once for all SCSI passthrough devices that provide access 349to either Direct Access or CDROM devices. 350.Pp 351.Dl iostat -h -n 8 -w 1 352.Pp 353Display up to 8 devices with the most I/O every second ad inifitum. 354.Pp 355.Dl iostat -dh -t da -w 1 356.Pp 357Omit the TTY and CPU displays, show devices in order of performance and 358show only Direct Access devices every second ad infinitum. 359.Pp 360.Dl iostat -Iw 3 361.Pp 362Display total statistics every three seconds ad infinitum. 363.Pp 364.Dl iostat -odICTw 2 -c 9 365.Pp 366Display total statistics using the old-style output format 9 times, with 367a two second interval between each measurement/display. The 368.Fl d 369flag generally disables the TTY and CPU displays, but since the 370.Fl T 371and 372.Fl C 373flags are given, the TTY and CPU displays will be displayed. 374.Sh SEE ALSO 375.Xr fstat 1 , 376.Xr netstat 1 , 377.Xr nfsstat 1 , 378.Xr ps 1 , 379.Xr systat 1 , 380.Xr pstat 8 , 381.Xr vmstat 8 382.Pp 383The sections starting with ``Interpreting system activity'' in 384.%T "Installing and Operating 4.3BSD" . 385.Sh HISTORY 386This version of 387.Nm iostat 388first appeared in 389.Fx 3.0 . 390.Sh BUGS 391.Pp 392You cannot display device statistics for a non-running system, due to the 393fact that the new device statistics interface is accessible only via 394.Xr sysctl 3 , 395which does not provide a way to access non-running systems. 396.Sh AUTHOR 397.An Kenneth Merry Aq ken@FreeBSD.ORG 398