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 .\" 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 April 17, 2006
  64 .Dt IOSTAT 8
  65 .Os
  66 .Sh NAME
  67 .Nm iostat
  68 .Nd report
  69 .Tn I/O
  70 statistics
  71 .Sh SYNOPSIS
  72 .Nm
  73 .Op Fl CdhIKoTxz?\&
  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 The
  88 .Nm
  89 utility displays kernel
  90 .Tn I/O
  91 statistics on terminal, device and cpu operations.
  92 The first statistics that are printed are averaged over the system uptime.
  93 To get information about the current activity, a suitable wait time should
  94 be specified, so that the subsequent sets of printed statistics will be
  95 averaged over that time.
  96 .Pp
  97 The options are as follows:
  98 .Bl -tag -width flag
  99 .It Fl c
 100 Repeat the display
 101 .Ar count
 102 times.
 103 If no
 104 .Ar wait
 105 interval is specified, the default is 1 second.
 106 .It Fl C
 107 Display CPU statistics.
 108 This is on by default, unless
 109 .Fl d
 110 is specified.
 111 .It Fl d
 112 Display only device statistics.
 113 If this flag is turned on, only device statistics will be displayed, unless
 114 .Fl C
 115 or
 116 .Fl T
 117 is also specified to enable the display of CPU or TTY statistics.
 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 M
 135 Extract values associated with the name list from the specified core
 136 instead of the default
 137 .Dq Pa /dev/kmem .
 138 .It Fl n
 139 Display up to
 140 .Ar devs
 141 number of devices.
 142 The
 143 .Nm
 144 utility will display fewer devices if there are not
 145 .Ar devs
 146 devices present.
 147 .It Fl N
 148 Extract the name list from the specified system instead of the default
 149 .Dq Pa /boot/kernel/kernel .
 150 .It Fl o
 151 Display old-style
 152 .Nm
 153 device statistics.
 154 Sectors per second, transfers per second, and milliseconds per seek are
 155 displayed.
 156 If
 157 .Fl I
 158 is specified, total blocks/sectors, total transfers, and
 159 milliseconds per seek are displayed.
 160 .It Fl t
 161 Specify which types of devices to display.
 162 There are three different categories of devices:
 163 .Pp
 164 .Bl -tag -width indent -compact
 165 .It device type:
 166 .Bl -tag -width 9n -compact
 167 .It da
 168 Direct Access devices
 169 .It sa
 170 Sequential Access devices
 171 .It printer
 172 Printers
 173 .It proc
 174 Processor devices
 175 .It worm
 176 Write Once Read Multiple devices
 177 .It cd
 178 CD devices
 179 .It scanner
 180 Scanner devices
 181 .It optical
 182 Optical Memory devices
 183 .It changer
 184 Medium Changer devices
 185 .It comm
 186 Communication devices
 187 .It array
 188 Storage Array devices
 189 .It enclosure
 190 Enclosure Services devices
 191 .It floppy
 192 Floppy devices
 193 .El
 194 .Pp
 195 .It interface:
 196 .Bl -tag -width 9n -compact
 197 .It IDE
 198 Integrated Drive Electronics devices
 199 .It SCSI
 200 Small Computer System Interface devices
 201 .It other
 202 Any other device interface
 203 .El
 204 .Pp
 205 .It passthrough:
 206 .Bl -tag -width 9n -compact
 207 .It pass
 208 Passthrough devices
 209 .El
 210 .El
 211 .Pp
 212 The user must specify at least one device type, and may specify at most
 213 one device type from each category.
 214 Multiple device types in a single device type statement must be separated by
 215 commas.
 216 .Pp
 217 Any number of
 218 .Fl t
 219 arguments may be specified on the command line.
 220 All
 221 .Fl t
 222 arguments are ORed together to form a matching expression against which
 223 all devices in the system are compared.
 224 Any device that fully matches any
 225 .Fl t
 226 argument will be included in the
 227 .Nm
 228 output, up to the number of devices that can be displayed in
 229 80 columns, or the maximum number of devices specified by the user.
 230 .It Fl T
 231 Display TTY statistics.
 232 This is on by default, unless
 233 .Fl d
 234 is specified.
 235 .It Fl w
 236 Pause
 237 .Ar wait
 238 seconds between each display.
 239 If no repeat
 240 .Ar count
 241 is specified, the default is infinity.
 242 .It Fl x
 243 Show extended disk statistics.
 244 Each disk is displayed on a line of its own with all available statistics.
 245 .It Fl z
 246 If
 247 .Fl x
 248 is specified, omit lines for devices with no activity.
 249 .It Fl ?\&
 250 Display a usage statement and exit.
 251 .El
 252 .Pp
 253 The
 254 .Nm
 255 utility displays its information in the following format:
 256 .Bl -tag -width flag
 257 .It tty
 258 .Bl -tag -width indent -compact
 259 .It tin
 260 characters read from terminals
 261 .It tout
 262 characters written to terminals
 263 .El
 264 .It devices
 265 Device operations.
 266 The header of the field is the device name and unit number.
 267 The
 268 .Nm
 269 utility
 270 will display as many devices as will fit in a standard 80 column screen, or
 271 the maximum number of devices in the system, whichever is smaller.
 272 If
 273 .Fl n
 274 is specified on the command line,
 275 .Nm
 276 will display the smaller of the
 277 requested number of devices, and the maximum number of devices in the system.
 278 To force
 279 .Nm
 280 to display specific drives, their names may be supplied on the command
 281 line.
 282 The
 283 .Nm
 284 utility
 285 will not display more devices than will fit in an 80 column screen, unless
 286 the
 287 .Fl n
 288 argument is given on the command line to specify a maximum number of
 289 devices to display.
 290 If fewer devices are specified on the command line than will fit in an 80
 291 column screen,
 292 .Nm
 293 will show only the specified devices.
 294 .Pp
 295 The standard
 296 .Nm
 297 device display shows the following statistics:
 298 .Pp
 299 .Bl -tag -width indent -compact
 300 .It KB/t
 301 kilobytes per transfer
 302 .It tps
 303 transfers per second
 304 .It MB/s
 305 megabytes per second
 306 .El
 307 .Pp
 308 The standard
 309 .Nm
 310 device display, with the
 311 .Fl I
 312 flag specified, shows the following statistics:
 313 .Pp
 314 .Bl -tag -width indent -compact
 315 .It KB/t
 316 kilobytes per transfer
 317 .It xfrs
 318 total number of transfers
 319 .It MB
 320 total number of megabytes transferred
 321 .El
 322 .Pp
 323 The extended
 324 .Nm
 325 device display, with the
 326 .Fl x
 327 flag specified, shows the following statistics:
 328 .Pp
 329 .Bl -tag -width indent -compact
 330 .It r/s
 331 read operations per second
 332 .It w/s
 333 write operations per second
 334 .It kr/s
 335 kilobytes read per second
 336 .It kw/s
 337 kilobytes write per second
 338 .It wait
 339 transactions queue length
 340 .It svc_t
 341 average duration of transactions, in milliseconds
 342 .It %b
 343 % of time the device had one or more outstanding transactions
 344 .El
 345 .Pp
 346 The old-style
 347 .Nm
 348 display (using
 349 .Fl o )
 350 shows the following statistics:
 351 .Pp
 352 .Bl -tag -width indent -compact
 353 .It sps
 354 sectors transferred per second
 355 .It tps
 356 transfers per second
 357 .It msps
 358 average milliseconds per transaction
 359 .El
 360 .Pp
 361 The old-style
 362 .Nm
 363 display, with the
 364 .Fl I
 365 flag specified, shows the following statistics:
 366 .Pp
 367 .Bl -tag -width indent -compact
 368 .It blk
 369 total blocks/sectors transferred
 370 .It xfr
 371 total transfers
 372 .It msps
 373 average milliseconds per transaction
 374 .El
 375 .It cpu
 376 .Bl -tag -width indent -compact
 377 .It \&us
 378 % of cpu time in user mode
 379 .It \&ni
 380 % of cpu time in user mode running niced processes
 381 .It \&sy
 382 % of cpu time in system mode
 383 .It \&in
 384 % of cpu time in interrupt mode
 385 .It \&id
 386 % of cpu time in idle mode
 387 .El
 388 .El
 389 .Sh FILES
 390 .Bl -tag -width /boot/kernel/kernel -compact
 391 .It Pa /boot/kernel/kernel
 392 Default kernel namelist.
 393 .It Pa /dev/kmem
 394 Default memory file.
 395 .El
 396 .Sh EXAMPLES
 397 .Dl iostat -w 1 da0 da1 cd0
 398 .Pp
 399 Display statistics for the first two Direct Access devices and the first
 400 CDROM device every second ad infinitum.
 401 .Pp
 402 .Dl iostat -c 2
 403 .Pp
 404 Display the statistics for the first four devices in the system twice, with
 405 a one second display interval.
 406 .Pp
 407 .Dl iostat -t da -t cd -w 1
 408 .Pp
 409 Display statistics for all CDROM and Direct Access devices every second
 410 ad infinitum.
 411 .Pp
 412 .Dl iostat -t da,scsi,pass -t cd,scsi,pass
 413 .Pp
 414 Display statistics once for all SCSI passthrough devices that provide access
 415 to either Direct Access or CDROM devices.
 416 .Pp
 417 .Dl iostat -h -n 8 -w 1
 418 .Pp
 419 Display up to 8 devices with the most I/O every second ad infinitum.
 420 .Pp
 421 .Dl iostat -dh -t da -w 1
 422 .Pp
 423 Omit the TTY and CPU displays, show devices in order of performance and
 424 show only Direct Access devices every second ad infinitum.
 425 .Pp
 426 .Dl iostat -Iw 3
 427 .Pp
 428 Display total statistics every three seconds ad infinitum.
 429 .Pp
 430 .Dl iostat -odICTw 2 -c 9
 431 .Pp
 432 Display total statistics using the old-style output format 9 times, with
 433 a two second interval between each measurement/display.
 434 The
 435 .Fl d
 436 flag generally disables the TTY and CPU displays, but since the
 437 .Fl T
 438 and
 439 .Fl C
 440 flags are given, the TTY and CPU displays will be displayed.
 441 .Sh SEE ALSO
 442 .Xr fstat 1 ,
 443 .Xr netstat 1 ,
 444 .Xr nfsstat 1 ,
 445 .Xr ps 1 ,
 446 .Xr systat 1 ,
 447 .Xr devstat 3 ,
 448 .Xr gstat 8 ,
 449 .Xr pstat 8 ,
 450 .Xr vmstat 8
 451 .Pp
 452 The sections starting with ``Interpreting system activity'' in
 453 .%T "Installing and Operating 4.3BSD" .
 454 .Sh HISTORY
 455 This version of
 456 .Nm
 457 first appeared in
 458 .Fx 3.0 .
 459 .Sh AUTHORS
 460 .An Kenneth Merry Aq ken@FreeBSD.org
 461 .Sh BUGS
 462 The use of
 463 .Nm
 464 as a debugging tool for crash dumps is probably limited because there is
 465 currently no way to get statistics that only cover the time immediately before
 466 the crash.