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