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$
  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 .\" 4. Neither the name of the University nor the names of its contributors
  42 .\"    may be used to endorse or promote products derived from this software
  43 .\"    without specific prior written permission.
  44 .\"
  45 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  46 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  47 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  48 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  49 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  50 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  51 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  52 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  53 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  54 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  55 .\" SUCH DAMAGE.
  56 .\"
  57 .\"     @(#)iostat.8    8.1 (Berkeley) 6/6/93
  58 .\"
  59 .Dd December 15, 2012
  60 .Dt IOSTAT 8
  61 .Os
  62 .Sh NAME
  63 .Nm iostat
  64 .Nd report
  65 .Tn I/O
  66 statistics
  67 .Sh SYNOPSIS
  68 .Nm
  69 .Op Fl CdhIKoTxz?\&
  70 .Op Fl c Ar count
  71 .Op Fl M Ar core
  72 .Op Fl n Ar devs
  73 .Op Fl N Ar system
  74 .Oo
  75 .Fl t
  76 .Sm off
  77 .Ar type , if , pass
  78 .Sm on
  79 .Oc
  80 .Op Fl w Ar wait
  81 .Op Ar drives
  82 .Sh DESCRIPTION
  83 The
  84 .Nm
  85 utility displays kernel
  86 .Tn I/O
  87 statistics on terminal, device and cpu operations.
  88 The first statistics that are printed are averaged over the system uptime.
  89 To get information about the current activity, a suitable wait time should
  90 be specified, so that the subsequent sets of printed statistics will be
  91 averaged over that time.
  92 .Pp
  93 The options are as follows:
  94 .Bl -tag -width flag
  95 .It Fl c
  96 Repeat the display
  97 .Ar count
  98 times.
  99 If no repeat
 100 .Ar count
 101 is specified, the default depends on whether
 102 .Fl w
 103 is specified.
 104 With
 105 .Fl w
 106 the default repeat count is infinity, otherwise it is 1.
 107 .It Fl C
 108 Display CPU statistics.
 109 This is on by default, unless
 110 .Fl d
 111 or
 112 .Fl x
 113 is specified.
 114 .It Fl d
 115 Display only device statistics.
 116 If this flag is turned on, only device statistics will be displayed, unless
 117 .Fl C
 118 or
 119 .Fl T
 120 is also specified to enable the display of CPU or TTY statistics.
 121 .It Fl h
 122 Put
 123 .Nm
 124 in
 125 .Sq top
 126 mode.
 127 In this mode,
 128 .Nm
 129 will show devices in order from highest to lowest bytes
 130 per measurement cycle.
 131 .It Fl I
 132 Display total statistics for a given time period, rather than average
 133 statistics for each second during that time period.
 134 .It Fl K
 135 In the blocks transferred display (-o), display block count in kilobytes rather
 136 then the device native block size.
 137 .It Fl M
 138 Extract values associated with the name list from the specified core
 139 instead of the default
 140 .Dq Pa /dev/kmem .
 141 .It Fl n
 142 Display up to
 143 .Ar devs
 144 number of devices.
 145 The
 146 .Nm
 147 utility will display fewer devices if there are not
 148 .Ar devs
 149 devices present.
 150 .It Fl N
 151 Extract the name list from the specified system instead of the default
 152 .Dq Pa /boot/kernel/kernel .
 153 .It Fl o
 154 Display old-style
 155 .Nm
 156 device statistics.
 157 Sectors per second, transfers per second, and milliseconds per seek are
 158 displayed.
 159 If
 160 .Fl I
 161 is specified, total blocks/sectors, total transfers, and
 162 milliseconds per seek are displayed.
 163 .It Fl t
 164 Specify which types of devices to display.
 165 There are three different categories of devices:
 166 .Pp
 167 .Bl -tag -width indent -compact
 168 .It device type:
 169 .Bl -tag -width 9n -compact
 170 .It da
 171 Direct Access devices
 172 .It sa
 173 Sequential Access devices
 174 .It printer
 175 Printers
 176 .It proc
 177 Processor devices
 178 .It worm
 179 Write Once Read Multiple devices
 180 .It cd
 181 CD devices
 182 .It scanner
 183 Scanner devices
 184 .It optical
 185 Optical Memory devices
 186 .It changer
 187 Medium Changer devices
 188 .It comm
 189 Communication devices
 190 .It array
 191 Storage Array devices
 192 .It enclosure
 193 Enclosure Services devices
 194 .It floppy
 195 Floppy devices
 196 .El
 197 .Pp
 198 .It interface:
 199 .Bl -tag -width 9n -compact
 200 .It IDE
 201 Integrated Drive Electronics devices
 202 .It SCSI
 203 Small Computer System Interface devices
 204 .It other
 205 Any other device interface
 206 .El
 207 .Pp
 208 .It passthrough:
 209 .Bl -tag -width 9n -compact
 210 .It pass
 211 Passthrough devices
 212 .El
 213 .El
 214 .Pp
 215 The user must specify at least one device type, and may specify at most
 216 one device type from each category.
 217 Multiple device types in a single device type statement must be separated by
 218 commas.
 219 .Pp
 220 Any number of
 221 .Fl t
 222 arguments may be specified on the command line.
 223 All
 224 .Fl t
 225 arguments are ORed together to form a matching expression against which
 226 all devices in the system are compared.
 227 Any device that fully matches any
 228 .Fl t
 229 argument will be included in the
 230 .Nm
 231 output, up to the number of devices that can be displayed in
 232 80 columns, or the maximum number of devices specified by the user.
 233 .It Fl T
 234 Display TTY statistics.
 235 This is on by default, unless
 236 .Fl d
 237 or
 238 .Fl x
 239 is specified.
 240 .It Fl w
 241 Pause
 242 .Ar wait
 243 seconds between each display.
 244 If no
 245 .Ar wait
 246 interval is specified, the default is 1 second.
 247 .Pp
 248 The
 249 .Nm
 250 command will accept and honor a non-integer number of seconds.
 251 Note that the interval only has millisecond granularity.
 252 Finer values will be truncated.
 253 E.g.,
 254 .Dq Li -w1.0001
 255 is the same as
 256 .Dq Li -w1.000 .
 257 The interval will also suffer from modifications to
 258 .Va kern.hz
 259 so your mileage may vary.
 260 .It Fl x
 261 Show extended disk statistics.
 262 Each disk is displayed on a line of its own with all available statistics.
 263 If this flag is turned on, only disk statistics will be displayed, unless
 264 .Fl C
 265 or
 266 .Fl T
 267 is also specified to enable the display of CPU or TTY statistics.
 268 .It Fl z
 269 If
 270 .Fl x
 271 is specified, omit lines for devices with no activity.
 272 .It Fl ?\&
 273 Display a usage statement and exit.
 274 .El
 275 .Pp
 276 The
 277 .Nm
 278 utility displays its information in the following format:
 279 .Bl -tag -width flag
 280 .It tty
 281 .Bl -tag -width indent -compact
 282 .It tin
 283 characters read from terminals
 284 .It tout
 285 characters written to terminals
 286 .El
 287 .It devices
 288 Device operations.
 289 The header of the field is the device name and unit number.
 290 The
 291 .Nm
 292 utility
 293 will display as many devices as will fit in a standard 80 column screen, or
 294 the maximum number of devices in the system, whichever is smaller.
 295 If
 296 .Fl n
 297 is specified on the command line,
 298 .Nm
 299 will display the smaller of the
 300 requested number of devices, and the maximum number of devices in the system.
 301 To force
 302 .Nm
 303 to display specific drives, their names may be supplied on the command
 304 line.
 305 The
 306 .Nm
 307 utility
 308 will not display more devices than will fit in an 80 column screen, unless
 309 the
 310 .Fl n
 311 argument is given on the command line to specify a maximum number of
 312 devices to display.
 313 If fewer devices are specified on the command line than will fit in an 80
 314 column screen,
 315 .Nm
 316 will show only the specified devices.
 317 .Pp
 318 The standard
 319 .Nm
 320 device display shows the following statistics:
 321 .Pp
 322 .Bl -tag -width indent -compact
 323 .It KB/t
 324 kilobytes per transfer
 325 .It tps
 326 transfers per second
 327 .It MB/s
 328 megabytes per second
 329 .El
 330 .Pp
 331 The standard
 332 .Nm
 333 device display, with the
 334 .Fl I
 335 flag specified, shows the following statistics:
 336 .Pp
 337 .Bl -tag -width indent -compact
 338 .It KB/t
 339 kilobytes per transfer
 340 .It xfrs
 341 total number of transfers
 342 .It MB
 343 total number of megabytes transferred
 344 .El
 345 .Pp
 346 The extended
 347 .Nm
 348 device display, with the
 349 .Fl x
 350 flag specified, shows the following statistics:
 351 .Pp
 352 .Bl -tag -width indent -compact
 353 .It r/s
 354 read operations per second
 355 .It w/s
 356 write operations per second
 357 .It kr/s
 358 kilobytes read per second
 359 .It kw/s
 360 kilobytes write per second
 361 .It qlen
 362 transactions queue length
 363 .It svc_t
 364 average duration of transactions, in milliseconds
 365 .It %b
 366 % of time the device had one or more outstanding transactions
 367 .El
 368 .Pp
 369 The extended
 370 .Nm
 371 device display, with the
 372 .Fl x
 373 and
 374 .Fl I
 375 flags specified, shows the following statistics:
 376 .Pp
 377 .Bl -tag -width indent -compact
 378 .It r/i
 379 read operations per time period
 380 .It w/i
 381 write operations per time period
 382 .It kr/i
 383 kilobytes read per time period
 384 .It kw/i
 385 kilobytes write per time period
 386 .It qlen
 387 transactions queue length
 388 .It tsvc_t/i
 389 total duration of transactions per time period, in seconds
 390 .It sb/i
 391 total time the device had one or more outstanding transactions per
 392 time period, in seconds
 393 .El
 394 .Pp
 395 The old-style
 396 .Nm
 397 display (using
 398 .Fl o )
 399 shows the following statistics:
 400 .Pp
 401 .Bl -tag -width indent -compact
 402 .It sps
 403 sectors transferred per second
 404 .It tps
 405 transfers per second
 406 .It msps
 407 average milliseconds per transaction
 408 .El
 409 .Pp
 410 The old-style
 411 .Nm
 412 display, with the
 413 .Fl I
 414 flag specified, shows the following statistics:
 415 .Pp
 416 .Bl -tag -width indent -compact
 417 .It blk
 418 total blocks/sectors transferred
 419 .It xfr
 420 total transfers
 421 .It msps
 422 average milliseconds per transaction
 423 .El
 424 .It cpu
 425 .Bl -tag -width indent -compact
 426 .It \&us
 427 % of cpu time in user mode
 428 .It \&ni
 429 % of cpu time in user mode running niced processes
 430 .It \&sy
 431 % of cpu time in system mode
 432 .It \&in
 433 % of cpu time in interrupt mode
 434 .It \&id
 435 % of cpu time in idle mode
 436 .El
 437 .El
 438 .Sh FILES
 439 .Bl -tag -width /boot/kernel/kernel -compact
 440 .It Pa /boot/kernel/kernel
 441 Default kernel namelist.
 442 .It Pa /dev/kmem
 443 Default memory file.
 444 .El
 445 .Sh EXAMPLES
 446 .Dl iostat -w 1 da0 da1 cd0
 447 .Pp
 448 Display statistics for the first two Direct Access devices and the first
 449 CDROM device every second ad infinitum.
 450 .Pp
 451 .Dl iostat -c 2
 452 .Pp
 453 Display the statistics for the first four devices in the system twice, with
 454 a one second display interval.
 455 .Pp
 456 .Dl iostat -t da -t cd -w 1
 457 .Pp
 458 Display statistics for all CDROM and Direct Access devices every second
 459 ad infinitum.
 460 .Pp
 461 .Dl iostat -t da,scsi,pass -t cd,scsi,pass
 462 .Pp
 463 Display statistics once for all SCSI passthrough devices that provide access
 464 to either Direct Access or CDROM devices.
 465 .Pp
 466 .Dl iostat -h -n 8 -w 1
 467 .Pp
 468 Display up to 8 devices with the most I/O every second ad infinitum.
 469 .Pp
 470 .Dl iostat -dh -t da -w 1
 471 .Pp
 472 Omit the TTY and CPU displays, show devices in order of performance and
 473 show only Direct Access devices every second ad infinitum.
 474 .Pp
 475 .Dl iostat -Iw 3
 476 .Pp
 477 Display total statistics every three seconds ad infinitum.
 478 .Pp
 479 .Dl iostat -odICTw 2 -c 9
 480 .Pp
 481 Display total statistics using the old-style output format 9 times, with
 482 a two second interval between each measurement/display.
 483 The
 484 .Fl d
 485 flag generally disables the TTY and CPU displays, but since the
 486 .Fl T
 487 and
 488 .Fl C
 489 flags are given, the TTY and CPU displays will be displayed.
 490 .Sh SEE ALSO
 491 .Xr fstat 1 ,
 492 .Xr netstat 1 ,
 493 .Xr nfsstat 1 ,
 494 .Xr ps 1 ,
 495 .Xr systat 1 ,
 496 .Xr devstat 3 ,
 497 .Xr gstat 8 ,
 498 .Xr pstat 8 ,
 499 .Xr vmstat 8
 500 .Pp
 501 The sections starting with ``Interpreting system activity'' in
 502 .%T "Installing and Operating 4.3BSD" .
 503 .Sh HISTORY
 504 This version of
 505 .Nm
 506 first appeared in
 507 .Fx 3.0 .
 508 .Sh AUTHORS
 509 .An Kenneth Merry Aq ken@FreeBSD.org
 510 .Sh BUGS
 511 The use of
 512 .Nm
 513 as a debugging tool for crash dumps is probably limited because there is
 514 currently no way to get statistics that only cover the time immediately before
 515 the crash.