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