From 548d59833d0983a5b824f591a89ee330326e2f33 Mon Sep 17 00:00:00 2001
From: lethargo <lethargo@comcast.net>
Date: Wed, 15 Jul 2009 17:16:34 -0500
Subject: [PATCH] add smem man page

A while back Matthew Miller asked about a man page for smem.  Here is a proposed start of one.
---
 smem.8 | 157 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 smem.8

diff --git a/smem.8 b/smem.8
new file mode 100644
index 0000000..b66c789
--- /dev/null
+++ b/smem.8
@@ -0,0 +1,157 @@
+.TH SMEM 8 "07/09/2009" "" ""
+
+.SH NAME
+smem \- Report memory usage with shared memory divided proportionally.
+
+.SH SYNOPSIS
+.B smem
+.RI [ options ]
+
+.SH DESCRIPTION
+\fBsmem\fP reports physical memory usage, taking shared memory pages
+into account.  Unshared memory is reported as the USS (Unique Set Size).
+Shared memory is divided evenly among the processes sharing that memory.
+The unshared memory (USS) plus a process's proportion of shared memory
+is reported as the PSS (Proportional Set Size).  The USS and PSS only
+include physical memory usage.  They do not include memory that has been
+swapped out to disk.
+
+Memory can be reported by process, by user, by mapping, or system\-wide. 
+Both text mode and graphical output are available.
+
+.SH OPTIONS
+
+.SS GENERAL OPTIONS
+
+.TP
+.B \-h, \-\-help
+Show help.
+
+.SS SOURCE DATA
+By default, smem will pull most of the data it needs from the /proc
+filesystem of the system it is running on.  The \-\-source option lets
+you used a tarred set of /proc data saved earlier, possibly on a
+different machine.  The \-\-kernel and \-\-realmem options let you
+specify a couple things that smem cannot discover on its own.
+
+.TP
+.BI "\-K " KERNEL ", \-\-kernel=" KERNEL
+Path to kernel image.  This lets smem include the size of the kernel's
+code and statically allocated data in the systemwide (-w) output.
+
+.TP
+.BI "\-R " REALMEM ", \-\-realmem=" REALMEM
+Amount of physical RAM.  This lets smem detect the amount of memory used
+by firmware/hardware in the systemwide (-w) output.  If provided, it
+will also be used as the total memory size to base percentages on.
+
+.TP
+.BI "\-S " SOURCE ", \-\-source=" SOURCE
+/proc data source.  This lets you specify an alternate source of the
+/proc data.  For example, you can capture data from an embedded system
+using smemcap, and parse the data later on a different machine.  If the
+\-\-source option is not included, smem reports memory usage on the
+running system.
+
+.SS REPORT BY
+If none of the following options are include, smem reports memory usage
+by process.
+
+.TP
+.B \-m, \-\-mappings
+Report memory usage by mapping.
+
+.TP
+.B \-u, \-\-users
+Report memory usage by user.
+
+.TP
+.B \-w, \-\-system
+Report systemwide memory usage summary.
+
+.SS FILTER BY
+If none of these options are included, memory usage is reported for all
+processes, users, or mappings.  (Note: If you are running as a non-root
+user, and if you are not using the \-\-source options, then you will
+only see data from processes whose /proc/ information you have access
+to.)
+
+.TP
+.BI "\-M " MAPFILTER ", \-\-mapfilter=" MAPFILTER
+Mapping filter regular expression.
+
+.TP
+.BI "\-P " PROCESSFILTER ", \-\-processfilter=" PROCESSFILTER
+Process filter regular expression.
+
+.TP
+.BI "\-U " USERFILTER ", \-\-userfilter=" USERFILTER
+User filter regular expression.
+
+.SS OUTPUT FORMATTING
+
+.TP
+.BI "\-c " COLUMNS ", \-\-columns=" COLUMNS
+Columns to show.
+
+.TP
+.B \-H, \-\-no\-header
+Disable header line.
+
+.TP
+.B \-k, \-\-abbreviate
+Show unit suffixes.
+
+.TP
+.B \-n, \-\-numeric
+Show numeric user IDs instead of usernames.
+
+.TP
+.B \-p, \-\-percent
+Show percentages.
+
+.TP
+.B \-r, \-\-reverse
+Reverse sort.
+
+.TP
+.BI "\-s " SORT ", \-\-sort=" SORT
+Field to sort on.
+
+.TP
+.B \-t, \-\-totals
+Show totals.
+
+.SS OUTPUT TYPE
+These options specify graphical output styles.
+
+.TP
+.BI "\-\-bar=" BAR
+Show bar graph.
+
+.TP
+.BI "\-\-pie=" PIE
+Show pie graph.
+
+.PP
+
+.SH NOTES
+\fBsmem\fP requires a 2.6.27 or newer kernel.
+
+.SH FILES
+.I /proc/$pid/cmdline
+.PP
+.I /proc/$pid/smaps
+.PP
+.I /proc/$pid/stat
+.PP
+.I /proc/meminfo
+.PP
+.I /proc/version
+
+.SH "SEE ALSO"
+.BR free (1), pmap (1)
+
+.SH AUTHOR
+\fBsmem\fP was written by Matt Mackall.
+