Update various statements in vmstat(8) to match reality.

- The process stats are actually thread counts rather than process
  counts.
- Simplify various descriptions to remove mention of stats that are
  updated every 5 seconds (all VM related stats are now "instant",
  only the load average is updated every 5 seconds).
- Don't make any mention of special treatment for processes that have
  been active in the last 20 seconds.  We don't track that stat.
- Rework the description of active virtual memory.  Call it mapped
  virtual memory and explicitly point out it is not the same as the
  active page queue (which corresponds to "Active" in top(1)), and
  also hint at the possible bogusness of the value (e.g. if a process
  maps a single page out of a multiple GB file, the entire file's size
  is considered mapped).
- Simplify a few descriptions that implied their output was a value
  per interval.  All of the "rate" values are per-second rates scaled
  across the interval.
- Update a few comments for 'struct vmtotal' along similar lines.

Reported by:	mwlucas (indirectly)
Reviewed by:	kib
MFC after:	1 week
Differential Revision:	https://reviews.freebsd.org/D13905

1 files changed, 25 insertions, 20 deletions

diff --git a/usr.bin/vmstat/vmstat.8 b/usr.bin/vmstat/vmstat.8
index dd1a0c9f1bc5..f2ada37916f5 100644
--- a/usr.bin/vmstat/vmstat.8
+++ b/usr.bin/vmstat/vmstat.8
@@ -28,7 +28,7 @@
 .\"	@(#)vmstat.8	8.1 (Berkeley) 6/6/93
 .\" $FreeBSD$
 .\"
-.Dd November 19, 2015
+.Dd January 18, 2018
 .Dt VMSTAT 8
 .Os
 .Sh NAME
@@ -248,31 +248,39 @@ By default,
 displays the following information:
 .Bl -tag -width indent
 .It procs
-Information about the numbers of processes in various states.
+Information about the number of threads in various states:
 .Pp
 .Bl -tag -width indent -compact
 .It r
-in run queue
+running or in run queue
 .It b
 blocked for resources (i/o, paging, etc.)
 .It w
-runnable or short sleeper (< 20 secs) but swapped
+swapped out
 .El
 .It memory
 Information about the usage of virtual and real memory.
-Virtual pages (reported in units of 1024 bytes) are considered active if
-they belong to processes which are running or have run in the last 20
-seconds.
+.Pp
+Mapped virtual memory is a sum of all of the virtual pages belonging
+to mapped virtual memory objects.
+Note that the entire memory object's size is considered mapped even if
+only a subset of the object's pages are currently mapped.
+This statistic is not related to the active page queue which is used to track
+real memory.
 .Pp
 .Bl -tag -width indent -compact
 .It avm
-active virtual pages
+mapped virtual memory
+.Po previously called active in
+.Nm
+output
+.Pc
 .It fre
 size of the free list
 .El
 .It page
 Information about page faults and paging activity.
-These are averaged each five seconds, and given in units per second.
+These are given in units per second.
 .Pp
 .Bl -tag -width indent -compact
 .It flt
@@ -286,11 +294,11 @@ pages paged in
 .It po
 pages paged out
 .It fr
-pages freed per second
+pages freed
 .\" .It de
 .\" anticipated short term memory shortfall
 .It sr
-pages scanned by clock algorithm, per-second
+pages scanned by page daemon
 .El
 .It disks
 Disk operations per second (this field is system dependent).
@@ -319,15 +327,15 @@ matching pattern is specified (see above),
 will only display the given devices or the devices matching the pattern,
 and will not randomly select other devices in the system.
 .It faults
-Trap/interrupt rate averages per second over last 5 seconds.
+Trap/interrupt rates per second.
 .Pp
 .Bl -tag -width indent -compact
 .It in
-device interrupts per interval (including clock interrupts)
+device interrupts (including clock interrupts)
 .It sy
-system calls per interval
+system calls
 .It cs
-cpu context switch rate (switches/interval)
+cpu context switches
 .El
 .It cpu
 Breakdown of percentage usage of CPU time.
@@ -336,7 +344,7 @@ Breakdown of percentage usage of CPU time.
 .It us
 user time for normal and low priority processes
 .It sy
-system time
+system and interrupt time
 .It id
 cpu idle
 .El
@@ -352,10 +360,7 @@ default memory file
 The command:
 .Dl vmstat -w 5
 will print what the system is doing every five
-seconds; this is a good choice of printing interval since this is how often
-some of the statistics are sampled in the system.
-Others vary every second and running the output for a while will make it
-apparent which are recomputed every second.
+seconds.
 .Pp
 The command:
 .Dl vmstat -p da -p cd -w 1