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