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