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 October 21, 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 allocated using
 113 .Xr malloc 9
 114 by type.
 115 .It Fl n
 116 Change the maximum number of disks to display from the default of 2.
 117 .It Fl p
 118 Specify which types of devices to display.
 119 There are three different
 120 categories of devices:
 121 .Pp
 122 .Bl -tag -width indent -compact
 123 .It device type:
 124 .Bl -tag -width 9n -compact
 125 .It da
 126 Direct Access devices
 127 .It sa
 128 Sequential Access devices
 129 .It printer
 130 Printers
 131 .It proc
 132 Processor devices
 133 .It worm
 134 Write Once Read Multiple devices
 135 .It cd
 136 CD devices
 137 .It scanner
 138 Scanner devices
 139 .It optical
 140 Optical Memory devices
 141 .It changer
 142 Medium Changer devices
 143 .It comm
 144 Communication devices
 145 .It array
 146 Storage Array devices
 147 .It enclosure
 148 Enclosure Services devices
 149 .It floppy
 150 Floppy devices
 151 .El
 152 .Pp
 153 .It interface:
 154 .Bl -tag -width 9n -compact
 155 .It IDE
 156 Integrated Drive Electronics devices
 157 .It SCSI
 158 Small Computer System Interface devices
 159 .It other
 160 Any other device interface
 161 .El
 162 .Pp
 163 .It passthrough:
 164 .Bl -tag -width 9n -compact
 165 .It pass
 166 Passthrough devices
 167 .El
 168 .El
 169 .Pp
 170 The user must specify at least one device type, and may specify at most
 171 one device type from each category.
 172 Multiple device types in a single
 173 device type statement must be separated by commas.
 174 .Pp
 175 Any number of
 176 .Fl p
 177 arguments may be specified on the command line.
 178 All
 179 .Fl p
 180 arguments are ORed together to form a matching expression against which
 181 all devices in the system are compared.
 182 Any device that fully matches
 183 any
 184 .Fl p
 185 argument will be included in the
 186 .Nm
 187 output, up to two devices, or the maximum number of devices specified
 188 by the user.
 189 .It Fl s
 190 Display the contents of the
 191 .Em sum
 192 structure, giving the total number of several kinds of paging related
 193 events which have occurred since system startup.
 194 .\" .It Fl t
 195 .\" Report on the number of page in and page reclaims since system startup,
 196 .\" and the amount of time required by each.
 197 .It Fl w
 198 Pause
 199 .Ar wait
 200 seconds between each display.
 201 If no repeat
 202 .Ar wait
 203 interval is specified, the default is 1 second.
 204 .It Fl z
 205 Report on memory used by the kernel zone allocator,
 206 .Xr uma 9 ,
 207 by zone.
 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 libmemstat 3 ,
 337 .Xr gstat 8 ,
 338 .Xr iostat 8 ,
 339 .Xr pstat 8 ,
 340 .Xr sysctl 8 ,
 341 .Xr malloc 9 ,
 342 .Xr uma 9
 343 .Pp
 344 The sections starting with ``Interpreting system activity'' in
 345 .%T "Installing and Operating 4.3BSD" .
 346 .Sh BUGS
 347 The
 348 .Fl c
 349 and
 350 .Fl w
 351 options are only available with the default output.