Debian 3.9.10debian/3.9.10debian

1 files changed, 252 insertions, 0 deletions

diff --git a/man/man5/pmns.5 b/man/man5/pmns.5
new file mode 100644
index 0000000..6d6c82c
--- /dev/null
+++ b/man/man5/pmns.5
@@ -0,0 +1,252 @@
+'\"! tbl | mmdoc
+'\"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 PMNS 5 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmns\f1 \- the performance metrics name space
+.\" literals use .B or \f3
+.\" arguments use .I or \f2
+.SH SYNOPSIS
+.I $PCP_VAR_DIR/pmns
+.SH DESCRIPTION
+When using the Performance Metrics Programming Interface (PMAPI)
+of the Performance Co-Pilot (PCP),
+performance metrics are identified by an external name in a
+hierarchic Performance Metrics Name Space (PMNS), and an
+internal identifier, the Performance Metric Identifier (PMID).
+.PP
+A PMNS specifies the association between a metric's name and its PMID.
+.PP
+A PMNS is defined on one or more ASCII source files.
+.PP
+Loading of a PMNS is done by calling
+.BR pmLoadNameSpace (3)
+or
+.BR pmLoadASCIINameSpace (3).
+.PP
+By default duplicate PMIDs are not allowed in the PMNS,
+although
+.BR pmLoadASCIINameSpace (3)
+provides an alternative interface with user-defined control
+over the processing of duplicate PMIDs in the PMNS.
+The external format for a PMNS conforms to the syntax
+and semantics described in the following sections.
+.PP
+There is one default PMNS in the files below
+.IR $PCP_VAR_DIR/pmns ,
+although users and application developers are free to
+create and use alternate PMNS's.
+For an example of this, see
+the PCP Tutorial in
+.IR $PCP_DEMOS_DIR/Tutorial .
+.PP
+Although an application can call 
+.BR pmLoadNameSpace (3),
+normally this is only done directly for the 
+.B \-n
+command line option where an explicit root PMNS file is specified.
+Since PCP version 2 uses a distributed PMNS (see below), 
+an application can extract PMNS information from a
+host's PMCD or an archive.  If the PMNS source
+is a version 1 archive (see
+.BR PCPIntro (1)),
+however, 
+then the local PMNS will be loaded using the path specified by the 
+environment variable
+.BR PMNS_DEFAULT .
+.SH DISTRIBUTED PMNS
+In PCP version 1, the PMNS functions in the API all operated on
+a PMNS loaded locally from a file. Since PCP version 2, however,
+PMNS functions may get the PMNS information remotely from a PMCD
+or directly from the meta data of an archive.
+.SH PROCESSING FRAMEWORK
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+The PMNS specification is initially passed through
+.BR pmcpp (1).
+This means the following facilities may be used in the specification
+.IP + 3n
+C-style comments
+.IP + 3n
+.CW #include
+directives
+.IP + 3n 
+.CW #define
+directives and macro substitution
+.IP + 3n 
+conditional processing via 
+.CW #ifdef
+\&...
+.CW #endif ,
+etc.
+.PP
+When
+.BR pmcpp (1)
+is executed, the ``standard'' include directories are the current directory and
+.IR $PCP_VAR_DIR/pmns .
+.SH SYNTAX
+The general syntax for a non-leaf node in the PMNS is as follows
+.PP
+.ft CW
+.nf
+pathname {
+        name      [pmid]
+        ...
+}
+.fi
+.ft R
+.PP
+Where
+.CW pathname
+is the full pathname from the root of the PMNS to this non-leaf node,
+with each
+component in the pathname separated by a ``.''.
+The root node for the PMNS must have the special 
+name ``root'', but the common prefix ``root.'' must be omitted from
+all pathnames.
+Each component in the pathname must begin with an alphabetic character,
+and be followed by zero or
+more characters drawn from the alphabetics, the digits and the underscore
+``_'') character.
+For alphabetic characters in a pathname component, upper and lower case are distinguished.
+.PP
+Non-leaf nodes in the PMNS may be defined in any order.
+.PP
+The descendent nodes are defined by the set of
+.CW names ,
+relative to the
+.CW pathname
+of their parent non-leaf node.  For the descendent nodes, leaf
+nodes have a
+.CW pmid
+specification, non-leaf nodes do not.  The syntax for
+the
+.CW pmid
+specification has been chosen to help manage the allocation of
+PMIDs across disjoint and autonomous domains
+of administration and implementation.  Each
+.CW pmid
+consists of 3 integer
+parts, separated by colons, e.g. 14:27:11.  This hierarchic numbering
+scheme is intended to mirror the implementation hierarchy of
+performance metric domain, metrics cluster (data structure or
+operational similarity) and individual metric.  In practice, the
+two leading components are likely to be macros in the PMNS specification
+source, and
+.BR pmcpp (1)
+will convert the macros to integers.  These macros for
+the initial components of the
+.CW pmid
+are likely to be defined either in
+a standard include file, e.g. \c
+.IR $PCP_VAR_DIR/pmns/stdpmid ,
+or in the current source file.
+.PP
+To support dynamic metrics, where the existence of a metric is known to
+a PMDA, but not visible in the PMNS, a variant syntax for the
+.CW pmid
+is supported, namely a domain number followed by asterisks for the other
+components of the
+.CW pmid ,
+e.g. 14:*:*.
+The corresponding metric name forms the root of a subtree of dynamic
+metric names defined in the corresponding PMDA as identified by the domain
+number.
+.PP
+The current allocation of the high-order (PMD or domain) component
+of PMIDs is as follows.
+.TS
+box,center;
+c | c
+n | l.
+Range	Allocation
+_
+0	reserved
+_
+1-31	PMDAs from the PCP base product
+_
+32-39	Oracle
+_
+40-47	Sybase
+_
+48-55	Informix
+_
+56-58	SNMP Gateway PMDA
+_
+59-63	Linux PMDAs
+_
+64-69	ISV PMDAs
+_
+70-128	more PMDAs from the PCP base product
+_
+129-510	End-user PMDAs and demo PMDAs
+_
+511	RESERVED
+.TE
+.SH EXAMPLE
+.ft CW
+.nf
+#define KERNEL 1
+#define FOO 317
+root {
+    network
+    cpu
+    dynamic     FOO:*:*
+}
+
+#define NETWORK 26
+network {
+    intrate     KERNEL:NETWORK:1
+    packetrate
+}
+
+network.packetrate {
+    in          KERNEL:NETWORK:35
+    out         KERNEL:NETWORK:36
+}
+
+#define CPU 10
+cpu {
+    syscallrate KERNEL:CPU:10
+    util
+}
+
+#define USER 20
+#define SYSTEM 21
+#define IDLE 22
+
+cpu.util {
+    user        KERNEL:CPU:USER
+    sys         KERNEL:CPU:SYSTEM
+    idle        KERNEL:CPU:IDLE
+}
+.fi
+.ft R
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR pmcd (1),
+.BR pmcpp (1),
+.BR PCPIntro (3),
+.BR PMAPI (3),
+.BR pmErrStr (3),
+.BR pmGetConfig (3),
+.BR pmLoadASCIINameSpace (3),
+.BR pmLoadNameSpace (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).