usr.bin/vmstat/vmstat.8

   1 .\" Copyright (c) 1986, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 .\"     @(#)vmstat.8    8.1 (Berkeley) 6/6/93
  29 .\" $FreeBSD: src/usr.bin/vmstat/vmstat.8,v 1.16.2.5 2001/08/16 13:17:13 ru Exp $
  30 .\" $DragonFly: src/usr.bin/vmstat/vmstat.8,v 1.6 2008/09/02 11:50:46 matthias Exp $
  31 .\"
  32 .Dd May 30, 2013
  33 .Dt VMSTAT 8
  34 .Os
  35 .Sh NAME
  36 .Nm vmstat
  37 .Nd report virtual memory statistics
  38 .Sh SYNOPSIS
  39 .Nm
  40 .\" .Op Fl bfimst
  41 .Op Fl imsuvz
  42 .Op Fl c Ar count
  43 .Op Fl M Ar core
  44 .Op Fl N Ar system
  45 .Op Fl w Ar wait
  46 .Op Fl n Ar devs
  47 .Oo
  48 .Fl p
  49 .Sm off
  50 .Ar type , if , pass
  51 .Sm on
  52 .Oc
  53 .Op Ar disks
  54 .Sh DESCRIPTION
  55 .Nm Vmstat
  56 reports certain kernel statistics kept about process, virtual memory,
  57 disk, trap and cpu activity.
  58 .Pp
  59 The options are as follows:
  60 .Bl -tag -width indent
  61 .It Fl b
  62 Formatted numbers use a brief format which some may find
  63 more readable with looped output.
  64 .It Fl c
  65 Repeat the display
  66 .Ar count
  67 times.
  68 The first display is for the time since a reboot and each subsequent
  69 report is for the time period since the last display.
  70 If no repeat
  71 .Ar count
  72 is specified, and
  73 .Fl w
  74 is specified, the default is infinity, otherwise the default is one.
  75 .\" .It Fl f
  76 .\" Report on the number
  77 .\" .Xr fork 2
  78 .\" and
  79 .\" .Xr vfork 2
  80 .\" system calls since system startup, and the number of pages of virtual memory
  81 .\" involved in each.
  82 .It Fl i
  83 Report on the number of interrupts taken by each device since system
  84 startup.
  85 .It Fl M
  86 Extract values associated with the name list from the specified
  87 .Ar core
  88 instead of the default
  89 .Pa /dev/kmem .
  90 .It Fl N
  91 Extract the name list from the specified
  92 .Ar system
  93 instead of the default
  94 .Pa /boot/kernel .
  95 .It Fl m
  96 Report on the usage of kernel dynamic memory listed first by size of
  97 allocation and then by type of usage.
  98 .It Fl n
  99 Change the maximum number of disks to display from the default of 2.
 100 .It Fl p
 101 Specify which types of devices to display.  There are three different
 102 categories of devices:
 103 .Pp
 104 .Bl -tag -width indent -compact
 105 .It device type:
 106 .Bl -tag -width 9n -compact
 107 .It da
 108 Direct Access devices
 109 .It sa
 110 Sequential Access devices
 111 .It printer
 112 Printers
 113 .It proc
 114 Processor devices
 115 .It worm
 116 Write Once Read Multiple devices
 117 .It cd
 118 CD devices
 119 .It scanner
 120 Scanner devices
 121 .It optical
 122 Optical Memory devices
 123 .It changer
 124 Medium Changer devices
 125 .It comm
 126 Communication devices
 127 .It array
 128 Storage Array devices
 129 .It enclosure
 130 Enclosure Services devices
 131 .It floppy
 132 Floppy devices
 133 .El
 134 .Pp
 135 .It interface:
 136 .Bl -tag -width 9n -compact
 137 .It IDE
 138 Integrated Drive Electronics devices
 139 .It SCSI
 140 Small Computer System Interface devices
 141 .It other
 142 Any other device interface
 143 .El
 144 .Pp
 145 .It passthrough:
 146 .Bl -tag -width 9n -compact
 147 .It pass
 148 Passthrough devices
 149 .El
 150 .El
 151 .Pp
 152 The user must specify at least one device type, and may specify at most
 153 one device type from each category.  Multiple device types in a single
 154 device type statement must be separated by commas.
 155 .Pp
 156 Any number of
 157 .Fl p
 158 arguments may be specified on the command line.  All
 159 .Fl p
 160 arguments are ORed together to form a matching expression against which
 161 all devices in the system are compared.  Any device that fully matches
 162 any
 163 .Fl p
 164 argument will be included in the
 165 .Nm
 166 output, up to three devices, or the maximum number of devices specified
 167 by the user.
 168 .It Fl s
 169 Display the contents of the
 170 .Em sum
 171 structure, giving the total number of several kinds of paging related
 172 events which have occurred since system startup.
 173 .\" .It Fl t
 174 .\" Report on the number of page in and page reclaims since system startup,
 175 .\" and the amount of time required by each.
 176 .It Fl u
 177 Output unformatted numeric values, suitable for field extraction and
 178 numeric sorting.
 179 Columnar output will not be nicely aligned.
 180 .It Fl v
 181 If specified together with
 182 .Fl i ,
 183 include IRQ numbers and IRQ target CPU numbers before device names.
 184 .It Fl w
 185 Pause
 186 .Ar wait
 187 seconds between each display.
 188 If no repeat
 189 .Ar wait
 190 interval is specified, the default is 1 second.
 191 .It Fl z
 192 Report on memory used by the kernel zone allocator, by zone.
 193 The information shown is the same as that returned by the
 194 .Va vm.zone
 195 sysctl variable.
 196 .El
 197 .Pp
 198 By default,
 199 .Nm
 200 displays the following information:
 201 .Bl -tag -width indent
 202 .It procs
 203 Information about the numbers of processes in various states.
 204 .Pp
 205 .Bl -tag -width indent -compact
 206 .It r
 207 in run queue
 208 .It b
 209 blocked for resources (i/o, paging, etc.)
 210 .It w
 211 runnable or short sleeper (< 20 secs) but swapped
 212 .El
 213 .It memory
 214 Information about the usage of virtual and real memory.
 215 Virtual pages (reported in units of 1024 bytes) are considered active if
 216 they belong to processes which are running or have run in the last 20
 217 seconds.
 218 .Pp
 219 .Bl -tag -width indent -compact
 220 .It fre
 221 Approximate free and easily-freeable memory.
 222 .El
 223 .It page
 224 Information about page faults and paging activity.
 225 These are averaged each five seconds, and given in units per second.
 226 .Pp
 227 .Bl -tag -width indent -compact
 228 .It flt
 229 total number of page faults
 230 .It re
 231 page reclaims (simulating reference bits)
 232 .\" .It at
 233 .\" pages attached (found in free list)
 234 .It pi
 235 pages paged in
 236 .It po
 237 pages paged out
 238 .It fr
 239 pages freed per second
 240 .\" .It de
 241 .\" anticipated short term memory shortfall
 242 .El
 243 .It disks
 244 Disk operations per second (this field is system dependent).
 245 Typically paging will be split across the available drives.
 246 The header of the field is the first two characters of the disk name and
 247 the unit number.
 248 If more than three disk drives are configured in the system,
 249 .Nm
 250 displays only the first three drives, unless the user specifies the
 251 .Fl n
 252 argument to increase the number of drives displayed.  This will probably
 253 cause the display to exceed 80 columns, however.
 254 To force
 255 .Nm
 256 to display specific drives, their names may be supplied on the command line.
 257 .Nm
 258 defaults to show disks first, and then various other random devices in the
 259 system to add up to three devices, if there are that many devices in the
 260 system.  If devices are specified on the command line, or if a device type
 261 matching pattern is specified (see above),
 262 .Nm
 263 will only display the given devices or the devices matching the pattern,
 264 and will not randomly select other devices in the system.
 265 .It faults
 266 Trap/interrupt rate averages per second over last 5 seconds.
 267 .Pp
 268 .Bl -tag -width indent -compact
 269 .It int
 270 device interrupts per interval (including clock interrupts)
 271 .It sys
 272 system calls per interval
 273 .It ctx
 274 cpu context switch rate (switches/interval)
 275 .El
 276 .It cpu
 277 Breakdown of percentage usage of CPU time.
 278 .Pp
 279 .Bl -tag -width indent -compact
 280 .It us
 281 user time for normal and low priority processes
 282 .It sy
 283 system time
 284 .It id
 285 cpu idle
 286 .El
 287 .El
 288 .Sh FILES
 289 .Bl -tag -width /dev/kmemxxx -compact
 290 .It Pa /boot/kernel
 291 default kernel namelist
 292 .It Pa /dev/kmem
 293 default memory file
 294 .El
 295 .Sh EXAMPLES
 296 The command:
 297 .Dl vmstat -w 5
 298 will print what the system is doing every five
 299 seconds; this is a good choice of printing interval since this is how often
 300 some of the statistics are sampled in the system.
 301 Others vary every second and running the output for a while will make it
 302 apparent which are recomputed every second.
 303 .Pp
 304 The command:
 305 .Dl vmstat -p da -p cd -w 1
 306 will tell vmstat to select the first three direct access or CDROM devices
 307 and display statistics on those devices, as well as other systems
 308 statistics every second.
 309 .Sh SEE ALSO
 310 .Xr fstat 1 ,
 311 .Xr netstat 1 ,
 312 .Xr nfsstat 1 ,
 313 .Xr ps 1 ,
 314 .Xr systat 1 ,
 315 .Xr iostat 8 ,
 316 .Xr pstat 8 ,
 317 .Xr sysctl 8
 318 .Pp
 319 The sections starting with ``Interpreting system activity'' in
 320 .%T "Installing and Operating 4.3BSD" .
 321 .Sh BUGS
 322 The
 323 .Fl c
 324 and
 325 .Fl w
 326 options are only available with the default output.