3 files changed, 647 insertions, 0 deletions
diff --git a/man/retired/pmdahotproc.1 b/man/retired/pmdahotproc.1
new file mode 100644
index 0000000..1311529
--- /dev/null
+++ b/man/retired/pmdahotproc.1
@@ -0,0 +1,315 @@
+'\"macro stdmacro
+.TH PMDAHOTPROC 1 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdahotproc\f1 \- Hot Proc performance metrics domain agent (PMDA)
+.SH SYNOPSIS
+\f3$PCP_PMDAS_DIR/hotproc/pmdahotproc\f1
+[\f3\-C\f1]
+[\f3\-d\f1 \f2domain\f1]
+[\f3\-l\f1 \f2logfile\f1]
+[\f3\-s\f1]
+[\f3\-t\f1 \f2interval\f1]
+[\f3\-U\f1 \f2username\f1]
+\f2configfile\f1
+.br
+.SH DESCRIPTION
+.B pmdahotproc
+is a Performance Metrics Domain Agent (PMDA) which exports
+.B proc 
+performance metrics from an instance domain of processes restricted
+to an "interesting" or "hot" set. Unlike the 
+.B proc 
+PMDA which has an instance domain equal to the current processes,
+.B pmdahotproc
+has an instance domain which is a subset of this and is
+determined by a configuration file and a refresh interval. 
+.P
+As well as
+the
+.B proc
+metrics, 
+.B pmdahotproc
+provides a \f3cpuburn\f1 metric which specifies the cpu utilization
+of the process over the refresh interval, \f3total\f1 metrics which
+indicate how much of the cpu that the "interesting" processes are
+accounting for, \f3predicate\f1 metrics which show the values of
+the reserved variables (see below) that
+are being used in the hotproc predicate and \f3control\f1 metrics
+for controlling the agent.
+.PP
+A brief description of the
+.B pmdahotproc
+command line options follows:
+.TP 5
+.B \-C
+Parse
+.IR configfile ,
+report any errors and exit.
+.TP 5
+.B \-d
+It is absolutely crucial that the performance metrics
+.I domain
+number specified here is unique and consistent.
+That is,
+.I domain
+should be different for every PMDA on the one host, and the same
+.I domain
+number should be used for the same PMDA on all hosts.
+.TP 5
+.B \-l
+Location of the log file.  By default, a log file named
+.I hotproc.log
+is written in the current directory of
+.BR pmcd (1)
+when
+.B pmdahotproc
+is started, i.e.
+.BR $PCP_LOG_DIR/pmcd .
+If the log file cannot
+be created or is not writable, output is written to the standard error instead.
+.TP 5
+.B \-s
+With this option, attempts to change the agent configuration by
+modifying the values of
+\f3hotproc.control.refresh\f1 and \f3hotproc.control.config\f1 using 
+.BR pmstore(1)
+will not be permitted.
+Without this option, storing into these \f3hotproc.control\f1 metrics will
+be permitted.
+.TP 5
+.B \-t
+.B pmdahotproc
+will regenerate its interesting set of processes using the configuration
+predicate, once every
+.I interval
+period.
+The period is specified as a time interval using the syntax
+described in 
+.BR PCPIntro (1).
+The default
+.I interval
+is 60 seconds.
+.TP 5
+.B \-U
+User account under which to run the agent.
+The default is the unprivileged "pcp" account in current versions of PCP,
+but in older versions the superuser account ("root") was used by default.
+.SH CONFIGURATION
+The configuration file consists of one predicate used to determine if
+a process should be in the interesting set or not.
+.PP
+Example configurations files may be found at
+.B $PCP_PMDAS_DIR/hotproc/sample.conf
+and
+.B $PCP_PMDAS_DIR/hotproc/general.conf .
+.PP
+The predicate is described
+using the language specified below. The symbols are based on those
+used by 
+.BR c (1) 
+and 
+.BR awk (1) .
+.TP 
+Boolean Connectives
+.B &&
+(and),
+.B ||
+(or),
+.B !
+(not),
+.B ()
+(precedence overriding)
+.TP 
+Number comparators
+.B <
+,
+.B <=
+,
+.B >
+,
+.B >=
+,
+.B ==
+,
+.B !=
+.TP 
+String comparators
+.B ==
+,
+.B !=
+.TP 
+String/Pattern comparators
+.B ~
+(string matches pattern)
+,
+.B !~
+(string does not match pattern)
+.TP 
+Reserved variables
+.B uid
+(user id; type integer)
+.B uname
+(user name; type string),
+.B gid
+(group id; type integer)
+.B gname
+(group name; type string),
+.B fname
+(process file name; type string),
+.B psargs
+(process file name with args; type string),
+.B cpuburn
+(cpu utilization; type float),
+.B iodemand
+(I/O demand - Kbytes read/written per second; type float),
+.B ctxswitch
+(number of context switches per second; type float),
+.B syscalls
+(number of system calls per second; type float),
+.B virtualsize
+(virtual size in Kbytes; type float),
+.B residentsize
+(resident size in Kbytes; type float),
+.B iowait
+(blocked and raw io wait in secs/sec; type float),
+.B schedwait
+(time waiting in run queue in secs/sec; type float).
+.TP
+Literal values
+.B 1234
+(positive integer),
+.B 0.35
+(positive float),
+\f3"foobar"\f1
+(string; delimited by \f3"\f1),
+.B /[fF](o)+bar/
+(pattern; delimited by \f3/\f1),
+.B true
+(boolean),
+.B false
+(boolean)
+.TP
+Comments
+.B #this is a comment
+(from \f3#\f1 to the end of the line).
+.TP
+Examples
+  cpuburn > 0.2 # cpu utilization of more than 20%
+  cpuburn > 0.2 && uname == "root"
+  cpuburn > 0.2 && (uname == "root" || uname == "hot")
+  psargs ~ /pmda/ && cpuburn > 0.4
+
+.PP
+The \f3hotproc.predicate\f1 metrics may be used
+to see what the values of the reserved variables are
+that were used by the predicate at the last refresh.
+They do not cover the reserved variables which are
+already exported elsewhere. A \f3hotproc.predicate\f1 metric
+may not have a value if it is not referenced in the configuration
+predicate. 
+ 
+
+.SH INSTALLATION
+If you want access to the names, help text and values for the Hotproc
+performance metrics, do the following as root:
+.PP
+.ft CW
+.nf
+.in +0.5i
+# cd $PCP_PMDAS_DIR/hotproc
+# ./Install
+.in
+.fi
+.ft 1
+.PP
+If you want to undo the installation, do the following as root:
+.PP
+.ft CW
+.nf
+.in +0.5i
+# cd $PCP_PMDAS_DIR/hotproc
+# ./Remove
+.in
+.fi
+.ft 1
+.PP
+.B pmdahotproc
+is launched by
+.BR pmcd (1)
+and should never be executed directly.
+The Install and Remove scripts notify
+.BR pmcd (1)
+when the agent is installed or removed.
+.SH FILES
+.PD 0
+.TP 10
+.B $PCP_PMCDCONF_PATH
+command line options used to launch
+.B pmdahotproc
+.TP 10
+.B /tmp/pcp.ttymap
+tty map file used for hotproc.psinfo.ttyname
+.TP 10
+.B $PCP_PMDAS_DIR/hotproc/help
+default help text file for the Hotproc metrics
+.TP 10
+.B $PCP_PMDAS_DIR/hotproc/Install
+installation script for the
+.B pmdahotproc
+agent
+.TP 10
+.B $PCP_PMDAS_DIR/hotproc/Remove
+undo installation script for the 
+.B pmdahotproc
+agent
+.TP 10
+.B $PCP_PMDAS_DIR/hotproc/sample.conf
+simple sample configuration (this is the default one)
+.TP 10
+.B $PCP_PMDAS_DIR/hotproc/general.conf
+another sample configuration that identifies "interesting"
+processes from several different classes.
+.TP 10
+.B $PCP_VAR_DIR/config/hotproc/hotproc.conf
+predicate configuration file from the most recent installation
+of the
+.B pmdahotproc
+agent
+.TP 10
+.B $PCP_LOG_DIR/pmcd/hotproc.log
+default log file for error messages and other information from
+.B pmdahotproc
+.PD
+.SH "PCP ENVIRONMENT"
+Environment variables with the prefix
+.B PCP_
+are used to parameterize the file and directory names
+used by PCP.
+On each installation, the file
+.B /etc/pcp.conf
+contains the local values for these variables.
+The
+.B $PCP_CONF
+variable may be used to specify an alternative
+configuration file,
+as described in
+.BR pcp.conf (5).
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR pmcd (1)
+and
+.BR pmstore (1).
+.SH CAVEATS
+Some of the required metrics may not be available on some platforms and these
+will generate an error
+message on startup.
+.P
+The values for hotproc.psinfo.ttyname are extracted from 
+.B /tmp/pcp.ttymap
+which is created on the very first fetch of proc.psinfo.ttyname or 
+hotproc.psinfo.ttyname.
+If new tty's are created past the high-water mark in /dev, then
+this file will be out of date. To fix this, 
+.B /tmp/pcp.ttymap 
+should be removed and pmcd restarted ($PCP_RC_DIR/pcp start); 
+this will create a new tty map file.
diff --git a/man/retired/pmnscomp.1 b/man/retired/pmnscomp.1
new file mode 100644
index 0000000..48923eb
--- /dev/null
+++ b/man/retired/pmnscomp.1
@@ -0,0 +1,185 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000-2004 Silicon Graphics, Inc.  All Rights Reserved.
+.\" 
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of the GNU General Public License as published by the
+.\" Free Software Foundation; either version 2 of the License, or (at your
+.\" option) any later version.
+.\" 
+.\" This program is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+.\" for more details.
+.\" 
+.\"
+.TH PMNSCOMP 1 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmnscomp\f1 \- compile an ASCII performance metrics namespace into binary format.
+.\" literals use .B or \f3
+.\" arguments use .I or \f2
+.SH SYNOPSIS
+\f3pmnscomp\f1
+[\f3\-d\f1]
+[\f3\-f\f1]
+[\f3\-n\f1 \f2namespace\f1]
+[\f3\-v\f1 \f2version\f1]
+\f2outfile\f1
+.SH DESCRIPTION
+.B pmnscomp
+compiles a Performance Metrics Name Space (PMNS) in ASCII format into a more
+efficient binary representation.
+.BR pmLoadNameSpace (3)
+is able to load this binary representation significantly faster than the
+equivalent ASCII representation.
+.PP
+If
+.I outfile
+already exists
+.B pmnscomp
+will exit without overwriting it.
+.PP
+By convention, the name of the compiled namespace is that of the root file of
+the ASCII namespace, with
+.B .bin
+appended.  For example, the root of the default PMNS is a file named
+.B root
+and the compiled version of the entire namespace is
+.BR root.bin .
+.PP
+The options are;
+.TP 5
+.B \-d
+By default the PMNS to be compiled is expected to contain at most one
+name for each unique Performance Metric Id (PMID).  The
+.B \-d
+option relaxes this restriction and allows the compilation of a
+PMNS in which multiple names may be associated with a single PMID.
+Duplicate names are useful when a particular metric may
+be logically associated with more than one group of related metrics,
+or when it is desired to create abbreviated aliases to name a set
+of frequently used metrics.
+.TP
+.B \-f
+Force overwriting of an existing
+.I outfile
+if it already exists.
+.TP
+.B \-n
+Normally
+.B pmnscomp
+operates on the default PMNS, however if the
+.B \-n
+option is specified an alternative namespace is loaded
+from the file
+.IR namespace.
+.TP
+.B \-v
+By default,
+.B pmnscomp
+writes a version
+.B 2
+compiled namespace.
+If
+.I version
+is
+.B 1
+then
+.B pmnscomp
+will write a version
+.B 1
+namespace which is similar to version
+.BR 2 ,
+without the extra integrity afforded by checksums.
+Note that PCP version 2.0 or later can handle both versions
+.B 1
+and
+.B 2
+of the binary PMNS format.
+.PP
+The default input PMNS is found in the file
+.I $PCP_VAR_DIR/pmns/root
+unless the environment variable
+.B PMNS_DEFAULT
+is set, in which case the value is assumed to be the pathname
+to the file containing the default input PMNS.
+.SH CAVEAT
+Once the writing of the new
+.I outfile
+has begun, the signals SIGINT, SIGHUP and SIGTERM will be ignored
+to protect the integrity of the new file.
+.SH FILES
+.PD 0
+.TP 10
+.I $PCP_VAR_DIR/pmns/*
+default PMNS specification files
+.TP
+.I $PCP_VAR_DIR/pmns/root.bin
+compiled version of the default PMNS, when the environment variable
+.B PMNS_DEFAULT
+is unset
+.TP
+.I $PCP_VAR_DIR/pmns/stdpmid
+some standard macros for PMID generation
+.PD
+.SH "PCP ENVIRONMENT"
+Environment variables with the prefix
+.B PCP_
+are used to parameterize the file and directory names
+used by PCP.
+On each installation, the file
+.I /etc/pcp.conf
+contains the local values for these variables.
+The
+.B $PCP_CONF
+variable may be used to specify an alternative
+configuration file,
+as described in
+.BR pcp.conf (5).
+.SH SEE ALSO
+.BR pmnsadd (1),
+.BR pmnsdel (1),
+.BR pmnsmerge (1),
+.BR PMAPI (3),
+.BR pmLoadNameSpace (3),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR pmns (5).
+.SH DIAGNOSTICS
+Cannot open ``xyz'' \- the filename for the root of the PMNS that was
+passed to
+.BR pmLoadNameSpace (3)
+is bogus.
+.PP
+Illegal PMID \- either one of the three PMID components (see
+.BR pmns (5))
+is not an integer, or the value for one of the 
+components is negative, or too large.
+.PP
+Expected ... \- specific syntax errors when a particular type of
+lexical symbol was expected and
+not found; the messages are intended to be self-explanatory.
+.PP
+Internal botch \- implementation problem for the parser ... 
+.PP
+Duplicate name ``abc'' in subtree for ``pqr.xyz'' \- for each non-leaf
+node, the names of all immediate descendents must be unique.
+.PP
+No name space entry for ``root'' \- the special non-leaf node with a pathname
+of ``root'' defines the root of the PMNS, and must appear
+somewhere in the PMNS specification.
+.PP
+Multiple name space entries for ``root'' \- more than one ``root'' node
+does not make sense!
+.PP
+Disconnected subtree (``abc.xyz.def'') in name space \- the pathname
+for this non-leaf node does not correspond to any pathname in the PMNS,
+hence this non-leaf node is ``orphaned'' in the PMNS.
+.PP
+Cannot find definition for non-terminal node ``xyz'' in name space \- a
+non-terminal node is named as part of its parent's specification, but
+is never defined.
+.PP
+Duplicate metric id (xxx) in name space for metrics ``abc'' and ``xyz''
+\- each PMID must be unique across the PMNS.
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).