system_cmds/iostat.tproj/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. Neither the name of the University nor the names of its contributors
  42 .\"    may be used to endorse or promote products derived from this software
  43 .\"    without specific prior written permission.
  44 .\"
  45 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  46 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  47 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  48 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  49 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  50 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  51 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  52 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  53 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  54 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  55 .\" SUCH DAMAGE.
  56 .\"
  57 .\"     @(#)iostat.8    8.1 (Berkeley) 6/6/93
  58 .\"
  59 .Dd May 22, 2015
  60 .Dt IOSTAT 8
  61 .Os
  62 .Sh NAME
  63 .Nm iostat
  64 .Nd report
  65 .Tn I/O
  66 statistics
  67 .Sh SYNOPSIS
  68 .Nm
  69 .Op Fl CUdKIoT?\&
  70 .Op Fl c Ar count
  71 .Op Fl n Ar devs
  72 .Op Fl w Ar wait
  73 .Op Ar drives
  74 .Sh DESCRIPTION
  75 The
  76 .Nm
  77 utility displays kernel
  78 .Tn I/O
  79 statistics on terminal, device and cpu operations.
  80 The first statistics that are printed are averaged over the system uptime.
  81 To get information about the current activity, a suitable wait time should
  82 be specified, so that the subsequent sets of printed statistics will be
  83 averaged over that time.
  84 .Pp
  85 The options are as follows:
  86 .Bl -tag -width flag
  87 .It Fl ?\&
  88 Display a usage statement and exit.
  89 .It Fl c
  90 Repeat the display
  91 .Ar count
  92 times.
  93 If no
  94 .Ar wait
  95 interval is specified, the default is 1 second.
  96 .It Fl C
  97 Display CPU statistics.
  98 This is on by default, unless
  99 .Fl d
 100 is specified.
 101 .It Fl d
 102 Display only device statistics.
 103 If this flag is turned on, only device statistics will be displayed, unless
 104 .Fl C
 105 or
 106 .Fl U
 107 or
 108 .Fl T
 109 is also specified to enable the display of CPU, load average or TTY statistics.
 110 .It Fl I
 111 Display total statistics for a given time period, rather than average
 112 statistics for each second during that time period.
 113 .It Fl K
 114 In the blocks transferred display (-o), display block count in kilobytes rather
 115 then the device native block size.
 116 .It Fl n
 117 Display up to
 118 .Ar devs
 119 number of devices.
 120 The
 121 .Nm
 122 utility will display fewer devices if there are not
 123 .Ar devs
 124 devices present.
 125 .It Fl o
 126 Display old-style
 127 .Nm
 128 device statistics.
 129 Sectors per second, transfers per second, and milliseconds per seek are
 130 displayed.
 131 If
 132 .Fl I
 133 is specified, total blocks/sectors, total transfers, and
 134 milliseconds per seek are displayed.
 135 .It Fl T
 136 Display TTY statistics.
 137 This is on by default, unless
 138 .Fl d
 139 is specified.
 140 .It Fl U
 141 Display system load averages.
 142 This is on by default, unless
 143 .Fl d
 144 is specified.
 145 .It Fl w
 146 Pause
 147 .Ar wait
 148 seconds between each display.
 149 If no repeat
 150 .Ar count
 151 is specified, the default is infinity.
 152 .El
 153 .Pp
 154 The
 155 .Nm
 156 utility displays its information in the following format:
 157 .Bl -tag -width flag
 158 .It tty
 159 .Bl -tag -width indent -compact
 160 .It tin
 161 characters read from terminals
 162 .It tout
 163 characters written to terminals
 164 .El
 165 .It devices
 166 Device operations.
 167 The header of the field is the device name and unit number.
 168 The
 169 .Nm
 170 utility
 171 will display as many devices as will fit in a standard 80 column screen, or
 172 the maximum number of devices in the system, whichever is smaller.
 173 If
 174 .Fl n
 175 is specified on the command line,
 176 .Nm
 177 will display the smaller of the
 178 requested number of devices, and the maximum number of devices in the system.
 179 To force
 180 .Nm
 181 to display specific drives, their names may be supplied on the command
 182 line.
 183 The
 184 .Nm
 185 utility
 186 will not display more devices than will fit in an 80 column screen, unless
 187 the
 188 .Fl n
 189 argument is given on the command line to specify a maximum number of
 190 devices to display, or the list of specified devices exceeds 80 columns.
 191 If fewer devices are specified on the command line than will fit in an 80
 192 column screen,
 193 .Nm
 194 will show only the specified devices.
 195 .Pp
 196 The standard
 197 .Nm
 198 device display shows the following statistics:
 199 .Pp
 200 .Bl -tag -width indent -compact
 201 .It KB/t
 202 kilobytes per transfer
 203 .It tps
 204 transfers per second
 205 .It MB/s
 206 megabytes per second
 207 .El
 208 .Pp
 209 The standard
 210 .Nm
 211 device display, with the
 212 .Fl I
 213 flag specified, shows the following statistics:
 214 .Pp
 215 .Bl -tag -width indent -compact
 216 .It KB/t
 217 kilobytes per transfer
 218 .It xfrs
 219 total number of transfers
 220 .It MB
 221 total number of megabytes transferred
 222 .El
 223 .Pp
 224 The old-style
 225 .Nm
 226 display (using
 227 .Fl o )
 228 shows the following statistics:
 229 .Pp
 230 .Bl -tag -width indent -compact
 231 .It sps
 232 sectors transferred per second
 233 .It tps
 234 transfers per second
 235 .It msps
 236 average milliseconds per transaction
 237 .El
 238 .Pp
 239 The old-style
 240 .Nm
 241 display, with the
 242 .Fl I
 243 flag specified, shows the following statistics:
 244 .Pp
 245 .Bl -tag -width indent -compact
 246 .It blk
 247 total blocks/sectors transferred
 248 .It xfr
 249 total transfers
 250 .It msps
 251 average milliseconds per transaction
 252 .El
 253 .It cpu
 254 .Bl -tag -width indent -compact
 255 .It \&us
 256 % of cpu time in user mode
 257 .It \&sy
 258 % of cpu time in system mode
 259 .It \&id
 260 % of cpu time in idle mode
 261 .El
 262 .El
 263 .Sh EXAMPLES
 264 .Dl iostat -w 1 disk0 disk2
 265 .Pp
 266 Display statistics for the first and third disk devices device every
 267 second ad infinitum.
 268 .Pp
 269 .Dl iostat -c 2
 270 .Pp
 271 Display the statistics for the first four devices in the system twice, with
 272 a one second display interval.
 273 .Pp
 274 .Dl iostat -Iw 3
 275 .Pp
 276 Display total statistics every three seconds ad infinitum.
 277 .Pp
 278 .Dl iostat -odICTw 2 -c 9
 279 .Pp
 280 Display total statistics using the old-style output format 9 times, with
 281 a two second interval between each measurement/display.
 282 The
 283 .Fl d
 284 flag generally disables the TTY and CPU displays, but since the
 285 .Fl T
 286 and
 287 .Fl C
 288 flags are given, the TTY and CPU displays will be displayed.
 289 .Sh SEE ALSO
 290 .Xr netstat 1 ,
 291 .Xr nfsstat 1 ,
 292 .Xr ps 1 ,
 293 .Xr top 1 ,
 294 .Xr vm_stat 1
 295 .Pp
 296 The sections starting with ``Interpreting system activity'' in
 297 .%T "Installing and Operating 4.3BSD" .
 298 .Sh HISTORY
 299 This version of
 300 .Nm
 301 first appeared in
 302 .Fx 3.0 .