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