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