1.\" $NetBSD: iostat.8,v 1.28 2022/06/18 11:33:13 kre Exp $ 2.\" 3.\" Copyright (c) 1985, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" from: @(#)iostat.8 8.1 (Berkeley) 6/6/93 31.\" 32.Dd June 18, 2022 33.Dt IOSTAT 8 34.Os 35.Sh NAME 36.Nm iostat 37.Nd report I/O statistics 38.Sh SYNOPSIS 39.Nm 40.Op Fl CdDITxyz 41.Op Fl c Ar count 42.Op Fl H Ar height 43.Op Fl W Ar width 44.Op Fl w Ar wait 45.Op Ar drives 46.Sh DESCRIPTION 47.Nm 48displays kernel I/O statistics on terminal, disk and CPU operations. 49By default, 50.Nm 51displays one line of statistics averaged over the machine's run time. 52The use of 53.Fl c 54or 55.Fl w 56presents successive lines averaged over the 57.Ar wait 58period. 59The 60.Fl I 61option causes 62.Nm 63to print raw, unaveraged values (totals). 64.Pp 65Only the last disk option specified 66.Fl ( d , 67.Fl D , 68.Fl x , 69or 70.Fl y ) 71is used. 72.Pp 73The options are as follows: 74.Bl -tag -width XNXsystemX 75.It Fl c Ar count 76Repeat the display 77.Ar count 78times. 79Unless the 80.Fl I 81flag is in effect, the first display is for the time since a reboot and 82each subsequent report is for the time period since the last display. 83If no 84.Ar wait 85interval is specified, the default is 1 second. 86.It Fl C 87Show CPU statistics. 88This is enabled by default unless any of the 89.Fl d , 90.Fl D , 91.Fl T , 92.Fl x , 93or 94.Fl y 95flags are used. 96.It Fl d 97Show disk statistics. 98This is the default. 99Displays 100number of transfers per second, 101kilobytes per transfer, 102and 103megabytes transferred per second. 104Use of this flag disables the default display of CPU and tty statistics. 105.It Fl D 106Show alternative disk statistics. 107Displays 108number of transfers, 109kilobytes transferred, 110and 111time spent in transfers, 112during the 113.Ar wait 114period (or since boot with 115.Fl I ) . 116Use of this flag disables the default display. 117.It Fl H Ar height 118Set the page size (length, or height) explicitly, as the number of lines, 119.Ar height . 120If not set, the page length is taken from the environment variable 121.Ev LINES 122if set, or from the terminal (window) size, if output is to a terminal 123and its size is set, 124and otherwise defaults to 20. 125If explicitly set to zero, pages are considered to be infinitely long. 126This parameter determines the frequency at which repeated headers are output. 127If the value is greater than zero, but too small for the header, along with 128one output set, then a new header will be produced for each set of output. 129.It Fl I 130Show the running total values, rather than an average. 131.ig ii 132.It Fl i 133Like 134.Fl I 135except the totals shown are those since 136.Nm 137started running, rather than since the system booted. 138In this case the first output would necessarily be zero, 139so is suppressed. 140Consequently this option produces no output if neither 141.Fl w 142nor 143.Fl c 144is given. 145.ii 146.It Fl T 147Show tty statistics. 148This is enabled by default unless one, or more, of the 149.Fl C , 150.Fl d , 151.Fl D , 152.Fl x , 153or 154.Fl y 155flags are used. 156.ig uu 157.It Fl u 158When totals are being shown 159.Pq Fl I 160.ig ii 161.Po or 162.Fl i Pc 163.ii 164include a column after each relevant output column 165showing the difference between this output and the previous. 166These added columns will be blank in the first displayed output. 167.uu 168.It Fl w Ar wait 169Pause 170.Ar wait 171seconds between each display. 172If no repeat 173.Ar count 174is specified, the default is infinity. 175.It Fl W Ar width 176Set the page width explicitly, as the number of columns of characters, 177.Ar width . 178If not set, the page width is taken from the environment variable 179.Ev COLUMNS 180if set, or from the terminal (window) size, if output is to a terminal 181and its size is set, 182and otherwise defaults to 80. 183If explicitly set to 0, lines are considered infinitely long. 184This width is used only to determine the number of drives to display 185by default when no drive list is given. 186In other cases output will be as wide as needed to display the 187data requested. 188.It Fl x 189Show extended disk statistics. 190Each disk is displayed on a line of its own with all available 191statistics. 192This option overrides all other display options, and all 193disks are displayed unless specific disk names 194are provided as arguments. 195Additionally, separate read and write statistics are displayed. 196The 197.Fl C 198and 199.Fl T 200options are ignored with this output format. 201.It Fl y 202Shows the extended statistics (as with 203.Fl x ) 204and additional queuing statistics. 205Output does not fit in an 80 column window. 206The 207.Fl C 208and 209.Fl T 210options are ignored with this output format. 211.It Fl z 212Replaces drive and CPU statistic outputs that are exactly zero with spaces. 213Note that zero values can still appear \(en this indicates a 214value that was not zero, but was rounded down so appears as zero. 215Drive output is replaced by spaces only when the drive did no 216input or output at all in the interval, 217or with 218.Fl I , 219has never done any I/O. 220.El 221.Pp 222.Nm 223displays its information in the following format: 224.Bl -tag -width flag 225.It tty 226.Bl -tag -width indent -compact 227.It tin 228characters read from terminals 229.It tout 230characters written to terminals 231.El 232.It disks 233Disk operations. 234The header of the field is the disk name and unit number. 235If more drives are configured in the system that fit across the 236current display, 237.Nm 238displays only those drives that fit on the display. 239To force 240.Nm 241to display specific drives, they may be supplied on the command 242line, either as names or 243.Fn fnmatch 244patterns. 245.Pp 246.Bl -tag -width indent -compact 247.It t/s 248transfers per second 249.It KB/t 250Kilobytes transferred per disk transfer 251.It MB/s 252Megabytes transferred per second 253.El 254.Pp 255The alternative display format, (selected with 256.Fl D ) , 257presents the following values: 258.Bl -tag -width indent -compact 259.It xfr 260Disk transfers 261.It KB 262Kilobytes transferred 263.It time 264Seconds spent in disk activity 265.El 266.Pp 267With the 268.Fl y 269flag, the following queuing measurements are added: 270.Bl -tag -width indent -compact 271.It wait 272Number of I/O requests queued up 273.It actv 274Number of currently active I/O requests 275.It wsvc_t 276Average waiting time of an I/O request in milliseconds 277.It asvc_t 278Average duration of an I/O request in milliseconds 279.It wtime 280Seconds spent in the waiting queue. 281Queuing data might not be available from all drivers 282and is then shown as zeros. 283.El 284.It cpu 285.Bl -tag -width indent -compact 286.It \&us 287% of CPU time in user mode 288.It \&ni 289% of CPU time in user mode running niced processes 290.It \&sy 291% of CPU time in system mode 292.It \&in 293% of CPU time in interrupt mode 294.It \&id 295% of CPU time in idle mode 296.El 297.Pp 298Note that because of rounding, these percentages may 299appear to total more or less than 100. 300.El 301.Sh SEE ALSO 302.Xr fstat 1 , 303.Xr netstat 1 , 304.Xr nfsstat 1 , 305.Xr ps 1 , 306.Xr systat 1 , 307.Xr vmstat 1 , 308.Xr fnmatch 3 , 309.Xr pstat 8 310.Pp 311The sections starting with ``Interpreting system activity'' in 312.%T "Installing and Operating 4.3BSD" . 313.Sh HISTORY 314.Nm 315appeared in 316.At v6 . 317The 318.Fl x 319option was added in 320.Nx 1.4 . 321Collection of queuing values and the 322.Fl y 323option were added in 324.Nx 8.0 . 325The archaic option format: 326.br 327.ti +3n 328.Nm 329.Op Ar drives ... 330.Oo Ar wait Op Ar count Oc 331.br 332remains supported (the first 333.Ar drive 334whose name starts with a digit is taken to be the 335.Ar wait 336period) but is deprecated, 337and may be removed in a future version, 338so should not be used. 339