diff.numastat.8b

diff -ruN numactl-2.0.8-rc5.orig/numastat.8 numactl-2.0.8-rc5.new/numastat.8
--- numactl-2.0.8-rc5.orig/numastat.8	2012-08-23 15:50:37.000000000 -0400
+++ numactl-2.0.8-rc5.new/numastat.8	2012-10-07 00:05:46.676484265 -0400
@@ -1,82 +1,155 @@
-.\" t
-.\" Copyright 2004 Andi Kleen, SuSE Labs.
-.\"
-.\" Permission is granted to make and distribute verbatim copies of this
-.\" manual provided the copyright notice and this permission notice are
-.\" preserved on all copies.
-.\"
-.\" Permission is granted to copy and distribute modified versions of this
-.\" manual under the conditions for verbatim copying, provided that the
-.\" entire resulting derived work is distributed under the terms of a
-.\" permission notice identical to this one.
-.\"
-.\" Since the Linux kernel and libraries are constantly changing, this
-.\" manual page may be incorrect or out-of-date.  The author(s) assume no
-.\" responsibility for errors or omissions, or for damages resulting from
-.\" the use of the information contained herein.
-.\"
-.\" Formatted or processed versions of this manual, if unaccompanied by
-.\" the source, must acknowledge the copyright and authors of this work.
-.TH NUMACTL 8 "Nov 2004" "SuSE Labs" "Linux Administrator's Manual"
-.SH NAME
-numastat \- Print statistics about NUMA memory allocation
-.SH SYNOPSIS
-numastat
-.SH DESCRIPTION
+.TH "numastat" "8" "1.0.0" "Bill Gray" "Administration"
+.SH "numastat"
+.LP
+\fBnumastat\fP \- Show per-NUMA-node memory statistics for processes and the operating system
+.SH "SYNTAX"
+.LP
+\fBnumastat\fP
+.br
+.LP
+\fBnumastat\fP [\fI\-V\fP]
+.br
+.LP
+\fBnumastat\fP [\fI\<PID>|<pattern>...\fP]
+.br
+.LP
+\fBnumastat\fP [\fI\-c\fP] [\fI\-m\fP] [\fI\-n\fP] [\fI\-p <PID>|<pattern>\fP] [\fI\-s[<node>]\fP] [\fI\-v\fP] [\fI\-z\fP] [\fI\<PID>|<pattern>...\fP]
+.br
+.SH "DESCRIPTION"
+.LP
 .B numastat
-displays NUMA allocations statistics from the kernel memory allocator.
-Each process has NUMA policies that specifies on which node pages
-are allocated. See
-.I set_mempolicy(2)
-or
-.I numactl(8)
-on details of the available policies.
-The numastat counters keep track on what nodes memory is finally allocated.
-
-The counters are separated for each node. Each count event is the allocation
-of a page of memory.
-
+with no command options or arguments at all, displays per-node NUMA hit and
+miss system statistics from the kernel memory allocator.  This default
+\fBnumastat\fP behavior is strictly compatible with the previous long-standing
+\fBnumastat\fP perl script, written by Andi Kleen.  The default \fBnumastat\fP
+statistics shows per-node numbers (in units of pages of memory) in these categories:
+.LP
 .B numa_hit
-is the number of allocations where an allocation was intended for
-that node and succeeded there.
-
+is memory successfully allocated on this node as intended.
+.LP
 .B numa_miss
-shows how often an allocation was intended for this node, but ended up
-on another node due to low memory.
-
+is memory allocated on this node despite the process preferring some different node. Each
+.I numa_miss
+has a
+.I numa_foreign
+on another node.
+.LP
 .B numa_foreign
-is the number of allocations that were intended for another node,
-but ended up on this node.  Each
+is memory intended for this node, but actually allocated on some different node.  Each
 .I numa_foreign
-event has a
+has a
 .I numa_miss
  on another node.
-
+.LP
  .B interleave_hit
-is the number of interleave policy allocations that were intended for a
-specific node and succeeded there.
-
+is interleaved memory successfully allocated on this node as intended.
+.LP
 .B local_node
-is incremented when a process running on the node allocated
-memory on the same node.
-
+is memory allocated on this node while a process was running on it.
+.LP
 .B other_node
-is incremented when a process running on another node allocated memory on that node.
-.SH SEE ALSO
-.I numactl(8)
-.I set_mempolicy(2)
-.I numa(3)
+is memory allocated on this node while a process was running on some other node.
+.LP
+Any supplied options or arguments with the \fBnumastat\fP command will
+significantly change both the content and the format of the display.  Specified
+options will cause display units to change to megabytes of memory, and will
+change other specific behaviors of \fBnumastat\fP as described below.
+.SH "OPTIONS"
+.LP
+.TP
+\fB\-c\fR
+Minimize table display width by dynamically shrinking column widths based on
+data contents.  With this option, amounts of memory will be rounded to the
+nearest megabyte (rather than the usual display with two decimal places).
+Column width and inter-column spacing will be somewhat unpredictable with this
+option, but the more dense display will be very useful on systems with many
+NUMA nodes.
+.TP
+\fB\-m\fR
+Show the meminfo-like system-wide memory usage information.  This option
+produces a per-node breakdown of memory usage information similar to that found
+in /proc/meminfo.
+.TP
+\fB\-n\fR
+Show the original \fBnumastat\fP statistics info.  This will show the same
+information as the default \fBnumastat\fP behavior but the units will be megabytes of
+memory, and there will be other formatting and layout changes versus the
+original \fBnumastat\fP behavior.
+.TP
+\fB\-p\fR <\fBPID\fP> or <\fBpattern\fP>
+Show per-node memory allocation information for the specified PID or pattern.
+If the \-p argument is only digits, it is assumed to be a numerical PID.  If
+the argument characters are not only digits, it is assumed to be a text
+fragment pattern to search for in process command lines.  For example,
+\fBnumastat -p qemu\fP will attempt to find and show information for processes
+with "qemu" in the command line.  Any command line arguments remaining after
+\fBnumastat\fP option flag processing is completed, are assumed to be
+additional <\fBPID\fP> or <\fBpattern\fP> process specifiers.  In this sense,
+the \fB\-p\fP option flag is optional: \fBnumastat qemu\fP is equivalent to
+\fBnumastat -p qemu\fP
+.TP
+\fB\-s[<node>]\fR
+Sort the table data in descending order before displaying it, so the biggest
+memory consumers are listed first.  With no specified <node>, the table will be
+sorted by the total column.  If the optional <node> argument is supplied, the
+data will be sorted by the <node> column.  Note that <node> must follow the
+\fB\-s\fP immediately with no intermediate white space (e.g., \fBnumastat
+\-s2\fP).
+.TP
+\fB\-v\fR
+Make some reports more verbose.  In particular, process information for
+multiple processes will display detailed information for each process.
+Normally when per-node information for multiple processes is displayed, only
+the total lines are shown.
+.TP
+\fB\-V\fR
+Display \fBnumastat\fP version information and exit.
+.TP
+\fB\-z\fR
+Skip display of table rows and columns of only zero valuess.  This can be used
+to greatly reduce the amount of uninteresting zero data on systems with many
+NUMA nodes.  Note that when rows or columns of zeros are still displayed with
+this option, that probably means there is at least one value in the row or
+column that is actually non-zero, but rounded to zero for display.
 .SH NOTES
-numastat output is only available on NUMA systems.
-
-numastat assumes the output terminal has a width of 80 characters
-and tries to format the output accordingly.
-.SH EXAMPLES
-.I watch -n1 numastat
+\fBnumastat\fP attempts to fold each table display so it will be conveniently
+readable on the output terminal.  Normally a terminal width of 80 characters is
+assumed.  When the \fBresize\fP command is available, \fBnumastat\fP attempts
+to dynamically determine and fine tune the output tty width from \fBresize\fP
+output.  If \fBnumastat\fP output is not to a tty, very long output lines can
+be produced, depending on how many NUMA nodes are present.  In all cases,
+output width can be explicitly specified via the \fBNUMASTAT_WIDTH\fP
+environment variable.  For example, \fBNUMASTAT_WIDTH=100  numastat\fP.  On
+systems with many NUMA nodes, \fBnumastat \-c \-z ....\fP can be very helpful
+to selectively reduce the amount of displayed information.
+.SH "ENVIRONMENT VARIABLES"
+.LP
+.TP
+NUMASTAT_WIDTH
+.SH "FILES"
+.LP
+\fI/proc/*/numa_maps\fP
+.br
+\fI/sys/devices/system/node/node*/meminfo\fP
+.br
+\fI/sys/devices/system/node/node*/numastat\fP
+.SH "EXAMPLES"
+.I numastat \-c \-z \-m \-n
+.br
+.I numastat \-czs libvirt kvm qemu
+.br
+.I watch \-n1 numastat
 .br
-.I watch -n1 --differences=accumulative numastat
-.SH FILES
-/sys/devices/system/node/node*/numastat
-.SH BUGS
-The output formatting on machines with a large number of nodes
-could be improved.
+.I watch \-n1 \-\-differences=cumulative numastat
+.SH "AUTHORS"
+.LP
+The original \fBnumastat\fP perl script was written circa 2003 by Andi Kleen
+<andi.kleen@intel.com>.  The current \fBnumastat\fP program was written in 2012
+by Bill Gray <bgray@redhat.com> to be compatible by default with the original,
+and to add options to display per-node system memory usage and per-node process
+memory allocation.
+.SH "SEE ALSO"
+.LP
+.BR numactl (8),
+.BR set_mempolicy( 2),
+.BR numa (3)