1 files changed, 147 insertions, 0 deletions
diff --git a/man/retired/pmtop.1 b/man/retired/pmtop.1
new file mode 100644
index 0000000..14a3215
--- /dev/null
+++ b/man/retired/pmtop.1
@@ -0,0 +1,147 @@
+'\"macro stdmacro
+.TH PMTOP 1 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmtop\f1 \- report top process resource usage
+.SH SYNOPSIS
+\f3pmtop\f1
+[\f3\-h\f1 \f2host\f1]
+[\f3\-m\f1 \f2top\f1]
+[\f3\-p\f1 \f2spec,...\f1]
+[\f3\-s\f1 \f2samples\f1]
+[\f3\-t\f1 \f2interval\f1]
+[\f3\-w\f1]
+[\f3\-z\f1]
+[\f3\-Z\f1 \f2timezone\f1]
+.SH DESCRIPTION
+.B pmtop
+reports per-process resource usage statistics
+within the Performance Co-Pilot framework.
+It outputs the highest \f2top\f1 values for the process
+resources of cpu utilization, system calls per second,
+context switches per second, kilobytes of data written per second,
+kilobytes of data read per second and resident set size. 
+A subset of this information may be selected using the
+.B \-p
+option.
+.SH COMMAND LINE OPTIONS
+The command line options for
+.B pmtop
+are as follows:
+.TP
+\f3\-h\f1 \f2host\f1
+Fetch performance metrics from
+.BR pmcd (1)
+on
+.IR host ,
+rather than the default local:.
+.TP
+\f3\-m\f1 \f2top\f1
+Report the \f2top\f1 highest values for a particular process 
+resource category.
+The default is the top 5.
+.TP
+\f3\-p\f1 \f2spec,...\f1
+Print out the process resource categories specified in the list of
+\f2spec\f1s. The specification is constructed from a comma
+separated list of categories from the following set:
+\f3cpu\f1, \f3sysc\f1, \f3ctx\f1, \f3read\f1,
+\f3write\f1 and \f3rss\f1.
+For example, "\f3\-p\f1 \f3cpu,ctx,rss\f1", will show
+three reports for the categories of cpu utilization, context switches and
+resident memory. It will also only show the category columns
+of \f3CPU%\f1, \f3CTX\f1 and \f3RSS\f1. 
+The default is to display all the categories.
+.TP
+\f3\-s\f1 \f2samples\f1
+Determines how many samples (iterations) of process data
+are displayed.
+The default is to do an infinite number of samples.
+.TP
+\f3\-t\f1 \f2interval\f1
+This value is used to determine the interval between fetching
+process data and reporting it.
+The
+.I interval
+argument follows the syntax described in
+.BR PCPIntro (1),
+and in the simplest form may be an unsigned integer (the implied
+units in this case are seconds).
+The default is 2 seconds.
+.TP
+\f3\-w\f1
+Normally the report is truncated at the 80th column.
+This option relieves this restriction.
+.TP
+\f3\-Z\f1 \f2timezone\f1
+By default,
+.B pmtop
+reports the time of day according to the local timezone on the system where
+.B pmtop
+is run.  The
+.B \-Z
+option changes the default timezone to 
+.I timezone
+which should be in the format of the environment variable
+.B TZ
+as described in 
+.BR environ (5).
+.TP
+\f3\-z\f1
+Change the reporting timezone to the local timezone at the host that is the
+source of the performance metrics, as identified via the
+.B \-h
+option.
+.SH "REPORT FORMAT"
+.PP
+The report is divided up into a number of sections, one for each
+process category as specified by the 
+.B \-p
+option.
+This also affects which columns are displayed. 
+.P
+At the top of the CPU%, SYSCALLS and CTX sections 
+it specifies how much the top
+processes used of the resource compared with how much was
+used globally by all the processes over the interval. 
+For example, for the
+CPU utilization category looking at the top 5 processes, 
+a value of 90% indicates that the top 5 processes account
+for 90% of the cpu consumption, the other 10% is used by processes
+which are not shown. These other processes are either not
+in the top 5, started after the beginning of the interval or 
+exited before the end of the interval.  
+.PP
+The columns in the report should be interpreted as follows:
+.PP
+.TP 10
+.B PID
+Process ID.
+.TP
+.B CPU%
+Percentage of CPU Utilization.
+.TP
+.B SYSCALLS
+The number of system calls per second.
+.TP
+.B CTX
+The number of context switches per second.
+.TP
+.B WRITES
+The number of kilobytes of data written per second.
+.TP
+.B READS
+The number of kilobytes of data read per second.
+.TP
+.B RSS
+The current resident set size in kilobytes.
+.TP
+.B CMD
+The command and arguments, truncated so each line in the
+report is at most 80 columns (unless the
+.B \-w
+option is given).
+.SH SEE ALSO
+.BR pmcd (1),
+.BR pmem (1)
+and
+.BR pminfo (1).