Documentation
¶
Overview ¶
Package vmstat implements the vmstat builtin command.
vmstat — report virtual memory, swap, IO, and CPU pressure statistics
Usage: vmstat [OPTION]... [delay [count]]
With no arguments, prints a single snapshot averaged since boot. With a delay and count (whole seconds / positive row count), samples repeatedly, printing a since-boot average as the first row and true deltas between samples thereafter. Sampling must be count-bounded and its total wait time may not exceed 29 seconds.
Counter collection is delegated to the internal vmstat package, which reads /proc/{stat,meminfo,vmstat,loadavg} on Linux (exempt from the AllowedPaths sandbox — same documented exception used by df, ss, and ip route: the paths are hardcoded and never derived from user input) and sysctl(3) on macOS (hw.memsize, vm.swapusage, vm.loadavg — the same darwin toolset already used by df and ss). See builtins/internal/vmstat's package doc for the full platform-coverage rationale.
Platform limitations ¶
macOS has no sysctl exposing per-page memory breakdown (buffers/cache/ active/inactive beyond totals), CPU tick counters, or paging/interrupt/ context-switch counters without a Mach host_statistics64 call, which this implementation intentionally does not make (see the internal package doc). On macOS those columns print as "-" when the whole counter group is unavailable (procs/swap-rate/io/system/cpu); memory and swap totals print normally.
Accepted flags:
-a, --active
Display active/inactive memory instead of buffers/cache.
-w, --wide
Use wider field widths (avoids truncating large numbers).
-S, --unit=k|K|m|M
Scale memory and swap-rate columns: k=1000 bytes, K=1024
(default), m=1e6, M=2^20.
-s, --stats
Print a full set of event counters, one label per line, instead
of the column report. Ignores delay/count.
-h, --help
Print usage to stdout and exit 0.
Rejected flags (intentionally not registered, rejected as unknown by pflag with exit 1):
-d, -p — disk/partition statistics; not implemented in v1.
-f — fork counts since boot; not implemented in v1.
-m — slab info; not implemented in v1.
-t — timestamp column; not implemented in v1.
-n — single-header mode; not meaningful (every invocation is
already a single process).
-V, --version — not meaningful in this shell.
Exit codes:
0 Success — a report was written. 1 Error — unsupported platform, unknown flag, extra operand, or failure to read counters.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Cmd = builtins.Command{
Name: "vmstat",
Description: "report virtual memory, swap, IO, and CPU pressure statistics",
MakeFlags: makeFlags,
}
Cmd is the vmstat builtin command descriptor.
var ProcPath = procpath.Default
ProcPath is the proc filesystem root passed to ivmstat.Read. It is a package-level variable so tests can point it at a synthetic directory instead of the real /proc.
Concurrency contract: this variable is written only in tests and is never mutated by production code after package initialization. Test code that mutates ProcPath must hold a test-package-level mutex for the duration of the test to prevent data races between concurrent test goroutines.
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files