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