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