usr.sbin/iostat/iostat.8

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