1.\" $NetBSD: iostat.8,v 1.30 2023/07/28 12:03:33 wiz 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 July 28, 2023 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 CDdITXxyz 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 , 69.Fl x , 70or 71.Fl y ) 72is used. 73.Pp 74The options are as follows: 75.Bl -tag -width XNXsystemX 76.It Fl C 77Show CPU statistics. 78This is enabled by default unless any of the 79.Fl D , 80.Fl d , 81.Fl T , 82.Fl X , 83.Fl x , 84or 85.Fl y 86flags are used. 87.It Fl c Ar count 88Repeat the display 89.Ar count 90times. 91Unless the 92.Fl I 93flag is in effect, the first display is for the time since a reboot and 94each subsequent report is for the time period since the last display. 95If no 96.Ar wait 97interval is specified, the default is 1 second. 98.It Fl D 99Show alternative disk statistics. 100Displays 101number of transfers, 102kilobytes transferred, 103and 104time spent in transfers, 105during the 106.Ar wait 107period (or since boot with 108.Fl I ) . 109Use of this flag disables the default display. 110.It Fl d 111Show disk statistics. 112This is the default. 113Displays 114number of transfers per second, 115kilobytes per transfer, 116and 117megabytes transferred per second. 118Use of this flag disables the default display of CPU and tty statistics. 119.It Fl H Ar height 120Set the page size (length, or height) explicitly, as the number of lines, 121.Ar height . 122If not set, the page length is taken from the environment variable 123.Ev LINES 124if set, or from the terminal (window) size, if output is to a terminal 125and its size is set, 126and otherwise defaults to 20. 127If explicitly set to zero, pages are considered to be infinitely long. 128This parameter determines the frequency at which repeated headers are output. 129If the value is greater than zero, but too small for the header, along with 130one output set, then a new header will be produced for each set of output. 131.It Fl I 132Show the running total values, rather than an average. 133.ig ii 134.It Fl i 135Like 136.Fl I 137except the totals shown are those since 138.Nm 139started running, rather than since the system booted. 140In this case the first output would necessarily be zero, 141so is suppressed. 142Consequently this option produces no output if neither 143.Fl c 144nor 145.Fl w 146is given. 147.ii 148.It Fl T 149Show tty statistics. 150This is enabled by default unless one, or more, of the 151.Fl C , 152.Fl D , 153.Fl d , 154.Fl X , 155.Fl x , 156or 157.Fl y 158flags are used. 159.ig uu 160.It Fl u 161When totals are being shown 162.Pq Fl I 163.ig ii 164.Po or 165.Fl i Pc 166.ii 167include a column after each relevant output column 168showing the difference between this output and the previous. 169These added columns will be blank in the first displayed output. 170.uu 171.It Fl W Ar width 172Set the page width explicitly, as the number of columns of characters, 173.Ar width . 174If not set, the page width is taken from the environment variable 175.Ev COLUMNS 176if set, or from the terminal (window) size, if output is to a terminal 177and its size is set, 178and otherwise defaults to 80. 179If explicitly set to 0, lines are considered infinitely long. 180This width is used only to determine the number of drives to display 181by default when no drive list is given. 182In other cases output will be as wide as needed to display the 183data requested. 184.It Fl w Ar wait 185Pause 186.Ar wait 187seconds between each display. 188If no repeat 189.Ar count 190is specified, the default is infinity. 191.It Fl X 192Show limited alternative disk statistics. 193Displays megabytes transferred, and time spent in transfers, during the 194.Ar wait 195period (or since boot with 196.Fl I ) . 197Use of this flag disables the default display. 198.It Fl x 199Show extended disk statistics. 200Each disk is displayed on a line of its own with all available 201statistics. 202This option overrides all other display options, and all 203disks are displayed unless specific disk names 204are provided as arguments. 205Additionally, separate read and write statistics are displayed. 206The 207.Fl C 208and 209.Fl T 210options are ignored with this output format. 211.It Fl y 212Shows the extended statistics (as with 213.Fl x ) 214and additional queuing statistics. 215Output does not fit in an 80 column window. 216The 217.Fl C 218and 219.Fl T 220options are ignored with this output format. 221.It Fl z 222Replaces drive and CPU statistic outputs that are exactly zero with spaces. 223Note that zero values can still appear \(en this indicates a 224value that was not zero, but was rounded down so appears as zero. 225Drive output is replaced by spaces only when the drive did no 226input or output at all in the interval, 227or with 228.Fl I , 229has never done any I/O. 230.El 231.Pp 232.Nm 233displays its information in the following format: 234.Bl -tag -width flag 235.It tty 236.Bl -tag -width indent -compact 237.It tin 238characters read from terminals 239.It tout 240characters written to terminals 241.El 242.It disks 243Disk operations. 244The header of the field is the disk name and unit number. 245If more drives are configured in the system that fit across the 246current display, 247.Nm 248displays only those drives that fit on the display. 249To force 250.Nm 251to display specific drives, they may be supplied on the command 252line, either as names or 253.Fn fnmatch 254patterns. 255.Pp 256.Bl -tag -width indent -compact 257.It t/s 258transfers per second 259.It KB/t 260Kilobytes transferred per disk transfer 261.It MB/s 262Megabytes transferred per second 263.El 264.Pp 265The alternative display format, (selected with 266.Fl D ) , 267presents the following values: 268.Pp 269.Bl -tag -width indent -compact 270.It xfr 271Disk transfers 272.It KB 273Kilobytes transferred 274.It time 275Seconds spent in disk activity 276.El 277.Pp 278With the 279.Fl y 280flag, the following queuing measurements are added: 281.Pp 282.Bl -tag -width indent -compact 283.It wait 284Number of I/O requests queued up 285.It actv 286Number of currently active I/O requests 287.It wsvc_t 288Average waiting time of an I/O request in milliseconds 289.It asvc_t 290Average duration of an I/O request in milliseconds 291.It wtime 292Seconds spent in the waiting queue. 293Queuing data might not be available from all drivers 294and is then shown as zeros. 295.El 296.Pp 297With the 298.Fl X 299flag, the following queuing measurements are added: 300.Pp 301.Bl -tag -width indent -compact 302.It MB/s 303Megabytes transferred per second 304.It time 305Seconds spent in disk activity 306.El 307.It cpu 308.Bl -tag -width indent -compact 309.It \&us 310% of CPU time in user mode 311.It \&ni 312% of CPU time in user mode running niced processes 313.It \&sy 314% of CPU time in system mode 315.It \&in 316% of CPU time in interrupt mode 317.It \&id 318% of CPU time in idle mode 319.El 320.Pp 321Note that because of rounding, these percentages may 322appear to total more or less than 100. 323.El 324.Sh SEE ALSO 325.Xr fstat 1 , 326.Xr netstat 1 , 327.Xr nfsstat 1 , 328.Xr ps 1 , 329.Xr systat 1 , 330.Xr vmstat 1 , 331.Xr fnmatch 3 , 332.Xr pstat 8 333.Pp 334The sections starting with ``Interpreting system activity'' in 335.%T "Installing and Operating 4.3BSD" . 336.Sh HISTORY 337.Nm 338appeared in 339.At v6 . 340The 341.Fl x 342option was added in 343.Nx 1.4 . 344Collection of queuing values and the 345.Fl y 346option were added in 347.Nx 8.0 . 348The 349.Fl X 350option was added in 351.Nx 11.0 . 352The archaic option format: 353.br 354.ti +3n 355.Nm 356.Op Ar drives ... 357.Oo Ar wait Oo Ar count Oc Oc 358.br 359remains supported (the first 360.Ar drive 361whose name starts with a digit is taken to be the 362.Ar wait 363period) but is deprecated, 364and may be removed in a future version, 365so should not be used. 366