Debian 3.9.10debian/3.9.10debian

136 files changed, 19226 insertions, 0 deletions

diff --git a/man/man3/GNUmakefile b/man/man3/GNUmakefile
new file mode 100644
index 0000000..f2ef6e4
--- /dev/null
+++ b/man/man3/GNUmakefile
@@ -0,0 +1,36 @@
+#
+# Copyright (c) 2013-2014 Red Hat.
+# 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.
+#
+
+TOPDIR = ../..
+include $(TOPDIR)/src/include/builddefs
+-include ./GNUlocaldefs
+
+MAN_SECTION	= 3
+MAN_PAGES	= $(shell echo *.3)
+MAN_DEST	= $(PCP_MAN_DIR)/man$(MAN_SECTION)
+LSRCFILES	= $(MAN_PAGES)
+
+default :: $(MAN_PAGES)
+
+default_pcp : $(MAN_PAGES)
+
+include $(BUILDRULES)
+
+install :: install_pcp
+
+install_pcp : default
+	$(INSTALL_MAN)
+
+
diff --git a/man/man3/QMC.3 b/man/man3/QMC.3
new file mode 100644
index 0000000..5add074
--- /dev/null
+++ b/man/man3/QMC.3
@@ -0,0 +1,50 @@
+'\"macro stdmacro
+.\" Copyright (c) 2005 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 QMC 3 "SGI" "Performance Co-Pilot"
+.SH NAME
+\f3QMC\f1 \- library for managing groups of Performance Co-Pilot metrics
+.SH "C++ SYNOPSIS"
+.ft 3
+#include <QMC.h>
+.sp
+CC ... \-lqmc \-lpcp 
+.ft 1
+.SH DESCRIPTION
+The Qt-based Performance Metrics Class
+.RB ( QMC )
+class library is a collection of C++ classes for managing a large set of
+performance metrics from a variety of sources.  This library is built over
+.BR PMAPI (3).
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR QmcContext (3),
+.BR QmcDesc (3),
+.BR QmcGroup (3),
+.BR QmcIndom (3),
+.BR QmcMetric (3),
+.BR QmcSource (3),
+.BR pmflush (3)
+and
+.BR pmprintf (3).
+.SH DIAGNOSTICS
+Error messages are generated using
+.BR pmprintf (3)
+but are not flushed. It is the responsibility of the user to call
+.BR pmflush (3)
+to output any messages.
+.PP
+Additional diagnostics may be activated by adding 
+.B DBG_TRACE_PMC
+to the global
+.IR pmDebug .
diff --git a/man/man3/QmcContext.3 b/man/man3/QmcContext.3
new file mode 100644
index 0000000..9e6be22
--- /dev/null
+++ b/man/man3/QmcContext.3
@@ -0,0 +1,132 @@
+'\"macro stdmacro
+.\" Copyright (c) 2005 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 QMC_CONTEXT 3 "SGI" "Performance Co-Pilot"
+.SH NAME
+\f3QmcContext\f1 \- container for a PMAPI context and its metrics
+.SH "C++ SYNOPSIS"
+.ft 3
+#include <QmcContext.h>
+.sp
+CC ... \-lqmc \-lpcp 
+.ft 1
+.SH DESCRIPTION
+A
+.B QmcContext
+object is a container for a single 
+.BR PMAPI (3)
+context.  The object maintains a list of all the metric descriptors
+.RB ( QmcDesc ),
+instance domains
+.RB ( QmcIndom )
+and
+metrics
+.RB ( QmcMetric )
+using the context to minimize the duplication of these objects.
+.SH "CONSTRUCTORS"
+A
+.B QmcContext
+object should be constructed through the
+.B QmcGroup::use
+interface.
+.SH "DESCRIPTOR LOOKUP"
+The metric and instance domain descriptors are cached by the
+.B QmcContext
+object to reduce duplicate
+.BR QmcDesc (3)
+and
+.BR QmcIndom (3)
+objects and
+.BR PMAPI (3)
+calls required to create them.  Also the mapping from metrics names to 
+.BR pmID s
+is also maintained to avoid
+.BR pmLookupName (3)
+calls.
+.TP 4
+.B "int lookupDesc(const char *name, pmID& id);"
+Search for the metric
+.I name
+in the name list and set 
+.B id
+to the known
+.BR pmID .
+If not found, use
+.BR pmLookupName (3)
+to get the mapping.  If this call fails, the
+.BR PMAPI (3)
+error code will be returned.
+.TP
+.B "int lookupDesc(const char *name, uint_t& desc, uint_t& indom);"
+Find the index 
+.I desc
+and
+.I indom
+to the
+.B QmcDesc
+object and the
+.B QmcIndom
+object for the metric 
+.IR name .
+The indexes can then be used with 
+.B QmcContext::desc
+and
+.B QmcContext::indom
+to obtain references to the real objects.
+The methods will return a
+.BR PMAPI (3)
+error code if the metric descriptor or instance domain could not be obtained.
+.TP
+.B "int lookupDesc(pmID pmid, uint_t& desc, uint_t& indom);"
+Find the index 
+.I desc
+and
+.I indom
+to the
+.B QmcDesc
+object and the
+.B QmcIndom
+object for the metric
+.IR pmid .
+The indexes can then be used with 
+.B QmcContext::desc
+and
+.B QmcContext::indom
+to obtain references to the real objects.
+The methods will return a
+.BR PMAPI (3)
+error code if the metric descriptor or instance domain could not be obtained.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR QMC (3),
+.BR QmcDesc (3),
+.BR QmcGroup (3),
+.BR QmcIndom (3),
+.BR QmcMetric (3),
+.BR pmflush (3),
+.BR pmLookupName (3)
+and
+.BR pmprintf (3).
+.SH DIAGNOSTICS
+Error messages are generated using
+.BR pmprintf (3)
+but are not flushed. It is the responsibility of the user to call
+.BR pmflush (3)
+to output any messages.
+.PP
+Additional diagnostics may be activated by adding 
+.B DBG_TRACE_PMC
+and
+.B DBG_TRACE_OPTFETCH
+to the global
+.IR pmDebug .
diff --git a/man/man3/QmcDesc.3 b/man/man3/QmcDesc.3
new file mode 100644
index 0000000..0269554
--- /dev/null
+++ b/man/man3/QmcDesc.3
@@ -0,0 +1,96 @@
+'\"macro stdmacro
+.\" Copyright (c) 2005 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 QMC_DESC 3 "SGI" "Performance Co-Pilot"
+.SH NAME
+\f3QmcDesc\f1 \- container for a metric description
+.SH "C++ SYNOPSIS"
+.ft 3
+#include <QmcDesc.h>
+.sp
+CC ... \-lqmc \-lpcp 
+.ft 1
+.SH DESCRIPTION
+A
+.B QmcDesc
+object is a container for a metric descriptor 
+.RB ( pmDesc ", see " PMAPI (3))
+and units.
+.SH "CONSTRUCTORS & DESTRUCTOR"
+.TP 4
+.B "~QmcDesc();"
+Destructor.
+.TP
+.B "QmcDesc(pmID pmid);"
+Construct a container for the descriptor for 
+.IR pmid .
+The descriptor is obtained from the current
+.BR PMAPI (3)
+context using
+.BR pmLookupDesc (3).
+.SH DESCRIPTION
+.TP 4
+.B "int status() const;"
+A status less than zero indicates that the descriptor could not be obtained,
+the
+.BR PMAPI (3)
+error is encoded in the result.
+.TP
+.B "pmID id() const;"
+Return the
+.B pmID
+for this descriptor.
+.TP
+.B "pmDesc desc() const;"
+Return a copy of the actual metric descriptor.
+.TP
+.B "const pmDesc *descPtr() const;"
+Return a pointer to the actual descriptor to avoid using a pointer to a
+temporary.
+.SH UNITS
+.TP 4
+.B "const QString &units() const;"
+The complete unit string for this descriptor.
+.TP
+.B "const QString &abvUnits() const;"
+The unit string using abbreviations.
+.TP
+.B "bool useScaleUnits() const;"
+Returns
+.B true
+if the units have been set by a call to
+.BR QmcDesc::setScaleUnits .
+.TP
+.B "const pmUnits &scaleUnits() const;"
+Return the scaling units for this descriptor.
+.TP
+.B "void setScaleUnits(const pmUnits &units);"
+Set the scaling units for this descriptor.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR QMC (3),
+.BR pmflush (3),
+.BR pmLookupDesc (3)
+and
+.BR pmprintf (3).
+.SH DIAGNOSTICS
+Error messages are generated using
+.BR pmprintf (3)
+but are not flushed. It is the responsibility of the user to call
+.BR pmflush (3)
+to output any messages.
+.PP
+Additional diagnostics may be activated by adding
+.B DBG_TRACE_PMC
+to the global
+.IR pmDebug .
diff --git a/man/man3/QmcGroup.3 b/man/man3/QmcGroup.3
new file mode 100644
index 0000000..0784aee
--- /dev/null
+++ b/man/man3/QmcGroup.3
@@ -0,0 +1,257 @@
+'\"macro stdmacro
+.\" Copyright (c) 2005 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 QMC_GROUP 3 "SGI" "Performance Co-Pilot"
+.SH NAME
+\f3QmcGroup\f1 \- container representing a single fetch group of metrics from
+multiple sources
+.SH "C++ SYNOPSIS"
+.ft 3
+#include <QmcGroup.h>
+.sp
+CC ... \-lqmc \-lpcp 
+.ft 1
+.SH DESCRIPTION
+A
+.B QmcGroup
+object is a container for contexts and metrics that should be fetched at
+the same time.  The class manages the 
+.BR QmcContext (3)
+objects, timezones and bounds for every context created with
+.B QmcGroup::use
+and
+.BR QmcGroup::addMetric .
+.SH "CONSTRUCTORS & DESTRUCTOR"
+.TP 4
+.B "~QmcGroup();"
+Destructor which destroys all metrics and contexts created by this group.
+.TP
+.B "QmcGroup(bool restrictArchives = false);"
+Construct a new fetch group. 
+.I restrictArchives
+will restrict the creating of multiple archive contexts created from the same
+host.
+.SH "CONTEXTS"
+The default context of the group is defined as the first context created with 
+.B QmcGroup::use 
+before the first call to
+.BR QmcGroup::addMetric .
+If no context is created before the first metric is added, the localhost
+is used as the default context.  Therefore, if any metrics specifications
+contain archive sources, an archive source must have been created with
+.B QmcGroup::use
+to avoid an error for mixing context types.
+.TP 4
+.B "uint_t numContexts() const;"
+The number of valid contexts created in this group.
+.TP
+.B "QmcContext const& context(uint_t index) const"
+Return a handle to a context.
+.TP
+.B "QmcContext& context(uint_t index);"
+Return a modifiable handle to a context.
+.TP
+.B "int mode() const;"
+Return the type of context, either
+.BR PM_CONTEXT_LOCAL ,
+.B PM_CONTEXT_HOST
+or
+.BR PM_CONTEXT_ARCHIVE .
+.TP
+.B "QmcContext* which() const;"
+Return a handle to the current context of this group. This does not
+call
+.BR pmUseContext (3)
+so it may not be the current
+.BR PMAPI (3)
+context.
+.TP
+.B "uint_t whichIndex() const"
+The index to the current group context.
+.TP
+.B "int use(int type, char const* source);"
+Use the context of 
+.I type
+from
+.IR source .
+If a context to this 
+.I source
+already exists in this group, that context will become the current
+.BR PMAPI (3)
+context.  Otherwise a new context will be created.  The result is the
+.BR PMAPI (3)
+context handle
+for the
+.B QmcGroup::context
+or a
+.BR PMAPI (3)
+error code if the context failed.
+.TP
+.B "bool defaultDefined() const;"
+Returns 
+.B true
+if a default context has been determined.
+.TP
+.B "int useDefault();"
+Use the default context. If a default context has not been created, the
+context to the local host will be attempted.  A result less than zero indicates
+that the method failed with the 
+.BR PMAPI (3)
+error encoded in the result.
+.TP
+.B "void createLocalContext();"
+Create and use a context to the local host.  A result less than zero indicates
+that the method failed with the 
+.BR PMAPI (3)
+error encoded in the result.
+.SH "METRICS"
+These 
+.B addMetric
+methods should be used to create new metrics as the 
+.B QmcMetric
+constructors are private. These methods will always return a pointer to
+a
+.B QmcMetric
+object, however the
+.B QmcMetric::status()
+field should be checked to ensure the metric is valid.
+.TP 4
+.B "QmcMetric* addMetric(char const* str, double theScale = 0.0,"
+.B "bool active = false);"
+
+Add the metric
+.I str
+to the group, with a scaling factor of
+.IR scale .
+If 
+.I active
+is set the metric will use only active instances (see
+.BR QmcMetric (3)).
+.TP
+.B "QmcMetric* addMetric(pmMetricSpec* theMetric, double theScale"
+.B "= 0.0, bool active);"
+
+Add the metric
+.I theMetric
+to the group, with a scaling factor of
+.IR scale .
+If 
+.I active
+is set the metric will use only active instances (see
+.BR QmcMetric (3)).
+.TP
+.B "int fetch(bool update = true);"
+Fetch all the metrics in all the contexts in this group.  If
+.I update
+is equal to
+.BR true ,
+all counter metrics will be automatically converted to rates (see
+.BR QmcMetric (3)).
+.TP
+.B "int setArchiveMode(int mode, const struct timeval *when,"
+.B "int interval);"
+
+Set the mode and time to access all archive contexts in this group.  See
+.BR pmSetmode (3)
+for more details.
+.SH TIMEZONES
+These methods assist in the management of multiple timezones and help to
+control the current timezone.
+.TP 4
+.B "enum TimeZoneFlag { localTZ, userTZ, groupTZ, unknownTZ };"
+Enumeration used to describe the origin of the default timezone.
+.BR localTZ ,
+.B userTZ
+and
+.B groupTZ
+indicate that the timezone was set with
+.BR "QmcGroup::useLocalTZ" ,
+.BR "QmcGroup::useTZ(QString const&)"
+and
+.BR "QmcGroup::useTZ()"
+respectively.
+.B unknownTZ
+indicates that a timezone has not been set.
+.B userTZ
+indicates that the timezone was
+.TP
+.B "int useTZ();"
+Use the timezone of the current group context as the default.
+.TP
+.B "int useTZ(const QString &tz);"
+Add and use
+.I tz
+as the default timezone of this group.
+.TP
+.B "int useLocalTZ();"
+Use the timezone of the localhost as the default for this group.
+.TP
+.B "void defaultTZ(QString &label, QString &tz);"
+Return the
+.I label
+and
+.I tz
+string of the default timezone of this group.
+.TP
+.B "TimeZoneFlag defaultTZ() const"
+Return the origin of the default timezone.
+.TP
+.B "int useDefaultTZ();"
+Set the timezone to be the default timezone as defined in a previous call
+to 
+.B QmcGroup::useTZ
+or
+.BR QmcGroup::useLocalTZ . 
+.TP
+.B "struct timeval const& logStart() const;"
+Return the earliest starting time of any archives in this group.  Assumes that
+.B QmcGroup::updateBounds
+has been called.
+.TP
+.B "struct timeval const& logEnd() const;"
+Return the latest finish time of any archives in this group.  Assumes that
+.B QmcGroup::updateBounds
+has been called.
+.TP
+.B "void updateBounds();"
+Determine the earliest start and latest finish times of all archives in this
+group.
+.TP
+.B "int sendTimezones();"
+Send the current timezones to
+.B kmtime (3).
+.SH "DEBUGGING"
+.TP 4
+.B "void dump(ostream &os);"
+Dump state information about this group to 
+.IR os .
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR QMC (3),
+.BR QmcContext (3),
+.BR QmcMetric (3),
+.BR pmflush (3),
+.BR pmprintf (3)
+and
+.BR pmSetMode (3).
+.SH DIAGNOSTICS
+Error messages are generated using
+.BR pmprintf (3)
+but are not flushed. It is the responsibility of the user to call
+.BR pmflush (3)
+to output any messages.
+.PP
+Additional diagnostics may be activated by adding 
+.B DBG_TRACE_PMC
+to the global
+.IR pmDebug .
diff --git a/man/man3/QmcIndom.3 b/man/man3/QmcIndom.3
new file mode 100644
index 0000000..4c54a0e
--- /dev/null
+++ b/man/man3/QmcIndom.3
@@ -0,0 +1,200 @@
+'\"macro stdmacro
+.\" Copyright (c) 2005 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 QMC_INDOM 3 "SGI" "Performance Co-Pilot"
+.SH NAME
+\f3QmcIndom\f1 \- container for a instance domain description
+.SH "C++ SYNOPSIS"
+.ft 3
+#include <QmcIndom.h>
+.sp
+CC ... \-lqmc \-lpcp 
+.ft 1
+.SH DESCRIPTION
+A
+.B QmcIndom
+object represents a
+.BR PMAPI (3)
+instance domain.  This includes a description of all the instances
+in the instance domain.
+.PP
+A
+.B QmcInstance
+is a structure used to describe each instance in the instance domain.  This
+includes:
+.PP
+.in 1.0i
+- internal identifier. If this is less than zero, the instance is treated as a
+NULL entry in the instance table.
+
+- external name
+
+- reference count, ie. the number of
+.B QmcMetric
+objects referring to this instance.
+
+- the likely position of the instance in the
+.B pmResult
+from a 
+.BR pmFetch (3).
+This is also used to indicate the position of the next NULL instance
+in the instance table, if this entry is also NULL.
+
+- a flag indicating if the instance was in the last
+.BR pmGetInDom (3).
+.in
+.PP
+The 
+.B QmcIndom
+object has a list of
+.B QmcInstance
+structures, and various flags and counters to support dynamic instance domains
+where instances may come and go with each fetch and efficient profile
+generation.
+.in
+.SH CONSTRUCTORS
+.TP 4
+.B "QmcIndom::QmcIndom(int type, QmcDesc &desc);"
+Calls 
+.BR pmGetInDom (3)
+and
+.BR pmGetInDomArchive (3)
+for host and archive contexts to obtain the entire instance list for the
+instance domain of
+.I type
+and identified in
+.IR desc .
+.SH "DYNAMIC INDOMS"
+The support of dynamic instance domains for live contexts is complex since many
+metrics may be referencing any of the instances in the domain.  Therefore the
+instance list may be sparse as the position of instances in the list must be maintained.
+.PP
+When the instance domain is updated, instances may be removed from the list if
+they are not in the new instance list (as returned by
+.BR pmGetInDom (3))
+and is not referenced by any metrics. Each instance in the new list is then
+compared with the old list to determine which instances are still active, and
+any new instances need to be added.  An instance is considered the same if both
+the internal and external identifiers are the same.  New instances are first
+inserted into positions of deleted instances before being appended to the list.
+.PP
+This algorithm is expensive (potentially O(N^2)).
+.TP 4
+.B "bool changed() const;"
+Returns 
+.B true
+if the instance domain may have changed in the last fetch.
+.TP
+.B "void newFetch();"
+Reset the flags that may have indicated that the instance domain had changed.
+This is called by 
+.BR QmcContext::fetch .
+.TP
+.B "void hasChanged();"
+Set the flags to indicate that the instance domain may have changed.  This is
+called by
+.BR QmcMetric::extractValues .
+.TP
+.B "int update();"
+Update the instance domain as described above. On subsequent calls, before the
+next fetch, this method will remove any instances that are no longer referenced
+without updating the instance list with a
+.BR pmGetInDom (3)
+call.
+.TP
+.B "uint_t numInsts() const;"
+Returns the number of instances that are not NULL.
+.TP
+.B "uint_t numActiveInsts() const;"
+Returns the number of instances that are active according to the last
+.B QmcIndom::update
+call.
+.TP
+.B "uint_t listLen() const;"
+Returns the length of the instance list, including NULL instances.
+.SH "PROFILES"
+The algorithm for determining the most compact profile uses the number of
+instances
+.RB ( _instances.length() ),
+the number of referenced instances
+.RB ( _count ),
+the number of active instances
+.RB ( _numActive )
+and the number of referenced active instances
+.RB ( _numActiveRef ).
+.PP
+.in 1.5i
+.ft CW
+.nf
+if (all active instances are referenced
+    or there are no active instances)
+
+        request all instances implicitly
+
+else if (the number of referenced instances
+         is less than the number of active
+         instances that are not referenced)
+
+        delete all instances from profile
+        add all referenced instances
+
+else
+
+        add all instances to profile
+        delete all instances that are not referenced 
+.fi
+.ft R
+.in
+.TP 4
+.B "bool diffProfile() const;"
+Returns
+.B true
+if the profile has potentially changed since the last call to
+.BR QmcIndom::genProfile .
+.TP
+.B "int genProfile();"
+Generates a new profile for the instance domain. a
+.BR PMAPI (3)
+error code is returned if the profile failed.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR QMC (3),
+.BR QmcContext (3),
+.BR QmcDesc (3),
+.BR QmcMetric (3),
+.BR pmFetch (3),
+.BR pmflush (3),
+.BR pmGetInDom (3),
+.BR pmGetInDomArchive (3)
+and
+.BR pmprintf (3).
+.SH DIAGNOSTICS
+Error messages are generated using
+.BR pmprintf (3)
+but are not flushed. It is the responsibility of the user to call
+.BR pmflush (3)
+to output any messages.
+.PP
+Additional diagnostics may be activated by adding 
+.B DBG_TRACE_PMC
+and
+.B DBG_TRACE_INDOM
+to the global
+.IR pmDebug .
+.SH BUGS
+User's have no control over the algorithm used to generate the profile. In
+the case of 
+.I proc
+metrics, an implicit profile could be generated if all process instances are
+required, even though this will result in no values being returned in the
+fetch.
diff --git a/man/man3/QmcMetric.3 b/man/man3/QmcMetric.3
new file mode 100644
index 0000000..d0d9cb1
--- /dev/null
+++ b/man/man3/QmcMetric.3
@@ -0,0 +1,105 @@
+'\"macro stdmacro
+.\" Copyright (c) 2005 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 QMC_METRIC 3 "SGI" "Performance Co-Pilot"
+.SH NAME
+\f3QmcMetric\f1 \- container for a metric and all its values
+.SH "C++ SYNOPSIS"
+.ft 3
+#include <pcp/pmc/Metric.h>
+.sp
+CC ... \-lpcp_pmc \-lpcp 
+.ft 1
+.SH DESCRIPTION
+A
+.B QmcMetric
+object is a container for a single metric and all its values.
+.PP
+The
+.B QmcMetricValue
+structure is used to hold the instance index, values and errors of each
+instance.  In the case of a singular metric, a single
+.B QmcMetricValue
+object is used.
+.PP
+A
+.B QmcMetric
+object consists of a list of
+.B QmcMetricValue
+objects, indexes to the descriptors in the metric's
+.B QmcGroup
+and
+.B QmcContext
+and flags to indicate if the instances are explicit or implicit, and if
+only active metrics are required after 
+.B QmcMetric::updateIndom
+is called.
+.SH "CONSTRUCTORS"
+Metrics should be constructed through the
+.B QmcGroup::addMetric
+methods as this will ensure that the references to the metric's context,
+descriptor and instance domain are correctly initialized.
+.SH INSTANCES
+For metrics with an instance domain it is possible to add and remove any
+instance, and also update the instance list to reflect changes in a dynamic
+instance domain.
+.TP 4
+.B "bool updateIndom();"
+Update the metric to include new instances.  This method will first call
+.B QmcContext::update
+to update the instance domain.  If the
+.I active
+flag is set in the
+.B QmcGroup::addMetric
+call, only instances will exported by the metric, otherwise the metric will
+export all instances listed in the domain.
+
+The ordering of instances may change as a result of this call.  Instances
+that already existed will keep their current and previous values and errors,
+even if they are in a different order.
+.TP
+.B "int addInst(QString const& name);"
+Add the instance
+.B name
+to the metric.  If the instance does not exist in the instance domain,
+a 
+.BR PMAPI (3)
+error will be returned.  This method ignores the value of the
+.I active
+flag set in the
+.B QmcMetric
+constructor.
+.TP
+.B "void removeInst(uint_t index);"
+Remove the instance at position
+.I index 
+from the metric.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR QMC (3),
+.BR QMC_Context (3),
+.BR QMC_Group (3),
+.BR pmflush (3)
+and
+.BR pmprintf (3).
+.SH DIAGNOSTICS
+Error messages are generated using
+.BR pmprintf (3)
+but are not flushed. It is the responsibility of the user to call
+.BR pmflush (3)
+to output any messages.
+.PP
+Additional diagnostics may be activated by adding 
+.B DBG_TRACE_PMC
+to the global
+.IR pmDebug .
diff --git a/man/man3/QmcSource.3 b/man/man3/QmcSource.3
new file mode 100644
index 0000000..122b3f8
--- /dev/null
+++ b/man/man3/QmcSource.3
@@ -0,0 +1,120 @@
+'\"macro stdmacro
+.\" Copyright (c) 2005 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 QMC_SOURCE 3 "SGI" "Performance Co-Pilot"
+.SH NAME
+\f3QmcSource \f1 \- manages contexts created by all groups
+.SH "C++ SYNOPSIS"
+.ft 3
+#include <QmcSource.h>
+.sp
+CC ... \-lqmc \-lpcp 
+.ft 1
+.SH DESCRIPTION
+The
+.B QmcSource
+class maintains a unique list of all metric sources in use to minimize
+the creation of new contexts (see
+.BR pmNewContext (3))
+when the context could have been duplicated (see
+.BR pmDupContext (3)).
+This also reduces the duplication of descriptions of each source.
+.PP
+In general, 
+.B QMC
+users should only need to access
+.B QmcSource
+methods to obtain source descriptions for a
+.BR QmcContext (3)
+object.  All context creation by the user should be handled through
+.BR QmcGroup (3).
+.SH "DESTRUCTOR"
+.TP 4
+.B "~QmcSource();"
+Destructor.
+.SH "CONSTRUCTORS"
+.TP 4
+.B "static QmcSource* getSource(int type, const char* source,"
+.B "bool matchHosts)"
+
+This method will return a 
+.B QmcSource
+object that represents a context of
+.I type
+to
+.IR source .
+The 
+.B QmcSource
+object may be a new object if the
+.I source
+has not been previously requested. Memory management of the
+.B QmcSource
+objects is handled by 
+.BR QmcSource .
+If all
+.BR QmcContext (3)s
+to the 
+.B QmcSource
+have been deleted, the
+.B QmcSource
+object will also be deleted.
+
+The
+.I matchHosts
+flag controls the algorithm that is used to match hosts to archives.
+If 
+.I matchHosts
+is equal to
+.B false
+then no attempt will be made by this method to match a host context to an
+existing source context. A
+.B QmcSource
+object will always be returned in this case, although the
+.B QmcSource::status
+method may indicate that a context to 
+.I source
+failed.
+
+If
+.I matchHosts
+is equal to
+.BR true ,
+host contexts will be matched to a pre-defined archive source collected from
+that
+.IR source .
+If no archive sources for the
+.I source
+have been previous specified,
+.B getSource
+will return a NULL pointer.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR QMC (3),
+.BR QmcContext (3),
+.BR QmcGroup (3),
+.BR pmDupContext (3),
+.BR pmflush (3),
+.BR pmNewContext (3)
+and
+.BR pmprintf (3).
+.SH DIAGNOSTICS
+Error messages are generated using
+.BR pmprintf (3)
+but are not flushed. It is the responsibility of the user to call
+.BR pmflush (3)
+to output any messages.
+.PP
+Additional diagnostics may be activated by adding 
+.B DBG_TRACE_PMC
+to the global
+.IR pmDebug .
diff --git a/man/man3/logimport.3 b/man/man3/logimport.3
new file mode 100644
index 0000000..469c67f
--- /dev/null
+++ b/man/man3/logimport.3
@@ -0,0 +1,110 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 LOGIMPORT 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3LOGIMPORT\f1 \- introduction to the library for importing data and creating a PCP archive
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/import.h>
+.sp
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.ft 1
+.SH DESCRIPTION
+The Performance Co-Pilot Log Import (LOGIMPORT) API is a library (and Perl wrapper)
+that supports the creation of PCP archives from external sources of
+performance data, either in the form of historical logs and spreadsheets
+or from real-time sources that are
+.B not
+integrated as a Performance Metrics
+Domain Agent (PMDA) under the control of
+.BR pmcd (1).
+.PP
+The typical usage for LOGIMPORT would involve:
+.IP \(bu 3n
+An initial call to
+.BR pmiStart (3).
+.IP \(bu 3n
+Optional calls to
+.BR pmiSetHostname (3)
+and/or
+.BR pmiSetTimezone (3)
+to set the hostname and timezone for the source of the performance data.
+.IP \(bu 3n
+One or more calls to
+.BR pmiAddMetric (3)
+to define performance metrics.
+.IP \(bu 3n
+One or more calls to
+.BR pmiAddInstance (3)
+to define instances associated with the metrics.
+.IP \(bu 3n
+Optional calls to
+.BR pmiGetHandle (3)
+to defined convenience handles for metric-instance pairs.
+.IP \(bu 3n
+A main loop in which performance data is injested and for each
+sample time interval, the PCP archive record is constructed by calls
+to
+.BR pmiPutValue (3)
+and/or
+.BR pmiPutValueHandle (3),
+followed by a call to
+.BR pmiWrite (3)
+to flush all data and any associated new metadata
+to the PCP archive.  Alternatively,
+.BR pmiPutResult (3)
+could be used to package and process all the data for one sample time
+interval.
+.IP \(bu 3n
+Once the input source of data has been consumed, calling
+.BR pmiEnd (3)
+to complete the PCP archive creation and close all open files.
+.PP
+If new metrics and/or instances are discovered during the data
+injestion, these can be added by subsequent calls to
+.BR pmiAddMetric (3)
+and/or
+.BR pmiAddInstance (3),
+provided all the metrics and instances have been defined before
+a call to
+.BR pmiGetHandle (3),
+.BR pmiPutValue (3) or
+.BR pmiPutResult (3)
+that references those metrics and instances.
+.SH SEE ALSO
+.BR pmcd (1),
+.BR pmlogger (1),
+.BR pmiGetHandle (3),
+.BR pmiAddInstance (3),
+.BR pmiAddMetric (3),
+.BR pmiEnd (3),
+.BR pmiErrStr (3),
+.BR pmiPutResult (3),
+.BR pmiPutValue (3),
+.BR pmiPutValueHandle (3),
+.BR pmiSetHostname (3),
+.BR pmiSetTimezone (3),
+.BR pmiStart (3)
+and
+.BR pmiWrite (3).
diff --git a/man/man3/mmv_inc_value.3 b/man/man3/mmv_inc_value.3
new file mode 100644
index 0000000..5204aea
--- /dev/null
+++ b/man/man3/mmv_inc_value.3
@@ -0,0 +1,42 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2009 Max Matveev
+.\" Copyright (c) 2009 Aconex.  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 MMV_INC_VALUE 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3mmv_inc_value\f1 - update a value in a Memory Mapped Value file
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/mmv_stats.h>
+.sp
+void mmv_inc_value(void *\fIaddr\fP, pmAtomValue *\fIval\fP, double \fIinc\fP);
+.sp
+cc ... \-lpcp_mmv \-lpcp
+.ft 1
+.SH DESCRIPTION
+.P
+\f3mmv_inc_value\f1 provides a convenient way of updating a value 
+returned by the \f3mmv_lookup_value_desc\f1.
+\f2addr\f1 is the address returned from \f3mmv_stats_init\f1().
+.P
+The value of the \f2inc\f1 is internally cast to match the type of
+the metric and then added to the previous value of the metric.
+.SH SEE ALSO
+.BR mmv_stats_init (3),
+.BR mmv_lookup_value_desc (3)
+and
+.BR mmv (5).
diff --git a/man/man3/mmv_lookup_value_desc.3 b/man/man3/mmv_lookup_value_desc.3
new file mode 100644
index 0000000..ac7a5ad
--- /dev/null
+++ b/man/man3/mmv_lookup_value_desc.3
@@ -0,0 +1,69 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2009 Max Matveev
+.\" Copyright (c) 2009 Aconex.  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 MMV_LOOKUP_VALUE_DESC 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3mmv_lookup_value_desc\f1 - find a value in the Memory Mapped Value file
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/mmv_stats.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+pmAtomValue *mmv_lookup_value_desc(void *\fIaddr\fP, const char *\fImetric\fP, const\ char\ *\fIinst\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_mmv \-lpcp
+.ft 1
+.SH DESCRIPTION
+.P
+\f3mmv_lookup_value_desc\f1 searches for the value of the instance 
+identified by the external instance name \f2inst\f1 of the metric
+\f2metric\f1 in the \f3MMV\f1(5) file.
+\f2addr\f1 is the address returned from \f3mmv_stats_init\f1().
+.P
+The pointer returned points to a pmAtomValue union, which is
+defined as follows:
+.P
+.nf
+    typedef union {
+        __int32_t   l;      /* 32-bit signed */
+        __uint32_t  ul;     /* 32-bit unsigned */
+        __int64_t   ll;     /* 64-bit signed */
+        __uint64_t  ull;    /* 64-bit unsigned */
+        float       f;      /* 32-bit floating point */
+        double      d;      /* 64-bit floating point */
+        char         *cp;   /* char ptr */
+	pmValueBlock *vbp;  /* pmValueBlock ptr */
+    } pmAtomValue;
+.fi
+.P
+MMV string values should be set using either of the
+\f3mmv_set_string\f1 or \f3mmv_set_strlen\f1 routines.
+.SH RETURNS
+The function returns the address inside of the memory mapped region
+on success or NULL on failure.
+.SH SEE ALSO
+.BR mmv_stats_init (3),
+.BR mmv_inc_value (3)
+and
+.BR mmv (5).
diff --git a/man/man3/mmv_stats_init.3 b/man/man3/mmv_stats_init.3
new file mode 100644
index 0000000..216ed02
--- /dev/null
+++ b/man/man3/mmv_stats_init.3
@@ -0,0 +1,110 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2013 Red Hat.
+.\" Copyright (c) 2009 Max Matveev.
+.\" Copyright (c) 2009 Aconex.  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 MMV_STATS_INIT 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3mmv_stats_init\f1 - create and initialize Memory Mapped Value file
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/mmv_stats.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+void *mmv_stats_init(const char *\fIname\fP, int \fIcluster\fP, mmv_stats_flags_t\ \fIflags\fP, const\ mmv_metric_t\ *\fIstats\fP, int\ \fInstats\fP, mmv_indom_t\ *\fIindoms\fP, int\ \fInindoms\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_mmv \-lpcp
+.ft 1
+.SH DESCRIPTION
+.P
+\f3mmv_stats_init\f1 creates and initializes the content of the 
+\f2MMV\f1(5) file, returning a handle that is used in subsequent
+MMV API calls.
+.P
+\f3mmv_stats_stop\f1 performs an orderly shutdown of the mapping
+handle returned by an earlier initialization call.
+.P
+The file is created in the $PCP_TMP_DIR/mmv directory, \f2name\f1
+argument is expected to be a basename of the file, not the full path.
+The metadata content of the file does not change after the file has
+been created. 
+.P
+The old file is removed unconditionally unless there was an error.
+.P
+\f2cluster\f1 is the preferred MMV PMDA cluster ID to be used for
+the metrics originating from this call to \f3mmv_stats_init\f1.
+The \f2flags\f1 provide additional control over the behaviour
+of the MMV PMDA - e.g. use of MMV_FLAG_PROCESS will ensure values
+are only exported when the instrumented application is running \-
+this is verified on each request for new values.
+.P
+\f2stats\f1 is the array of \f3mmv_metric_t\f1 elements of length
+\f2nstats\f1. Each element of the array describes one PCP metric.
+.P
+.nf
+        typedef struct {
+            char name[MMV_NAMEMAX];     /* Name of the metric */
+            __uint32_t item;            /* Item component of PMID */
+            mmv_metric_type_t type;     /* Type of the metric */
+            mmv_metric_sem_t semantics; /* Semantics of the metric */
+            pmUnits dimension;          /* Dimensions (TIME,SPACE,etc) */
+            __uint32_t indom;           /* Instance domain identifier */
+            char *shorttext;            /* Optional, one-line help */
+            char *helptext;             /* Optional, full help text */
+        } mmv_metric_t;
+.fi
+.P
+If \f3indom\f1 is not zero and not PM_INDOM_NULL, then the metric has
+multiple values and there must be a corresponding \f2indom\f1 entry
+in the \f2indom\f1 list (uniquely identified by \f3serial\f1 number).
+.P
+The \f2stats\f1 array cannot contain any elements which have no name -
+this is considered an error and no metrics will be exported in this case.
+.P
+\f2indoms\f1 is the array of \f3mmv_indom_t\f1 elements of length
+\f2nindoms\f1. Each element of the array describes one PCP instance
+domain.
+.P
+.nf
+        typedef struct {
+            __int32_t internal;
+            char external[MMV_NAMEMAX];
+        } mmv_instances_t;
+
+        typedef struct {
+            __uint32_t serial;          /* Unique serial number */
+            __uint32_t count;           /* Number of instances */
+            mmv_instances_t *instances; /* Internal/external IDs */
+            char *shorttext;            /* Short help text */
+            char *helptext;             /* Long help text */
+        } mmv_indom_t;
+.fi
+.P
+.SH RETURNS
+The function returns the address of the memory mapped region on success or
+NULL on failure.
+.SH SEE ALSO
+.BR mmv_inc_value (3),
+.BR mmv_lookup_value_desc (3)
+and
+.BR mmv (5).
diff --git a/man/man3/pcpintro.3 b/man/man3/pcpintro.3
new file mode 100644
index 0000000..9bfb07c
--- /dev/null
+++ b/man/man3/pcpintro.3
@@ -0,0 +1,637 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PCPINTRO 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3PCPIntro\f1 \- introduction to the Performance Co-Pilot (PCP) libraries
+.SH INTRODUCTION
+Performance Co-Pilot (PCP) is a toolkit designed for monitoring
+and managing system-level performance.
+.PP
+The PCP libraries support the APIs required to create new performance
+monitoring tools and new agents (or PMDAs) to export performance data.
+The
+.B libpcp
+library is used in both cases.  The
+.B libpcp_pmda
+library is used only for PMDAs.
+.PP
+Individual library routines are documented in their own manual page entries.
+.PP
+Most routines return an integer value; greater than equal to zero for
+success and less than zero for an error.  The error codes have
+symbolic names defined in
+.BR <pcp/pmapi.h> .
+Other negative values are used to encode errors that can be mapped to
+the traditional
+.I errno
+values defined in
+.BR <errno.h> ,
+with the value negated.
+To translate all PCP error codes into useful messages use
+either
+.BR pmerr (1)
+or
+.BR pmErrStr (3);
+the latter may also be used to decode the
+.I \-errno
+cases.
+.SH "GENERAL ERRORS"
+These common errors may occur in various PCP interactions.
+.TP 4n
+.B PM_ERR_TIMEOUT
+.I "Timeout waiting for a response from PMCD"
+.br
+Many interactions between PCP applications involve
+synchronous message passing, and these are subject to
+timeout constraints.  These errors are most frequently
+encountered when using network connections with slow
+data rates or long latencies.
+.RS
+.PP
+For client\-\c
+.B pmcd
+timeouts, refer to
+.BR PCPIntro (1)
+for environment variables that may be used to modify
+the timeout thresholds.
+For
+.BR pmcd -PMDA
+timeouts refer to the
+.B \-t
+and
+.B \-q
+options of
+.BR pmcd (1)
+and the PCP metric
+.B pmcd.control.timeout
+that can be dynamically changed with
+.BR pmstore (1).
+.RE
+.TP
+.B PM_ERR_APPVERSION
+.I "Metric not supported by this version of monitored application"
+.br
+Some performance metrics are unavailable from specific versions
+of the associated PMDA, or may be unavailable because the underlying
+instrumentation has changed or is not installed or is not enabled.
+This error is used in results from
+.BR pmFetch (3)
+to indicate these situations.
+.TP
+.B PM_ERR_IPC
+.I "IPC protocol failure"
+.br
+Generic protocol failure
+on a pipe or socket connecting two PCP applications, eg. client\-\c
+.BR pmcd ,
+or client\-\c
+.BR pmtime ,
+or PMDA\-\c
+.B pmcd
+or
+.BR pmlc \- pmlogger .
+.TP
+.B PM_ERR_TEXT
+.I "Oneline or help text is not available"
+.br
+Set by a PMDA, and passed back to a PCP client,
+to indicate that the PMDA is unable to supply the
+requested metric or instance domain help text.
+.TP
+.B PM_ERR_VALUE
+.I "Missing metric value(s)"
+.br
+This error is used for a number of conditions in which the value
+of a performance metric is inappropriate for the context in
+which it is being used, eg.
+.RS
+.IP (a) 4n
+Bad value for the metric
+.B pmcd.timezone
+when trying to set the timezone via
+.BR pmNewContextZone (3)
+for a remote or archive context.
+.IP (b)
+Attempting to interpolate values for a metric with non-numeric data
+type from a PCP archive.
+.IP (c)
+A bad
+.I result
+data structure passed to
+.BR pmStore (3).
+.RE
+.TP
+.B PM_ERR_NAME
+.I "Unknown metric name"
+.br
+Just what the message says.
+.TP
+.B PM_ERR_PMID
+.I "Unknown or illegal metric identifier"
+.br
+Just what the message says.
+.TP
+.B PM_ERR_INDOM
+.I "Unknown or illegal instance domain identifier"
+.br
+A request nominates an instance domain that is unknown
+or
+.BR PM_INDOM_NULL .
+May occur as a consequence of
+the instance domain identifier passed by a PCP client to
+.BR pmGetInDom (3),
+.BR pmLookupInDom (3),
+.BR pmNameInDom (3),
+.BR pmGetInDomArchive (3),
+.BR pmLookupInDomArchive (3),
+.BR pmNameInDomArchive (3)
+or a request passed from
+.BR pmcd (1)
+to a PMDA.
+.TP
+.B PM_ERR_EOF
+.I "IPC channel closed"
+.br
+End of file on a pipe or socket connecting two PCP applications, eg. client\-\c
+.BR pmcd ,
+or client\-\c
+.B pmtime
+or PMDA\-\c
+.BR pmcd.
+.TP
+.B PM_ERR_NOCONTEXT
+.I "Attempt to use an illegal context"
+.br
+Typically caused by a PCP client that tries to make calls before
+calling
+.BR pmNewContext (3)
+or after calling
+.BR pmDestroyContext (3).
+.TP
+.B PM_ERR_PERMISSION
+.I "No permission to perform requested operation"
+.br
+PCP-specific access controls apply to
+.BR pmcd (1)
+and
+.BR pmlogger (1).
+Platform-specific permission errors are returned as
+.BR \-EPERM .
+.TP
+.B PM_ERR_CONV
+.I "Impossible value or scale conversion"
+.br
+Some value conversion requests are illegal, eg. bad debug flag symbolic name
+for
+.B \-D
+option, or asking
+.BR pmExtractValue (3)
+to translate non-numeric data types to numbers and
+.IR vice " " versa .
+.TP
+.B PM_ERR_TRUNC
+.I "Truncation in value conversion"
+.br
+Some conversion requests to
+.BR pmExtractValue (3)
+cannot be performed based on the metric types and values involved,
+in this case conversion would result in loss of precision.
+.TP
+.B PM_ERR_SIGN
+.I "Negative value in conversion to unsigned"
+.br
+Some conversion requests to
+.BR pmExtractValue (3)
+cannot be performed based on the metric types and values involved,
+in this case converting a negative value to an unsigned value.
+.TP
+.B PM_ERR_TYPE
+.I "Unknown or illegal metric type"
+.br
+The metric type is held in the metric descriptor and sometimes
+encoded in the metric values returned from a call to
+.BR pmFetch (3).
+Legal values for the metric type are defined by the
+.B PM_TYPE_*
+macros in
+.BR <pcp/pmapi.h> .
+.TP
+.B PM_ERR_UNIT
+.I "Illegal pmUnits specification"
+.br
+Some conversion requests to
+.BR pmConvScale (3)
+cannot be performed due to illegal or incompatible specifications
+of the source and destination units.
+.TP
+.B PM_ERR_PROFILE
+.I "Explicit instance identifier(s) required"
+.br
+Some PMDAs, especially the
+.B proc
+PMDA, will not return ``all instances'' for a
+.BR pmFetch (3)
+request due to the cost.  The client must explicitly built an instance
+profile using
+.BR pmAddProfile (3)
+and/or
+.BR pmDelProfile (3)
+before calling
+.BR pmFetch (3).
+See also the
+.B \-F
+option to
+.BR pminfo (1).
+.TP
+.B PM_ERR_INST
+.I "Unknown or illegal instance identifier"
+.br
+A request to a PMDA nominates an instance that is unknown.
+May occur as a consequence of the profile established prior
+to a
+.BR pmFetch (3)
+call, or an explicit instance name or identifier to
+.BR pmLookupInDom (3)
+or
+.BR pmNameInDom (3).
+.TP
+.B PM_ERR_MODE
+.I "Illegal mode specification"
+.br
+Illegal
+.I mode
+argument to
+.BR pmSetMode (3).
+.TP
+.B PM_ERR_PROFILESPEC
+.I "NULL pmInDom with non-NULL instlist"
+.br
+Bad arguments passed from a PCP client to
+.BR pmAddProfile (3).
+.TP
+.B PM_ERR_TOOSMALL
+.I "Insufficient elements in list"
+.br
+Parameter passing error by caller specifying a list with less than
+one element to
+.BR pmFetch (3),
+.BR pmLookupName (3)
+or
+.BR pmStore (3).
+.TP
+.B PM_ERR_THREAD
+.I "Operation not supported for multi-threaded applications"
+.br
+As documented in
+.BR PMAPI (3)
+and elsewhere, some
+.B libpcp
+routines are intended solely for use from single-threaded applications.
+.TP
+.B PM_ERR_TOOBIG
+.I "Result size exceeded"
+.br
+Indicates a fatal error in the message (or PDU) passing protocol between
+two PCP applications.  This is an internal error, and other than
+an exotic networking failure, should not occur.
+.TP
+.B PM_ERR_RESET
+.I "PMCD reset or configuration change"
+.br
+Not used.
+.RS
+.PP
+Refer to
+.BR pmFetch (3)
+for an alternative mechanism that may be used to notify
+a PCP client when
+.BR pmcd (1)
+has experienced one or more configuration changes since the
+last request from the client.  Usually these changes involve
+a change to the namespace exported via
+.B pmcd
+and/or changes to the PMDAs under
+.BR pmcd 's
+control.
+.RE
+.TP
+.B PM_ERR_FAULT
+.I "QA fault injected"
+.br
+Used only for PCP Quality Assurance (QA) testing.
+.TP
+.B PM_ERR_NYI
+.I "Functionality not yet implemented"
+.br
+Self explanatory and rarely used.
+.TP
+.B PM_ERR_GENERIC
+.I "Generic error, already reported above"
+.br
+Rarely used, this error may be returned when the error condition
+is a consequent of some earlier returned error and a more precise
+characterization is not possible.
+.SH "CLIENT-PMCD ERRORS"
+These errors may occur in the interactions between a PCP client and
+.BR pmcd (1)
+providing real-time performance data.
+.TP
+.B PM_ERR_NOAGENT
+.I "No PMCD agent for domain of request"
+.br
+A request sent to
+.BR pmcd (1)
+requires information from an agent or PMDA that does not exist.
+Usually this means the namespace being used by the client application
+contains metric names from a previously installed PMDA.
+.TP
+.B PM_ERR_CONNLIMIT
+.I "PMCD connection limit for this host exceeded"
+.br
+The client connection limit for
+.BR pmcd (1)
+is controlled by the optional
+.B access
+controls in
+.IR $PCP_PMCDCONF_PATH .
+By default there is no limit imposed by the PCP code, and this
+error would not be seen.
+.TP
+.B PM_ERR_AGAIN
+.I "Try again. Information not currently available"
+.br
+Used to notify a PCP client that
+the PMDA responsible for delivering the information is temporarily
+unavailable.
+See also
+.BR PM_ERR_PMDANOTREADY .
+.TP
+.B PM_ERR_NOPROFILE
+.I "Missing profile - protocol botch"
+.br
+Internal error in the communication between a client application
+and
+.BR pmcd (1)
+\- should not occur.
+.SH "CLIENT-ARCHIVE ERRORS"
+These errors may occur in the interactions between a PCP client and
+the library routines that provide historical
+performance data from PCP archives created by
+.BR pmlogger (1).
+.TP
+.B PM_ERR_LOGFILE
+.I "Missing archive file"
+.br
+Each PCP archive consists of multiple physical files as described
+in
+.BR pmlogger (1).
+This error occurs when one of the physical files is missing or
+cannot be opened for reading.
+.TP
+.B PM_ERR_EOL
+.I "End of PCP archive log"
+.br
+An attempt is made to read past the end file of the last volume
+of a PCP archive, or past the
+end of the time window (as specified with a 
+.B \-T
+option) for a PCP archive.
+.TP
+.B PM_ERR_NOTHOST
+.I "Operation requires context with host source of metrics"
+.br
+Operations involving help text (ie. \c
+.BR pmLookupText (3)
+and
+.BR pmLookupInDomText (3))
+or calls to
+.BR pmStore (3)
+require a host context and are not supported for PCP archives.
+.TP
+.B PM_ERR_LOGREC
+.I "Corrupted record in a PCP archive log"
+.br
+PCP archives can become corrupted for a variety of reasons,
+but the most common is premature termination of
+.BR pmlogger (1)
+without flushing its output buffers.
+.TP
+.B PM_ERR_LABEL
+.I "Illegal label record at start of a PCP archive log file"
+.br
+Each physical file in a PCP archive should begin with a common
+label record.  This is a special case of
+.B PM_ERR_LOGREC
+errors.
+.TP
+.B PM_ERR_NODATA
+.I "Empty archive log file"
+.br
+An empty physical file can never be part of a valid PCP archive
+(at least the label record should be present).
+This is a special case of
+.B PM_ERR_LOGREC
+errors.
+.TP
+.B PM_ERR_NOTARCHIVE
+.I "Operation requires context with archive source of metrics"
+.br
+A call to one of the archive variant routines, i.e. \c
+.BR pmFetchArchive (3),
+.BR pmGetInDomArchive (3),
+.BR pmLookupInDomArchive (3)
+or
+.BR pmNameInDomArchive (3),
+when the current context is not associated with a PCP archive.
+.TP
+.B PM_ERR_PMID_LOG
+.I "Metric not defined in the PCP archive log"
+.br
+A PCP client has requested information about a metric,
+and there is no corresponding information in the PCP archive.
+This should not happen for well-behaved PCP clients.
+.TP
+.B PM_ERR_INDOM_LOG
+.I "Instance domain identifier not defined in the PCP archive log"
+.br
+A PCP client has requested information about an instance domain
+for one or more performance metrics,
+and there is no corresponding information in the PCP archive.
+If the client is using metric descriptors from the archive
+to identify the instance domain, this is less likely to happen.
+.RS
+.PP
+Because instance domains may vary over time, clients may
+need to use the variant routines
+.BR pmGetInDomArchive (3)
+or
+.BR pmLookupInDomArchive (3)
+or
+.BR pmNameInDomArchive (3)
+to manipulate the union of the instances in an instance domain over the life
+of an archive.
+.RE
+.TP
+.B PM_ERR_INST_LOG
+.I "Instance identifier not defined in the PCP archive log"
+.br
+A PCP client has requested information about a specific instance
+of a performance metric,
+and there is no corresponding information in the PCP archive.
+If the client is using instance names from the instance
+domain in the archive
+(rather than hard-coded instance names) and instance identifiers
+from the results returned by
+.BR pmFetch (3)
+or
+.BR pmFetchArchive (3)
+this is less likely to happen.
+.RS
+.PP
+Because instance domains may vary over time, clients may
+need to use the variant routines
+.BR pmLookupInDomArchive (3)
+or
+.BR pmNameInDomArchive (3)
+to manipulate the union of the instances in an instance domain over the life
+of an archive.
+.RE
+.SH "TIME CONTROL ERRORS"
+These errors may occur in the interactions between a GUI PCP client and
+the time control services provided by
+.BR pmtime (1).
+.TP
+.B PM_ERR_ISCONN
+.I "Already Connected"
+.br
+A PCP client application called
+.BR pmTimeConnect (3)
+when already connected to a
+.BR pmtime (1)
+instance.
+.TP
+.B PM_ERR_NOTCONN
+.I "Not Connected"
+.br
+A PCP client application called one of the time control routines
+.BR pmTime* (3)
+when not currently connected to any
+.BR pmtime (1)
+instance.
+.TP
+.B PM_ERR_NEEDPORT
+.I "A non-null port name is required"
+.br
+If a shared
+.BR pmtime (1)
+instance is being created
+the
+.I port
+argument to
+.BR pmTimeConnect (3)
+must not be invalid.
+.SH "NAMESPACE ERRORS"
+These errors may occur in the processing of PCP namespace operations.
+A PCP namespace, see
+.BR pmns (5),
+provides the external
+names and the internal identifiers for the available performance metrics.
+.TP
+.B PM_ERR_NONLEAF
+.I "Metric name is not a leaf in PMNS"
+.br
+The metric name passed to
+.BR pmLookupName (3)
+names a non-terminal path in the namespace, i.e. a group of metrics
+rather than a single metric.
+.TP
+.B PM_ERR_DUPPMNS
+.I "Attempt to reload the PMNS"
+.br
+When using an explicit local namespace, it is illegal to call
+either of
+.BR pmLoadNameSpace (3)
+or
+.BR pmLoadASCIINameSpace (3)
+more than once.
+.TP
+.B PM_ERR_PMNS
+.I "Problems parsing PMNS definitions"
+.br
+Only occurs when an ASCII namespace is explicitly loaded.
+.TP
+.B PM_ERR_NOPMNS
+.I "PMNS not accessible"
+.br
+Only occurs when an ASCII namespace is explicitly loaded.
+.SH "PMCD-PMDA ERRORS"
+These error codes are used in the interactions between
+.BR pmcd (1)
+and the PMDAs that provide the performance data.
+.TP
+.B PM_ERR_PMDANOTREADY
+.I "PMDA is not yet ready to respond to requests"
+.br
+Some PMDAs have long initialization or reset times, and will respond
+to
+.BR pmcd (1)
+with this error if they are busy at the moment.  This error translates
+to
+.B PM_ERR_AGAIN
+for the PCP client who made the request to
+.BR pmcd 
+which caused the initial request to the PMDA.
+At some later time the PMDA will inform
+.B pmcd
+(see
+.BR PM_ERR_PMDAREADY )
+that it is now ready to process requests, and client
+requests will begin to succeed.
+.TP
+.B PM_ERR_PMDAREADY
+.I "PMDA is now responsive to requests"
+.br
+Used by PMDAs to asynchronously inform
+.BR pmcd (1)
+that they are now willing to resume processing requests.
+See also
+.BR PM_ERR_PMDANOTREADY .
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR pmerr (1),
+.BR PMAPI (3),
+.BR pmErrStr (3),
+.BR pmGetConfig (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
diff --git a/man/man3/pmaddprofile.3 b/man/man3/pmaddprofile.3
new file mode 100644
index 0000000..457e4ae
--- /dev/null
+++ b/man/man3/pmaddprofile.3
@@ -0,0 +1,112 @@
+'\"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 PMADDPROFILE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmAddProfile\f1 \- add instance(s) to the current PMAPI instance profile
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmAddProfile(pmInDom \fIindom\fP, int \fInuminst\fP, int *\fIinstlist\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+The set of instances for performance metrics returned from a
+.BR pmFetch (3)
+call may be filtered or restricted using an instance profile.
+There is one instance profile for each context the application
+creates at the Performance Metrics Application Programming Interface 
+.RB ( PMAPI (3)),
+and each instance profile may include instances from one or more
+instance domains (see
+.BR pmLookupDesc (3)).
+.PP
+.B pmAddProfile
+may be used to
+add new instance specifications to the instance profile of the current
+PMAPI context.
+.PP
+In the simplest variant, the list of instances identified by the
+.I instlist
+argument for the
+.I indom
+instance domain are added to the instance profile.
+The list of instance
+identifiers contains
+.I numinst
+values.
+.PP
+The
+.I indom
+value would normally be extracted from a call to
+.BR pmLookupDesc (3)
+for a particular performance metric, and the instances in
+.I instlist
+would typically be determined by calls to
+.BR pmGetInDom (3)
+or
+.BR pmLookupInDom (3).
+.PP
+To select all instances in all instance domains, use
+
+.in 1.0i
+.nf
+.ft CW
+pmAddProfile(PM_INDOM_NULL, 0, (int *)0)
+.ft
+.fi
+.in
+
+This is the only case where
+.I indom
+may be equal to
+.BR PM_INDOM_NULL .
+If
+.I numinst
+is zero, or
+.I instlist
+is NULL, then all instances in
+.I indom
+are selected.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmDelProfile (3),
+.BR pmFetch (3),
+.BR pmGetInDom (3),
+.BR pmLookupDesc (3),
+.BR pmLookupInDom (3),
+.BR pmNewContext (3),
+.BR pmUseContext (3)
+and
+.BR pmWhichContext (3).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_PROFILESPEC\f1
+.I indom
+was
+.B PM_INDOM_NULL
+and
+.I instlist
+was not empty
+.SH CAVEAT
+It is possible to add non-existent instance domains and non-existent instances
+to an instance profile.  None of the routines that use the instance profile
+will ever issue an error if you do this.  The cost of checking, when checking
+is possible, outweighs any benefits.
diff --git a/man/man3/pmaf.3 b/man/man3/pmaf.3
new file mode 100644
index 0000000..fc91906
--- /dev/null
+++ b/man/man3/pmaf.3
@@ -0,0 +1,152 @@
+'\"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 PMAF 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3__pmAFregister\f1,
+\f3__pmAFunregister\f1,
+\f3__pmAFblock\f1,
+\f3__pmAFunblock\f1,
+\f3__pmAFisempty\f1 \- event queue services for periodic asynchronous callbacks
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int __pmAFregister(const struct timeval *\fIdelta\fP, void *\fIdata\fP, void\ (*\fIfunc\fP)(int,\ void *));
+.br
+.in
+.hy
+.ad
+int __pmAFunregister(int \fIafid\fP);
+.br
+void __pmAFblock(void);
+.br
+void __pmAFunblock(void);
+.br
+int __pmAFisempty(void);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+The routines implement an event queue and callback framework that supports
+periodic evaluation of a series of events with varying frequencies
+for Performance Co-Pilot (PCP) applications.
+.P
+The
+.BR pmlogger (1)
+application, the
+.BR pmdatrace (1)
+PMDA and the
+.BR pmdahotproc (1)
+PMDA are the principal users of these services.
+.P
+An event is registered by calling
+.BR __pmAFregister ,
+and on success the return value is an event number greater than zero.
+The event has associated event data identified by the opaque pointer
+.IR data .
+The event will occur with frequency
+.IR delta
+(the first instance will be
+.I delta
+after the current time when the event is registered),
+and each time the event occurs the function
+.I func
+will be called with the event number and the event data as arguments.
+.P
+Once the event occurs and the callback has been executed, the event
+will be rescheduled for
+.I delta
+into the future, except
+if all the fields of
+.I delta
+are zero, in which case
+the event will not be rescheduled
+(a ``one trip'' event).
+.P
+Internally, events are processed serially so there is no
+possibility of nested callbacks or re-entrant callbacks from the
+event management routines.
+.P
+Given an event number
+.IR afid ,
+.B __pmAFunregister
+will permanently remove the corresponding entry from the event queue.
+.P
+To control the event queue processing,
+.B __pmAFblock
+and
+.B __pmAFunblock
+may be used to explicitly block and unblock the dispatch of events.
+This is most useful when the caller wishes to set up a number of
+events via
+.B __pmAFregister
+and complete the registration phase before the first
+event callback occurs.
+.P
+A call to
+.B __pmAFisempty
+returns 1 or 0 depending on whether the event queue is empty or not.
+.SH SEE ALSO
+.BR PMAPI (3)
+.SH DIAGNOSTICS
+.PP
+.B __pmAFregister
+and
+.B __pmAFunregister
+return values less than zero in the case of an error.  These values
+are PCP error codes, and may be used to produce error messages via
+.BR pmErrStr (3).
+.P
+The routines support the standard PCP debug tracing, and the value
+.B DBG_TRACE_AF
+(or
+.B "\-D af"
+on the command line)
+will produce diagnostics on standard error that trace the enqueueing
+and execution of events.
+.SH CAVEATS
+These routines rely on
+.BR setitimer (2)
+and manipulate the handling of
+.B SIGALRM
+signals, and hence are probably ill-suited for applications that
+require direct and concurrent access to these services and resources.
+.P
+If the callback functions are slow, or delayed, it is possible that
+the event scheduling could fall behind and never catchup.  When this
+begins to happen, events are silently skipped and rescheduled at the earliest
+possible time on the future according to the fixed schedule defined
+by the time of the call to
+.B __pmAFregister
+and the value of the
+.I delta
+argument to
+.BR __pmAFregister .
+.P
+In addition, the semantics of the interval timer(s) and the global
+state needed to support these services demand that applications
+calling these routines must do so from a single thread.
+This restriction is enforced at the
+.BR PMAPI (3),
+where routines may return the error code
+.B PM_ERR_THREAD
+if the library detects calls from more than one thread.
diff --git a/man/man3/pmafm.3 b/man/man3/pmafm.3
new file mode 100644
index 0000000..6d0c122
--- /dev/null
+++ b/man/man3/pmafm.3
@@ -0,0 +1,479 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 1998-2008 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 PMAFM 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmafm\f1,
+\f3pmRecordSetup\f1,
+\f3pmRecordAddHost\f1,
+\f3pmRecordControl\f1 \- record mode support for PMAPI clients
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmafm.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+FILE *pmRecordSetup(const char *\fIfolio\fP, const char *\fIcreator\fP, int\ \fIreplay\fP);
+.br
+.ti -8n
+int pmRecordAddHost(const char *\fIhost\fP, int \fIisdefault\fP, pmRecordHost\ **\fIrhp\fP);
+.br
+.ti -8n
+int pmRecordControl(pmRecordHost *\fIrhp\fP, int \fIrequest\fP, const\ char\ *\fIoptions\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_gui
+.ft 1
+.SH DESCRIPTION
+These routines may be used to create a Performance Co-Pilot (PCP)
+archive ``on the fly'' to
+support ``record mode'' services for PMAPI client applications.
+.PP
+Each record mode ``session'' involves one or more
+PCP archive logs each created using a dedicated
+.BR pmlogger (1)
+process, with an overall Archive Folio format as understood by
+.BR pmafm (1),
+to name and collect all of the archive logs associated with
+a single recording session.
+.PP
+The
+.I pmRecordHost
+structure is used to maintain state information between the
+creator of the recording session and the associated
+.BR pmlogger
+process(es).  The structure is defined as:
+.sp 0.5v
+.ft CW
+.nf
+.in +0.25i
+typedef struct {
+    FILE   *f_config;    /* caller writes pmlogger configuration here */
+    int    fd_ipc;       /* IPC channel to pmlogger */
+    char   *logfile;     /* full pathname for pmlogger error logfile */
+    pid_t  pid;          /* process id for pmlogger */
+    int    status;       /* exit status, \-1 if unknown */
+} pmRecordHost;
+.in -0.25i
+.fi
+.ft R
+.PP
+The routines are used in combination to create a recording session
+as follows.
+.IP 1. 4n
+Call
+.B pmRecordSetup
+to establish a new recording session.  A new Archive Folio will be
+created using the name
+.IR folio ;
+if the file or directory
+.I folio
+already exists, or the file
+.I folio
+cannot be created, this is an error.
+The application that is creating the session is identified by
+.I creator
+(most often this would be the same as the global PMAPI application name,
+.IR pmProgname ).
+If the application knows how to create its own configuration file to replay
+the recorded session, then
+.I replay
+should be non-zero.
+.RS
+.PP
+.B pmRecordSetup
+returns a
+.I stdio
+stream onto
+which the application should write the text of the required
+replay configuration file, if any.
+.RE
+.IP 2.
+For each
+.I host
+that is to be included in the recording session, call
+.BR pmRecordAddHost .
+A new
+.I pmRecordHost
+structure is returned via
+.IR rhp .
+It is assumed that
+.BR pmcd (1)
+is running on
+.I host
+as this is how
+.BR pmlogger (1)
+will retrieve the required performance metrics.
+.RS
+.PP
+If this
+.I host
+is the default host for this recording session, then
+.I isdefault
+should be non-zero.  This will ensure that the corresponding archive
+appears first in the PCP archive folio, and hence the tools used
+to replay the archive folio will make the correct determination of the
+archive associated with the default host.
+At most one
+.I host
+per recording session may be nominated as the default host.
+.PP
+The calling application should
+write the desired
+.B pmlogger
+configuration onto the
+.I stdio
+stream returned via the
+.I f_config
+field in the
+.I pmRecordHost
+structure.
+.RE
+.IP 3.
+Optionally add arguments to the command line that will be used
+to launch
+.BR pmlogger (1)
+by calling
+.B pmRecordControl
+with a
+.I request
+of
+.BR PM_REC_SETARG .
+The argument is passed via
+.I options
+and one call to
+.B pmRecordControl
+is required for each distinct argument.
+.RS
+.PP
+An argument may be added for a particular
+.B pmlogger
+instance
+identified by
+.IR rhp ,
+or if the
+.I rhp
+argument
+is NULL the argument is added for all
+.B pmlogger
+instances that will be launched in the current recording session.
+.PP
+Independent of any calls to
+.B pmRecordControl
+with a
+.I request
+of
+.BR PM_REC_SETARG ,
+each
+.B pmlogger
+instance will automatically be launched with the following arguments:
+.BR \-c ,
+.BR \-h ,
+.BR \-l ,
+.B \-x
+and the basename for the PCP archive log.
+.RE
+.IP 4.
+To commence the recording session, call
+.B pmRecordControl
+with a
+.I request
+of
+.BR PM_REC_ON ,
+and
+.I rhp
+must be NULL.
+This will launch one
+.BR pmlogger (1)
+process for each host in the recording session,
+and initialize the
+.IR fd_ipc ,
+.IR logfile ,
+.I pid
+and
+.I status
+fields in the associated
+.I pmRecordHost
+structure(s).
+.IP 5.
+To terminate a
+.B pmlogger
+instance
+identified by
+.IR rhp ,
+call
+.B pmRecordControl
+with a
+.I request
+of
+.BR PM_REC_OFF .
+If the
+.I rhp
+argument to
+.B pmRecordControl
+is NULL, the termination request is broadcast to all
+.B pmlogger
+processes in the current recording session.
+.RS
+.PP
+An informative dialog is generated directly by each
+.B pmlogger
+process and hence note the comments on the disposition of output from
+.B pmlogger
+below.
+.PP
+Alternatively,
+.B pmlogger
+can be started with options to limit the duration of logging, e.g. the
+.B \-T
+or
+.B \-s
+arguments, in which case there is no need to call
+.B pmRecordControl
+with a
+.I request
+of
+.B PM_REC_OFF
+and no dialog is generated.
+.RE
+.IP 6.
+To display the current status of the
+.B pmlogger
+instance identified by
+.IR rhp ,
+call
+.B pmRecordControl
+with a
+.I request
+of
+.BR PM_REC_STATUS .
+If the
+.I rhp
+argument to
+.B pmRecordControl
+is NULL, the status request is broadcast to all
+.B pmlogger
+processes in the current recording session.
+.RS
+.PP
+The display is generated directly by each
+.B pmlogger
+process and hence note the comments on the disposition of output from
+.B pmlogger
+below.
+.RE
+.IP 7.
+To detach a
+.B pmlogger
+instance identified by
+.IR rhp
+and allow it to continue independent of
+the application that launched the recording session, call
+.B pmRecordControl
+with a
+.I request
+of
+.BR PM_REC_DETACH .
+If the
+.I rhp
+argument to
+.B pmRecordControl
+is NULL, the detach request is broadcast to all
+.B pmlogger
+processes in the current recording session.
+.RS
+.PP
+An informative dialog is generated directly by each
+.B pmlogger
+process and hence note the comments on the disposition of output from
+.B pmlogger
+below.
+.RE
+.PP
+The calling application should not close any of the returned
+.I stdio
+streams; this will be done by
+.B pmRecordControl
+when recording is commenced.
+.PP
+Once
+.B pmlogger
+has been started for a recording session, then
+.B pmlogger
+will assume responsibility for any dialog with the user in the event
+that the application that launched the recording session should
+exit, particularly without terminating the recording session.
+.PP
+By default, information and dialogs from
+.B pmlogger
+will be displayed using
+.BR pmquery (1)
+on the assumption that most applications wishing to launch
+a recording session are GUI-based.  In the event that
+.B pmquery
+fails to display the information (for example, because the
+.B DISPLAY
+environment variable is not set),
+.B pmlogger
+will write on its own
+.I stderr
+stream (\c
+.B not
+the
+.I stderr
+stream of the launching process);
+the output will be assigned to the
+.I XXXXXX.host.\fBlog\fP
+file described in the FILES section below.
+For convenience, the full pathname to this file is provided via the
+.I logfile
+field in the
+.I pmRecordHost
+structure.
+.PP
+If the
+.I options
+argument to
+.B pmRecordControl
+is not NULL, this string may be
+used to pass additional arguments to
+.BR pmquery (1)
+in those cases where a dialog is to be displayed.  One use of this
+capability would be to
+provide a
+.B \-geometry
+string to control the placement of the dialog.
+.PP
+Premature termination of a launched
+.B pmlogger
+process may be determined using the
+.I pmRecordHost
+structure,
+by calling
+.BR select (2)
+on the
+.I fd_ipc
+field
+or polling the
+.I status
+field that will contain the termination status from
+.BR waitpid (2)
+if known, else \-1.
+.SH SEE ALSO
+.BR pmafm (1),
+.BR pmlogger (1),
+.BR pmquery (1)
+and
+.BR PMAPI (3).
+.SH FILES
+These routines create a number of files in the
+.B "same directory"
+as the
+.I folio
+file named in the call to
+.BR pmRecordSetup .
+In all cases, the ``XXXXXX'' component is the result of
+calling
+.BR mktemp (3).
+.TP 10
+.I XXXXXX
+If
+.I replay
+is non-zero, this is the creator's replay configuration file, else
+an empty control file, used to guarantee uniqueness.
+.PD 0
+.TP
+.I folio
+The PCP Archive Folio, suitable for use with
+.BR pmafm (1).
+.TP
+.I XXXXXX.host.\fBconfig\fP
+The
+.BR pmlogger (1)
+configuration for each
+.I host
+\- if the same
+.I host
+is used in different calls to
+.B pmRecordAddHost
+within the same recording session
+then one of the letters ``a'' through ``z'' will
+be appended to the ``XXXXXX'' part of all associated file names to ensure
+uniqueness.
+.TP
+.I XXXXXX.host.\fBlog\fP
+.I stdout
+and
+.I stderr
+for the
+.BR pmlogger (1)
+instance for each
+.IR host .
+.TP
+.I XXXXXX.host.\fR{\fB0\fP,\fBmeta\fP,\fBindex\fP}
+The files comprising a single PCP archive for each
+.IR host .
+.SH DIAGNOSTICS
+.PD
+.PP
+.B pmRecordSetup
+may return
+.B NULL
+in the event of an error.
+Check
+.I errno
+for the real cause, but the value
+.B EINVAL
+typically means that the order of calls to these routines is
+not correct (there is obvious state associated with the current
+recording session that is maintained across calls to these routines).
+For example
+the following calls would produce this
+.B EINVAL
+error;
+calling
+.B pmRecordControl
+before calling
+.B pmRecordAddHost
+at least once, or calling
+.B pmRecordAddHost
+before calling
+.BR pmRecordSetup .
+.PP
+.B pmRecordControl
+and
+.B pmRecordAddHost
+both return 0 on success, else a value less than 0 suitable for
+decoding with
+.BR pmErrStr (3)
+on failure.
+The value
+.B \-EINVAL
+has the same interpretation as
+.I errno
+being set to
+.B EINVAL
+as described above.
+.PP
+.B pmRecordControl
+will return
+.B PM_ERR_IPC
+if the associated
+.B pmlogger
+process has already exited.
diff --git a/man/man3/pmapi.3 b/man/man3/pmapi.3
new file mode 100644
index 0000000..0c3a35c
--- /dev/null
+++ b/man/man3/pmapi.3
@@ -0,0 +1,455 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMAPI 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3PMAPI\f1 \- introduction to the Performance Metrics Application Programming Interface
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.ft 1
+\& ... assorted routines ...
+.ft 3
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+.\" add in the -me strings for super and subscripts
+.ie n \{\
+.       ds [ \u\x'-0.25v'
+.       ds ] \d
+.       ds { \d\x'0.25v'
+.       ds } \u
+.\}
+.el \{\
+.       ds [ \v'-0.4m'\x'-0.2m'\s-3
+.       ds ] \s0\v'0.4m'
+.       ds { \v'0.4m'\x'0.2m'\s-3
+.       ds } \s0\v'-0.4m'
+.\}
+Within the framework of the Performance Co-Pilot (PCP), client
+applications are developed using the
+Performance Metrics Application Programming Interface (PMAPI) that
+defines a procedural interface with services suited to the development
+of applications with a particular interest in performance metrics.
+.PP
+This description presents an overview of the PMAPI and the
+context in which PMAPI applications are run.
+The PMAPI is more fully described in the
+.IR "Performance Co-Pilot Programmer's Guide" ,
+and the manual pages for the individual PMAPI routines.
+.SH "PERFORMANCE METRICS \- NAMES AND IDENTIFIERS"
+For a description of the Performance Metrics Name Space (PMNS)
+and associated terms and concepts,
+see
+.BR PCPIntro (1).
+.PP
+Not all PMIDs need be represented in the PMNS of
+every application.
+For example, an application which monitors disk
+traffic will likely use a name space which references only the PMIDs
+for I/O statistics.
+.PP
+Applications which use the PMAPI may have independent
+versions of a PMNS, constructed from an initialization file when the
+application starts; see
+.BR pmLoadASCIINameSpace (3),
+.BR pmLoadNameSpace (3),
+and
+.BR pmns (5).
+.PP
+Internally (below the PMAPI) the implementation of the
+Performance Metrics Collection System
+(PMCS) uses only the PMIDs, and a PMNS
+provides an external mapping from a hierarchic taxonomy of names to
+PMIDs that is
+convenient in the context of a particular system or particular use of
+the PMAPI.
+For the applications programmer,
+the routines
+.BR pmLookupName (3)
+and
+.BR pmNameID (3)
+translate between names in a PMNS and PMIDs, and vice versa.
+The PMNS may be traversed using
+.BR pmGetChildren (3).
+.SH "PMAPI CONTEXT"
+An application using the PMAPI may manipulate several concurrent contexts,
+each associated with a source of performance metrics, e.g. \c
+.BR pmcd (1)
+on some host, or an archive log of performance metrics as created by
+.BR pmlogger (1).
+.PP
+Contexts are identified by a ``handle'', a small integer value that is returned
+when the context is created; see
+.BR pmNewContext (3)
+and
+.BR pmDupContext (3).
+Some PMAPI functions require an explicit ``handle'' to identify
+the correct context, but more commonly the PMAPI function is
+executed in the ``current'' context.
+The current context may be discovered using
+.BR pmWhichContext (3)
+and changed using
+.BR pmUseContext (3).
+.PP
+If a PMAPI context has not been explicitly established
+(or the previous current context has been closed using
+.BR pmDestroyContext (3))
+then the current PMAPI context is undefined.
+.PP
+In addition to the source of the performance metrics, the context
+also includes the instance profile and collection time (both described below)
+which controls
+how much information is returned, and when the information was collected.
+.SH "INSTANCE DOMAINS"
+When performance metric values are returned across the PMAPI to a
+requesting application, there may be more than one value for a
+particular metric.
+Multiple values, or
+.BR instances ,
+for a single metric
+are typically the result of instrumentation being implemented for each
+instance of a set of similar components or services in a system, e.g.
+independent counts for each CPU, or each process, or each disk, or each
+system call type, etc.
+This multiplicity of values is not enumerated in
+the name space but rather, when performance metrics are delivered
+across the PMAPI by
+.BR pmFetch (3),
+the format of the result accommodates values for one
+or more instances, with an instance-value pair
+encoding the metric value for a particular
+instance.
+.PP
+The instances are identified by an internal identifier assigned
+by the agent responsible for instantiating the values for the
+associated performance metric.
+Each instance identifier has a corresponding external instance identifier
+name (an ASCII string).
+The routines
+.BR pmGetInDom (3),
+.BR pmLookupInDom (3)
+and
+.BR pmNameInDom (3)
+may be used to enumerate all instance identifiers, and to
+translate between internal and external instance
+identifiers.
+.PP
+All of the instance identifiers for a particular performance metric
+are collectively known as an instance domain.
+Multiple performance metrics may share the same instance domain.
+.PP
+If only one instance is ever available for a particular performance
+metric, the instance identifier
+in the result from
+.BR pmFetch (3)
+assumes the special value
+.B PM_IN_NULL
+and may be ignored by the
+application, and only one instance-value pair appears in the result
+for that metric.
+Under these circumstances, the associated instance domain (as returned
+via
+.BR pmLookupDesc (3))
+is set to
+.B PM_INDOM_NULL
+to indicate that values for this metric are singular.
+.PP
+The difficult issue of
+transient performance metrics (e.g. per-filesystem information, hot-plug
+replaceable hardware modules, etc.) means that repeated requests for
+the same PMID may return different numbers of values, and/or some
+changes in the particular instance identifiers returned.
+This means
+applications need to be aware that metric instantiation is guaranteed
+to be valid at the time of collection only.
+Similar rules apply to the
+transient semantics of the associated metric values.
+In general
+however, it is expected that the bulk of the performance metrics will
+have instantiation semantics that are fixed over the execution
+life-time of any PMAPI client.
+.SH "THE TYPE OF METRIC VALUES"
+The PMAPI supports a wide range of format and type encodings for
+the values of performance metrics, namely signed and unsigned integers,
+floating point numbers, 32-bit and 64-bit encodings of all of the above,
+ASCII strings (C-style, NULL byte terminated), and arbitrary aggregates of
+binary data.
+.PP
+The
+.CW type
+field in the
+.CW pmDesc
+structure returned by
+.BR pmLookupDesc (3)
+identifies the format and type of the values for a particular
+performance metric within a particular PMAPI context.
+.PP
+Note that the encoding of values for a particular performance metric
+may be different for different PMAPI contexts, due to differences
+in the underlying implementation for different contexts.
+However it is expected that the vast majority of performance metrics
+will have consistent value encoding across all versions of all
+implementations, and hence across all PMAPI contexts.
+.PP
+The PMAPI supports routines to automate the handling
+of the various value formats and types, particularly for
+the common case where conversion to a canonical format is
+desired, see
+.BR pmExtractValue (3)
+and
+.BR pmPrintValue (3).
+.SH "THE DIMENSIONALITY AND SCALE OF METRIC VALUES"
+Independent of how the value is encoded, the
+value for a performance metric is assumed to be drawn from a set of values that
+can be described in terms of their dimensionality and scale by a compact
+encoding as follows.
+The dimensionality is defined by a power, or index, in
+each of 3 orthogonal dimensions, namely Space, Time and Count
+(or Events, which are dimensionless).
+For example I/O throughput might be represented as
+Space/Time, while the
+running total of system calls is Count, memory allocation is Space and average
+service time is Time/Count.
+In each dimension there are a number
+of common scale values that may be used to better encode ranges that might
+otherwise exhaust the precision of a 32-bit value.
+This information is encoded
+in the
+.CW pmUnits
+structure which is embedded in the
+.CW pmDesc
+structure returned from
+.BR pmLookupDesc (3).
+.PP
+The routine
+.BR pmConvScale (3)
+is provided to convert values in
+conjunction with the
+.CW pmUnits
+structures that defines the dimensionality and scale of the values for a
+particular performance metric as returned from
+.BR pmFetch (3),
+and the desired dimensionality and scale of
+the value the PMAPI client wishes to manipulate.
+.SH "INSTANCE PROFILE"
+The set of instances for performance metrics returned from a
+.BR pmFetch (3)
+call may be filtered or restricted using an instance profile.
+There is one instance profile for each PMAPI context the application
+creates,
+and each instance profile may include instances from one or more
+instance domains.
+.PP
+The routines
+.BR pmAddProfile (3)
+and
+.BR pmDelProfile (3)
+may be used to dynamically adjust the instance profile.
+.SH "COLLECTION TIME"
+For each set of values for performance metrics returned
+via
+.BR pmFetch (3)
+there is an associated ``timestamp''
+that serves to identify when the performance metric
+values were collected; for metrics being delivered from
+a real-time source (i.e. \c
+.BR pmcd (1)
+on some host) this would typically be not long before they
+were exported across the PMAPI, and for metrics being delivered
+from an archive log, this would be the time when the metrics
+were written into the archive log.
+.PP
+There is an issue here of exactly
+when individual metrics may have been collected, especially given
+their origin in potentially different Performance Metric Domains, and
+variability in the metric updating frequency at the lowest level of the
+Performance Metric Domain.
+The PMCS opts for the pragmatic approach,
+in which the PMAPI implementation undertakes to return all of the
+metrics with values accurate as of the timestamp, to the best of our
+ability.
+The belief is that the inaccuracy this introduces is small,
+and the additional burden of accurate individual timestamping for each
+returned metric value is neither warranted nor practical (from an
+implementation viewpoint).
+.PP
+Of course, in the case of collection of
+metrics from multiple hosts the PMAPI client must assume the
+sanity of the timestamps is constrained by the extent to which clock
+synchronization protocols are implemented across the network.
+.PP
+A PMAPI application may call
+.BR pmSetMode (3)
+to vary the requested collection time, e.g. to rescan performance
+metrics values from the recent past, or to ``fast-forward'' through
+an archive log.
+.SH "GENERAL ISSUES OF PMAPI PROGRAMMING STYLE"
+Across the PMAPI, all arguments and results involving a
+``list of something'' are declared to be arrays with an associated argument or
+function value to identify the number of elements in the list.
+This has been done to avoid both the
+.BR varargs (3)
+approach and sentinel-terminated lists.
+.PP
+Where the size of a result is known at the time of a call, it
+is the caller's responsibility to allocate (and possibly free) the
+storage, and the called function will assume the result argument is of
+an appropriate size.
+Where a result is of variable size and that size
+cannot be known in advance (e.g. for
+.BR pmGetChildren (3),
+.BR pmGetInDom (3),
+.BR pmNameInDom (3),
+.BR pmNameID (3),
+.BR pmLookupText (3)
+and
+.BR pmFetch (3))
+the PMAPI implementation uses a range of dynamic
+allocation schemes in the called routine, with the caller
+responsible for subsequently releasing the storage when
+no longer required.
+In some cases this simply involves calls to
+.BR free (3C),
+but in others (most notably for the result from
+.BR pmFetch (3)),
+special routines (e.g. \c
+.BR pmFreeResult (3))
+should be used to release the storage.
+.PP
+As a general rule, if the called routine returns
+an error status then no allocation will have been
+done, and any pointer to a variable sized result is undefined.
+.SH DIAGNOSTICS
+Where error conditions may arise, the functions that comprise the PMAPI conform to a single, simple 
+error notification scheme, as follows;
+.IP + 3n
+the function returns an integer
+.IP + 3n
+values >= 0 indicate no error, and perhaps some positive status,
+e.g. the number of things really processed
+.IP + 3n
+values < 0 indicate an error, with a global table of error conditions and error messages
+.PP
+The PMAPI routine
+.BR pmErrStr (3)
+translates error conditions into error messages.
+By convention, the small negative
+values are assumed to be negated versions of the Unix error codes as defined
+in
+.B <errno.h>
+and the strings returned are as per
+.BR strerror (3C).
+The larger, negative error codes are PMAPI error conditions.
+.PP
+One error, common to all PMAPI routines that interact with
+.BR pmcd (1)
+on some host is
+.BR PM_ERR_IPC ,
+which indicates the communication link to
+.BR pmcd (1)
+has been lost.
+.SH "MULTI-THREADED APPLICATIONS"
+The original design for PCP was based around single-threaded applications, or
+more strictly applications in which only one thread was ever expected to
+call the PCP libraries.
+This restriction has been relaxed for
+.B libpcp
+to allow the most common PMAPI routines to be safely called from any
+thread in a multi-threaded application.
+.PP
+However the following groups of functions and services in
+.B libpcp
+are still restricted to being called from a single-thread, and this is enforced
+by returning
+.B PM_ERR_THREAD
+when an attempt to call the routines in each group from more than one
+thread is detected.
+.TP 4n
+1.
+Any use of a
+.B PM_CONTEXT_LOCAL
+context, as the DSO PMDAs that are called directly from
+.B libpcp
+may not be thread-safe.
+.TP 4n
+2.
+The interval timer services use global state with semantics that demand
+it is only used in the context of a single thread, so
+.BR __pmAFregister (3),
+.BR __pmAFunregister (3),
+.BR __pmAFblock (3),
+.B __pmAFunblock (3)
+and
+.BR __pmAFisempty (3).
+.TP 4n
+3.
+The following (undocumented) access control manipulation
+routines that are principally intended
+for single-threaded applications:
+.BR __pmAccAddOp ,
+.BR __pmAccSaveHosts ,
+.BR __pmAccRestoreHosts ,
+.BR __pmAccFreeSavedHosts ,
+.BR __pmAccAddHost ,
+.BR __pmAccAddClient ,
+.B __pmAccDelClient
+and
+.BR __pmAccDumpHosts .
+.TP 4n
+4.
+The following (undocumented) routines that identify
+.I pmlogger
+control ports and are principally intended
+for single-threaded applications:
+.B __pmLogFindPort
+and
+.BR __pmLogFindLocalPorts .
+.SH "PCP ENVIRONMENT"
+Most environment variables are described in
+.BR PCPIntro (1).
+In addition,
+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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR PCPIntro (3),
+.BR PMAPI (3),
+.BR pmda (3),
+.BR pmGetConfig (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
diff --git a/man/man3/pmatomstr.3 b/man/man3/pmatomstr.3
new file mode 100644
index 0000000..b5fa298
--- /dev/null
+++ b/man/man3/pmatomstr.3
@@ -0,0 +1,119 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMATOMSTR 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmAtomStr\f1,
+\f3pmAtomStr_r\f1 \- convert a performance metric value into a string
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+const char *pmAtomStr(const pmAtomValue *\fIavp\fP, int \fItype\fP);
+.br
+char *pmAtomStr_r(const pmAtomValue *\fIavp\fP, int \fItype\fP, char *\fIbuf\fP, int \fIbuflen\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+All performance metric values may be encoded in a
+.CW pmAtomValue
+union, defined as follows;
+.PP
+.ft CW
+.nf
+.in +0.5i
+typedef union {
+    __int32_t    l;     /* 32-bit signed */
+    __uint32_t   ul;    /* 32-bit unsigned */
+    __int64_t    ll;    /* 64-bit signed */
+    __uint64_t   ull;   /* 64-bit unsigned */
+    float        f;     /* 32-bit floating point */
+    double       d;     /* 64-bit floating point */
+    char         *cp;   /* char ptr */
+    pmValueBlock *vbp;  /* pmValueBlock ptr */
+} pmAtomValue;
+.in
+.fi
+.ft 1
+.PP
+Given the performance metric value pointed to by
+.IR avp ,
+and a performance metric type defined by
+.IR type ,
+.B pmAtomStr
+will generate the corresponding metric value as a string,
+suitable for diagnostic or report output.
+The
+.B pmAtomStr_r
+function does the same, but stores the result in a user-supplied buffer
+.I buf
+of length
+.IR buflen ,
+which should have room for at least 80 bytes.
+.PP
+The value for
+.I type
+is typically extracted from a
+.CW pmDesc
+structure, following a call to
+.BR pmLookupDesc (3)
+for a particular performance metric.
+.PP
+If the
+.I type
+is
+.B PM_TYPE_STRING
+values longer than 38 characters will be truncated after 34 characters,
+and truncation shown with ellipsis ``...'' at the end of the value.
+.PP
+If the
+.I type
+is
+.B PM_TYPE_AGGREGATE
+then up to the first three 32-bit words are displayed as hexadecimal values.
+.PP
+If the
+.I type
+is
+.B PM_TYPE_EVENT
+then a summary of the number of event records found in the value
+is generated.
+.PP
+The return value from
+.B pmAtomStr
+is held in a single static buffer, so
+the returned value is only valid until the next call
+to
+.BR pmAtomStr .
+.SH NOTES
+.B pmAtomStr
+returns a pointer to a static buffer and hence is not thread-safe.
+Multi-threaded applications should use
+.B pmAtomStr_r
+instead.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmConvScale (3),
+.BR pmExtractValue (3),
+.BR pmLookupDesc (3),
+.BR pmPrintValue (3),
+.BR pmTypeStr (3)
+and
+.BR pmUnitsStr (3).
diff --git a/man/man3/pmconnectlogger.3 b/man/man3/pmconnectlogger.3
new file mode 100644
index 0000000..e29ded1
--- /dev/null
+++ b/man/man3/pmconnectlogger.3
@@ -0,0 +1,106 @@
+'\"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 PMCONNECTLOGGER 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3__pmConnectLogger\f1 \- connect to a performance metrics logger control port
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+.sp
+int __pmConnectLogger(const char *\fIhostname\fP, int \fIpid\fP);
+.sp
+cc ... \-lpcp 
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\fR\\$2
+.el \fI\\$1\fR\\$2
+..
+Each instance of the Performance Co-Pilot (PCP) archive logger program
+.BR pmlogger (1)
+supports a control port on which
+.BR __pmControlLog (3)
+requests are received, and responses sent.
+Optionally, the
+.BR pmlogger (1)
+instance may be designated the ``primary'' logger.
+.PP
+.B __pmConnectLogger
+may be used to establish a control port connection to the
+.BR pmlogger (1)
+instance identified by process id
+.I pid
+on the host
+.IR hostname .
+.PP
+One special case is supported; for the reserved
+.I pid
+value of
+.B PM_LOG_CONTROL_PORT
+the requested connection is to the
+control port for the ``primary'' logger, whatever its process
+id might be.
+.PP
+On success,
+.B __pmConnectLogger
+returns a non-negative integer, that is a file descriptor that may be used
+in subsequent communication with the
+.BR pmlogger (1)
+instance, e.g. for
+.BR __pmControlLog (3).
+.PP
+As the control port to
+.BR pmlogger (1)
+is not mulitplexed, applications using
+.B __pmConnectLogger
+should use
+.BR close (2)
+to terminate the connection to
+.BR pmlogger (1)
+as soon as they have finished communicating.
+.PP
+If the application connects, and the
+.BR pmlogger (1)
+instance subsequently terminates, e.g. \c
+because the associated
+.BR pmcd (1)
+instance is terminated, the application will have to explicitly
+re-establish connection to a re-started
+.BR pmlogger (1)
+instance by calling
+.B __pmConnectLogger
+again.
+.SH SEE ALSO
+.BR pmcd (1),
+.BR pmlc (1),
+.BR pmlogger (1),
+.BR PMAPI (3)
+and
+.BR __pmControlLog (3).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_PERMISSION\f1
+no permission to connect to the specified
+.BR pmlogger (1)
+instance
+.IP \f3\-ECONNREFUSED\f1
+the designated
+.BR pmlogger (1)
+instance does not exist
+.IP \f3\-EEADDRINUSE\f1
+the requested control port is already in use
diff --git a/man/man3/pmcontrollog.3 b/man/man3/pmcontrollog.3
new file mode 100644
index 0000000..820de32
--- /dev/null
+++ b/man/man3/pmcontrollog.3
@@ -0,0 +1,286 @@
+'\"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 PMCONTROLLOG 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3__pmControlLog\f1 \- enable, disable or enquire about logging of performance
+metrics
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int __pmControlLog(int \fIfd\fP, const pmResult *\fIrequest\fP, int\ \fIcontrol\fP, int\ \fIstate\fP, int\ \fIdelta\fP, pmResult\ **\fIstatus\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\fR\\$2
+.el \fI\\$1\fR\\$2
+..
+.B __pmControlLog
+may be used to enable or disable the archive logging for particular performance
+metrics, as identified by the
+.I request
+parameter;
+see
+.BR pmFetch (3)
+for an explanation of the
+.CW pmResult
+structure.
+.PP
+The application must have previously issued a call to
+.BR __pmConnectLogger (3)
+to establish a control-port connection
+to the
+.BR pmlogger (1)
+instance to whom the control request is to be directed, and
+.I fd
+(the result from
+.BR __pmConnectLogger (3))
+identifies this connection.
+.PP
+Within
+.IR request ,
+only the details of the performance metrics and their associated
+instances will be used, i.e.
+the values of the metrics, if any, will be ignored.
+.I request
+would typically be constructed as the result of an earlier call to
+.BR pmFetch (3).
+For metrics with a singular value (having an instance domain of
+.BR PM_INDOM_NULL )
+the corresponding
+.CW pmValueSet
+should have the value one in the
+.CW numval
+field and
+.B PM_IN_NULL
+as the
+.CW inst
+field of the single
+.CW pmValue
+supplied.
+If multiple explicit instances are to be logged, the
+.CW numval
+field of the
+.CW pmValueSet
+should contain the number of instances supplied and the
+.CW inst
+fields of the
+.CW pmValue
+structures should contain specific instance identifiers (which may not have the
+reserved value
+.BR PM_IN_NULL ).
+.PP
+If the
+.CW numval
+field within any of the
+.CW pmValueSet
+structures in
+.I request
+has a value of zero, it indicates that all available instances of the metric
+should be used.  Enumeration of the instance domain is deferred until the
+logger fetches the metric prior to writing it to the log, rather than being
+performed when the
+.B __pmControlLog
+request is received.  This is useful for metrics with instance domains that
+change over time.  It is an error to specify
+.CW numval
+equal to zero if the corresponding metric has a singular value (no instance
+domain).
+.PP
+There are several sorts of logging control available, namely mandatory or
+advisory, as defined by the
+.I control
+argument, and on, off or maybe as defined by the
+.I state
+argument. These different types of control may be used to ensure that some
+performance metrics can be guaranteed to always be in the log, while others may
+be dynamically enabled or disabled as determined by the level and type of
+system activity.
+.PP
+The actual action to be performed is defined by the combination of
+.I control
+and
+.I state
+as follows.
+If
+.I control
+is
+.B PM_LOG_MANDATORY
+and
+.I state
+is
+.BR PM_LOG_ON ,
+then logging is enabled.
+If
+.I control
+is
+.B PM_LOG_MANDATORY
+and
+.I state
+is
+.BR PM_LOG_OFF ,
+then logging is disabled.
+If
+.I control
+is
+.B PM_LOG_MANDATORY
+and
+.I state
+is
+.BR PM_LOG_MAYBE ,
+then subsequent advisory controls will be honored.  If the logging state prior
+to the request was mandatory (on or off), the state is changed to advisory off.
+If the logging state was already advisory (either on or off), it remains
+unchanged.  If
+.I control
+is
+.B PM_LOG_ADVISORY
+and the last mandatory control for the metric was 
+.BR PM_LOG_MAYBE ,
+then logging is enabled or disabled as specified by the
+.I state
+argument, i.e. 
+.B PM_LOG_ON
+or
+.BR PM_LOG_OFF .
+When the arguments
+.I state
+and
+.I control
+specify a request to change the logging behavior, the 
+argument
+.I delta
+defines the logging interval in milliseconds to be applied to all metrics and
+instances identified in
+.IR request .
+.PP
+The result argument
+.I status
+returns the current logging state for each of the nominated performance
+metrics.  There is a 1:1 correspondence between the elements of
+.I request
+and
+.IR status.
+For metrics in
+.I request
+that have
+.CW pmValueSet s
+with
+.CW numval
+equal to zero, the corresponding
+.CW pmValueSet
+in
+.IR result 
+will contain a value for each available instance at the time of the call.  Each
+metric value in
+.I status
+will have the current logging state encoded in it.  The detailed outcome of the
+operation for each metric can be determined by comparing these values to that
+requested via
+.IR control ,
+.I state
+and
+.IR delta .
+.PP
+Macros defined in
+.B <pcp/impl.h>
+may be used to extract the state and logging interval from the returned metric
+values.
+.B PMLC_GET_ON
+returns true if logging is on, or false if it is off;
+.B PMLC_GET_MAND
+returns true if logging is mandatory, or false if it is advisory;
+.B PMLC_GET_INLOG
+returns true if the metric has been logged at least once, or false otherwise;
+.B PMLC_GET_AVAIL
+returns true if the metric was available from its source the last time it was
+supposed to be logged, or false if it was unavailable; and
+.B PMLC_GET_DELTA
+returns the current logging interval for the metric (in milliseconds).
+.B PMLC_MAX_DELTA
+defines the greatest
+.I delta 
+that can be returned in an encoded metric value.
+.PP
+As a special case, when
+.I control
+is
+.BR PM_LOG_ENQUIRE ,
+.I state
+and
+.I delta
+are ignored, and
+.I status
+returns the current logging state of the nominated performance metrics (this
+variant makes no changes to the logging state).
+.PP
+If the value of the logging interval is 0, either for
+.I delta
+in a request to change state to
+.BR PM_LOG_ON ,
+or encoded in the value returned from
+.BR PM_LOG_ENQUIRE ,
+then this corresponds to the special ``once only'' logging of metrics
+that appear once in the archive log, and are never logged again.
+.PP
+.B __pmControlLog
+returns zero on success.
+.SH NOTE
+This routine is not thread-safe as there is no serialization on the
+use of the communication channel between the sending of the request
+and receiving the reply.
+It is assumed that the caller is single-threaded,
+which is true for the only current user of this routine, namely
+.BR pmlc (1).
+.SH SEE ALSO
+.BR pmlc (1),
+.BR pmlogger (1),
+.BR PMAPI (3),
+.BR pmFetch (3)
+and
+.BR __pmConnectLogger (3).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_TOOSMALL\f1
+The number of metrics in
+.I request
+is less than one.
+.IP \f3PM_ERR_VALUE\f1
+One or more of the
+.CW pmValueSet s
+in
+.I request
+had
+.CW numval
+(the number of instances) less than one.
+.IP \f3EINVAL\f1
+An invalid combination of
+.I control
+and
+.I state
+was specified, or
+.I delta
+was negative.
diff --git a/man/man3/pmconverttime.3 b/man/man3/pmconverttime.3
new file mode 100644
index 0000000..e882e6c
--- /dev/null
+++ b/man/man3/pmconverttime.3
@@ -0,0 +1,81 @@
+'\"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 PMCONVERTTIME 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3__pmConvertTime\f1 \- convert \fBtm\fR structure to \fBtimeval\fR structure
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int __pmConvertTime(struct tm *\fItmin\fP, struct timeval *\fIorigin\fP, struct\ timeval\ *\fIrslt\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B __pmConvertTime
+accepts a
+.B tm
+structure that has been filled in by
+.BR __pmParseCtime (3)
+and a reference time point
+.BR origin ,
+and fills in the given
+.B rslt
+structure with the time the user meant when he specified a partial
+.B ctime
+or positive or negative time
+.BR interval .
+.PP
+Typically, the argument
+.B origin
+is the start time for a PCP archive log, unless the user specified
+a negative
+.B interval
+offset, in which case it is the end
+time of the log.
+.PP
+.B __pmConvertTime
+returns 0 if successful.  
+It returns \-1 and writes an error message to
+.BR stderr ,
+if an error is detected.
+.PP
+Use
+.BR pmNewZone (3),
+.BR pmNewContextZone (3)
+or
+.BR pmUseZone (3)
+to establish a new current timezone that will effect
+.BR __pmConvertTime .
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmNewContextZone (3),
+.BR pmNewZone (3),
+.BR pmParseInterval (3),
+.BR pmParseTimeWindow (3),
+.BR pmUseZone (3),
+.BR __pmParseCtime (3)
+and
+.BR __pmParseTime (3).
diff --git a/man/man3/pmconvscale.3 b/man/man3/pmconvscale.3
new file mode 100644
index 0000000..bba7c67
--- /dev/null
+++ b/man/man3/pmconvscale.3
@@ -0,0 +1,124 @@
+'\"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 PMCONVSCALE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmConvScale\f1 \- rescale a performance metric value
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmConvScale(int \fItype\fP, const pmAtomValue *\fIival\fP, const\ pmUnits\ *\fIiunit\fP, pmAtomValue\ *\fIoval\fP, const\ pmUnits\ *\fIounit\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+All performance metric values may be encoded in a
+.CW pmAtomValue
+union, defined as follows;
+.PP
+.ft CW
+.nf
+.in +0.5i
+typedef union {
+    __int32_t    l;     /* 32-bit signed */
+    __uint32_t   ul;    /* 32-bit unsigned */
+    __int64_t    ll;    /* 64-bit signed */
+    __uint64_t   ull;   /* 64-bit unsigned */
+    float        f;     /* 32-bit floating point */
+    double       d;     /* 64-bit floating point */
+    char         *cp;   /* char ptr */
+    pmValueBlock *vbp;  /* pmValueBlock ptr */
+} pmAtomValue;
+.in
+.fi
+.ft 1
+.PP
+The encoding of a performance metric's dimensionality and scale uses
+a
+.CW pmUnits
+structure; see
+.BR pmLookupDesc (3).
+.PP
+Given a performance metric value pointed to by
+.I ival
+multiply it by a scale factor and return the value in
+.IR oval .
+The scaling takes place from the units defined by
+.I iunit
+into the units defined by
+.IR ounit .
+Both input and output units must have the same dimensionality.
+.PP
+The performance metric type for both input and output values is determined by
+.IR type ,
+the value for which
+is typically extracted from a
+.CW pmDesc
+structure, following a call to
+.BR pmLookupDesc (3)
+for a particular performance metric.
+.PP
+.B pmConvScale
+is most useful when values returned via
+.BR pmFetch (3),
+(and possibly extracted using
+.BR pmExtractValue (3))
+need to be normalized
+into some canonical scale and units for the purposes of computation.
+.PP
+As a special case, if all components of the dimension are zero, then
+this is treated as synonymous with a ``count'' dimension of one,
+and so the ``count'' scale components determine the relative scaling.
+This accommodates the case where performance metrics are
+dimensionless, without special case handling on the part of the caller.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmAtomStr (3),
+.BR pmExtractValue (3),
+.BR pmFetch (3),
+.BR pmLookupDesc (3),
+.BR pmPrintValue (3),
+.BR pmTypeStr (3)
+and
+.BR pmUnitsStr (3).
+.SH DIAGNOSTICS
+.P
+.B PM_ERR_CONV
+.IP
+.I iunit
+and
+.I ounit
+have different dimensionality, or have inappropriate
+.I type
+.P
+.B PM_ERR_UNIT
+.IP
+Inappropriate
+.I iunit
+or
+.I ounit
+parameter
diff --git a/man/man3/pmctime.3 b/man/man3/pmctime.3
new file mode 100644
index 0000000..b5fd95b
--- /dev/null
+++ b/man/man3/pmctime.3
@@ -0,0 +1,83 @@
+'\"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 PMCTIME 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmCtime\f1 \- format the date and time for a reporting timezone
+.SH "C SYNOPSIS"
+.ft 3
+#include <time.h>
+.br
+#include <pcp/pmapi.h>
+.sp
+char *pmCtime(const time_t *\fIclock\fP, char *\fIbuf\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmCtime
+is very similar to
+.BR ctime (3),
+except the timezone used is the current ``reporting timezone'' (rather than the
+default
+.B TZ
+environment variable scheme), and the result is returned into a
+caller-declared buffer (rather than a private buffer).
+.PP
+Like
+.BR ctime (3)
+the time to be converted is passed via
+.IR clock ,
+and 
+the result in
+.I buf
+is fixed width fields in the format:
+.PP
+.in +1i
+Fri Sep 13 00:00:00 1986\en\e0
+.PP
+The result buffer
+.I buf
+must be at least 26 bytes long, and no attempt is made to check this.
+.B pmCtime
+returns
+.I buf
+as the value of the function.
+.PP
+The default current reporting timezone is as defined by the
+.B TZ
+environment variable, so
+.B pmCtime
+and
+.BR ctime (3)
+will initially produce similar encoding of the date and time.
+.PP
+Use
+.BR pmNewZone (3),
+.BR pmNewContextZone (3)
+or
+.BR pmUseZone (3)
+to establish a new current reporting timezone that will effect
+.B pmCtime
+but not
+.BR ctime (3).
+.SH SEE ALSO
+.BR ctime (3),
+.BR PMAPI (3),
+.BR pmLocaltime (3),
+.BR pmNewContextZone (3),
+.BR pmNewZone (3)
+and
+.BR pmUseZone (3).
diff --git a/man/man3/pmda.3 b/man/man3/pmda.3
new file mode 100644
index 0000000..20194f6
--- /dev/null
+++ b/man/man3/pmda.3
@@ -0,0 +1,743 @@
+'\"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.
+.\" 
+.\"
+.\" add in the -me strings for super and subscripts
+.ie n \{\
+.       ds [ \u\x'-0.25v'
+.       ds ] \d
+.       ds { \d\x'0.25v'
+.       ds } \u
+.\}
+.el \{\
+.       ds [ \v'-0.4m'\x'-0.2m'\s-3
+.       ds ] \s0\v'0.4m'
+.       ds { \v'0.4m'\x'0.2m'\s-3
+.       ds } \s0\v'-0.4m'
+.\}
+.TH PMDA 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3PMDA\f1 \- introduction to the Performance Metrics Domain Agent support library
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+To assist in the development of Performance Metric Domain Agents 
+.RB ( PMDA s)
+for the Performance Co-Pilot (PCP),
+a procedural interface is provided that extends the Performance Metrics
+Application Programming Interface (
+.BR PMAPI (3)) 
+library.  These procedures are designed to enable a programmer to quickly 
+build a 
+.B PMDA
+which can then be tested and refined.  However, this also 
+implies that a 
+.B PMDA
+has a particular structure which may not be suitable for 
+all applications.
+.PP
+Once you are familiar with the PCP and
+.B PMDA
+frameworks, you can quickly implement a new 
+.B PMDA
+with only a few data structures and functions.  This is covered in far greater
+detail in the
+.IR "Performance Co-Pilot Programmer's Guide" .
+.PP
+A
+.B PMDA
+is responsible for a set of performance metrics, in the sense that it must
+respond to requests from
+.BR pmcd(1)
+for information about performance metrics, instance domains, and instantiated
+values.  The
+.BR pmcd (1)
+process generates requests on behalf of performance tools that make requests
+using 
+.BR PMAPI (3)
+routines.
+.PP
+This man page contains sections of the 
+.B simple PMDA
+which is located at
+.IR $PCP_PMDAS_DIR/simple .
+.SH COMMUNICATING WITH PMCD
+Two approaches may be used for connecting a
+.B PMDA 
+to a 
+.BR pmcd (1)
+process.  A Dynamic Shared Object (DSO) can be attached by
+.BR pmcd (1)
+using
+.BR dlopen (3)
+when the
+.BR pmcd (1)
+process is started.  A procedural interface referenced through a shared data
+structure is used to handle requests from
+.BR pmcd (1)
+to the
+.BR PMDA .
+.PP
+The preferred approach is for a separate process (daemon) to communicate with 
+.BR pmcd (1)
+using the Performance Data Units (PDU) Inter-Process Communication (IPC)
+protocol.
+.PP
+All
+.BR PMDA s
+are launched and controlled by the
+.BR pmcd (1)
+process on the local host.  The requests from the clients are received by
+.BR pmcd (1)
+and forwarded to the appropriate
+.BR PMDA s.
+Responses, when required, are returned through 
+.BR pmcd (1)
+to the clients.  The requests (PDUs) that may be sent to a
+.B PMDA
+from
+.BR pmcd (1)
+are
+.BR PDU_FETCH ,
+.BR PDU_PROFILE ,
+.BR PDU_INSTANCE_REQ ,
+.BR PDU_DESC_REQ ,
+.BR PDU_TEXT_REQ 
+and
+.BR PDU_RESULT .
+.SH DEFAULT CALLBACKS FOR HANDLING PDUs
+To allow a consistent framework,
+.BR pmdaMain (3)
+can be used by a daemon
+.B PMDA
+to handle the communication protocol using the same callbacks as a DSO
+.BR PMDA .
+The structure
+.B pmdaInterface
+is used to convey the common procedural interface and state information that is
+used by 
+.BR pmcd (1)
+and a
+.BR PMDA .
+This state information includes tables describing the supported metrics and
+instance domains.
+.PP
+As most of the
+procedural interface is identical for all 
+.BR PMDA s,
+they are provided as part of
+this support library
+.RB ( pmdaProfile (3),
+.BR pmdaFetch (3),
+.BR pmdaInstance (3),
+.BR pmdaDesc (3),
+.BR pmdaText (3)
+and
+.BR pmdaStore (3)). 
+However, these routines require access to the 
+.B pmdaInterface
+state information so it must be correctly initialized using 
+.BR pmdaConnect (3),
+.BR pmdaDaemon (3),
+.BR pmdaOpenLog (3),
+.BR pmdaDSO (3),
+.BR pmdaGetOpt (3)
+and
+.BR pmdaInit (3).
+.SH INSTANCES AND INSTANCE DOMAINS
+Three structures are declared in
+.I /usr/include/pcp/pmda.h
+which provide a framework for declaring the metrics and instances supported by
+the 
+.BR PMDA .
+.PP
+Every instance requires a unique integer identifier and a unique name, as defined by
+the structure
+.BR pmdaInstid :
+.PP
+.nf
+.ft CW
+.in +0.5i
+/*
+ * Instance description: index and name
+ */
+
+typedef struct {
+    int         i_inst;        /* internal instance identifier */
+    char        *i_name;       /* external instance identifier */
+} pmdaInstid;
+.in
+.fi
+.PP
+An instance domain requires its own unique identification
+.RB ( pmInDom ),
+the number of instances the domain represents, and a pointer to an array of
+instance descriptions.  This is defined in the structure 
+.BR pmdaIndom :
+.PP
+.nf
+.ft CW
+.in +0.5i
+/*
+ * Instance domain description: unique instance id, 
+ * number of instances in this domain, and the list of 
+ * instances (not null terminated).
+ */
+
+typedef struct {
+    pmInDom     it_indom;       /* indom, filled in */
+    int         it_numinst;     /* number of instances */
+    pmdaInstid  *it_set;        /* instance identifiers */
+} pmdaIndom;
+.in
+.fi
+.ft 1
+.PP
+The
+.B simple PMDA 
+has one instance domain for 
+.IR simple . color
+with three instances
+.RI ( red ,
+.I green 
+and
+.IR blue ),
+and a second instance domain for
+.IR simple . now
+with instances which can be specified at run-time.
+These instance domains are defined as:
+.PP
+.nf
+.ft CW
+.in +0.5i
+static pmdaInstid _color[] = {
+    { 0, "red" }, { 1, "green" }, { 2, "blue" }
+};
+static pmdaInstid *_timenow = NULL;
+
+static pmdaIndom indomtab[] = {
+#define COLOR_INDOM	0
+    { COLOR_INDOM, 3, _color },
+#define NOW_INDOM 1
+    { NOW_INDOM, 0, NULL },
+};
+.in
+.fi
+.PP
+The preprocessor macros
+.B COLOR_INDOM
+and
+.B NOW_INDOM
+are used in the metric description table to identify the instance domains of
+individual metrics.  These correspond to the
+.I serial
+value in the instance domain 
+.B pmInDom
+structure (the 
+.I domain
+field is set by
+.BR pmdaInit (3)
+at run-time).  The serial value must be unique for each instance domain
+within the
+.BR PMDA . 
+.PP
+The indom table shown above which is usually passed to 
+.BR pmdaInit (3)
+does not need to be created 
+if one wants to write one's own Fetch and Instance functions.
+See 
+.BR pmdaInit (3)
+for more details.
+.SH NAMESPACE
+Every 
+.B PMDA
+has its own unique 
+.B namespace 
+using the format defined in 
+.BR pmns (5). 
+In summary, the namespace matches the names of the metrics to the unique
+identifier.  The
+.B simple PMDA
+defines five metrics:
+.IR simple . numfetch ,
+.IR simple . color ,
+.IR simple . time . user,
+.IR simple . time . sys
+and
+.IR simple . now .
+The namespace for these metrics is defined in
+.I $PCP_PMDAS_DIR/simple/pmns
+and is installed as:
+.PP
+.nf
+.ft CW
+.in +0.5in
+simple {
+    numfetch    253:0:0
+    color       253:0:1
+    time
+    now         253:2:4
+}
+
+simple.time {
+    user        253:1:2
+    sys         253:1:3
+}
+.in
+.fi
+.PP
+The domain number of
+.I 253
+is obtained from
+.IR $PCP_VAR_DIR/pmns/stdpmid .
+New 
+.BR PMDA s
+should specify a unique domain number in this file, and obtain the
+number during installation.  This allows the domain number to change by
+modifying only the file
+.IR $PCP_VAR_DIR/pmns/stdpmid .
+.PP
+The
+.I simple.time
+and
+.I simple.now
+metrics are defined in separate clusters to the other metrics which allows a
+.B PMDA
+to support more than 1024 metrics, as well as grouping similar metrics 
+together.  Therefore, the item numbers for a new cluster may be identical to 
+the item numbers in other clusters.  The 
+.B simple PMDA 
+continues to increment the item numbers to permit direct mapping (see
+.BR pmdaInit (3)).
+.PP
+The namespace file should be installed and removed with the agent using 
+.BR pmnsadd (1)
+and
+.BR pmnsdel (1).
+See the later sections on INSTALLATION and REMOVAL.
+.PP
+A simple ASCII namespace can be constructed by creating a file similar to
+.IR $PCP_PMDAS_DIR/simple/root :
+.PP
+.nf
+.ft CW
+.in +0.5i
+/*
+ * fake "root" for validating the local PMNS subtree
+ */
+
+#include "$PCP_VAR_DIR/pmns/stdpmid"
+
+root { simple }
+
+#include "pmns"
+
+.in
+.fi
+.PP
+and can be referred to with the
+.B \-n
+option in most PCP tools.
+.SH METRIC DESCRIPTIONS
+Each metric requires a description
+.RB ( pmDesc ), 
+which contains its PMID, data type specification, instance domain, semantics 
+and units (see 
+.BR pmLookupDesc (3)).
+A handle is also provided for application specific information in the
+.B pmdaMetric
+structure:
+.PP
+.nf
+.ft CW
+.in +0.5i
+/*
+ * Metric description: handle for extending description, 
+ * and the description.
+ */
+
+typedef struct {
+    void*       m_user;         /* for users external use */
+    pmDesc      m_desc;         /* metric description */
+} pmdaMetric;
+.in
+.fi
+.PP
+The 
+.B simple PMDA
+defines the metrics as:
+.PP
+.nf
+.ft CW
+.in +0.5i
+static pmdaMetric metrictab[] = {
+/* numfetch */
+    { (void *)0, 
+      { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT, 
+        { 0,0,0,0,0,0} }, },
+/* color */
+    { (void *)0, 
+      { PMDA_PMID(0,1), PM_TYPE_32, COLOR_INDOM, PM_SEM_INSTANT, 
+        { 0,0,0,0,0,0} }, },
+/* time.user */
+    { (void*)0,
+      { PMDA_PMID(1,2), PM_TYPE_DOUBLE, PM_INDOM_NULL, PM_SEM_COUNTER,
+      	{ 0, 1, 0, 0, PM_TIME_SEC, 0 } }, },
+/* time.sys */
+    { (void*)0,
+      { PMDA_PMID(1,3), PM_TYPE_DOUBLE, PM_INDOM_NULL, PM_SEM_COUNTER,
+      	{ 0, 1, 0, 0, PM_TIME_SEC, 0 } }, },
+/* now */
+    { NULL,
+      { PMDA_PMID(2,4), PM_TYPE_U32, NOW_INDOM, PM_SEM_INSTANT,
+        { 0,0,0,0,0,0 } }, },
+};
+.in
+.fi
+.PP
+The macro
+.B PMDA_PMID
+(defined in
+.IR /usr/include/pcp/pmda.h )
+is used to specify each metric's
+.I cluster
+and
+.I unit 
+number in the 
+.B __pmID_int
+structure defined in
+.IR /usr/include/pcp/impl.h .
+As with instance domains, the
+.I domain
+field is set by
+.BR pmdaInit (3)
+at run-time, however, the default domain is assumed to be defined by the
+.B PMDA 
+in the macro
+.BR MYDOMAIN .
+.PP
+The metric table shown above which is usually passed to 
+.BR pmdaInit (3)
+does not need to be created 
+if one wants to write one's own Fetch and Descriptor functions.
+See 
+.BR pmdaInit (3)
+for more details.
+.SH DSO PMDA
+A 
+.B PMDA
+that is run as a DSO is opened by 
+.BR pmcd (1)
+with
+.BR dlopen (3).
+.B pmcd
+will call the 
+.BR PMDA "'s"
+initialization function that is specified in
+.IR $PCP_PMCDCONF_PATH. 
+This function is passed a pointer to a
+.B pmdaInterface 
+structure which must be completed.  Any callbacks which are
+.I not
+the default 
+.B PMDA
+support library callbacks must be specified in the
+.B pmdaInterface
+structure. 
+.PP
+The
+.B simple PMDA 
+uses its own store and fetch callback.  
+.BR simple_fetch ()
+calls 
+.BR pmdaFetch (3)
+which requires a callback to be set with
+.BR pmdaSetFetchCallBack (3)
+as can be seen in
+.IR $PCP_PMDAS_DIR/simple/simple.c .
+.PP
+The flag
+.B _isDSO
+is used to determine if the 
+.B PMDA
+is a daemon or a DSO so that the correct initialization
+routine,
+.BR pmdaDaemon (3)
+or
+.BR pmdaDSO (3),
+is called.
+.SH DAEMON PMDA
+A 
+.B PMDA
+that is run as a daemon is forked and executed by 
+.BR pmcd (1).
+Therefore, unlike a DSO 
+.BR PMDA ,
+the starting point for a daemon 
+.B PMDA 
+is
+.BR main ().
+The agent should parse the command line arguments, create
+a log file and initialize some data structures that 
+.B pmcd
+would initialize for a DSO agent.
+.PP
+The
+.B pmdaInterface
+structure must be completely defined by the daemon
+.BR PMDA .
+The function
+.BR pmdaDaemon (3)
+can be called at the start of 
+.BR main ()
+to set most of these fields.  Command line parsing can be simplified by using
+.BR pmdaGetOpt (3),
+which is similar to 
+.BR getopt (2),
+but extracts a common set of options into the 
+.B pmdaInterface
+structure.
+.I stderr 
+can be mapped to a log file using 
+.BR pmdaOpenLog (3)
+to simplify debugging and error messages.  The connection to 
+.B pmcd
+can be made with
+.BR pmdaConnect (3)
+and the loop which handles the incoming PDUs,
+.BR pmdaMain (3),
+should be the last function called.  This can be seen in
+.IR $PCP_PMDAS_DIR/simple/simple.c .
+.PP
+The
+.BR simple_init ()
+routine is common to an agent that can be run as both a Daemon and DSO
+.BR PMDA .
+.SH HELP TEXT
+Each 
+.B PMDA
+must be able to provide 
+.B pmcd
+with the help text for each metric.  Most 
+.BR PMDA s
+use specially created files with indexes to support
+efficient retrieval of the help text.
+Tools are provided with PCP to
+create the help text files of appropriate format. See 
+.BR newhelp (1).
+.SH INSTALLATION AND REMOVAL
+A series of shell procedures are defined in 
+.I $PCP_SHARE_DIR/lib/pmdaproc.sh 
+which greatly simplify the installation and removal of a
+.BR PMDA .
+The
+.I Install
+scripts for most
+.BR PMDAs
+should only need to specify the name of the
+.B PMDA
+in
+.BR iam ,
+call
+.B _setup
+which check licenses and whether the 
+.B PMDA
+has been previously installed,
+specify the communication protocols,
+and finally call
+.BR _install .
+The 
+.I Remove
+scripts are even simpler as the communication protocols are not required.
+Further information is contained in the
+.I $PCP_SHARE_DIR/lib/pmdaproc.sh
+file.
+.SH DIAGNOSTICS
+Any 
+.B PMDA
+which uses this library can set
+.BR PMAPI (3)
+debug control variable
+.B pmDebug
+(with \-D on the command line) to 
+.B DBG_TRACE_LIBPMDA
+to enable the display of debugging information which may be useful during
+development
+(see
+.BR pmdbg (1)).
+.PP
+The
+.I status 
+field of the 
+.B pmdaInterface
+structure should be zero after 
+.BR pmdaDaemon ,
+.BR pmdaDSO ,
+.BR pmdaGetOpt ,
+.BR pmdaConnect
+and
+.B pmdaInit
+are called.  A value less than zero indicates that initialization has failed.
+.PP
+Some error messages that are common to most functions in this library are:
+.TP 15
+.BI "PMDA interface version " interface " not supported"
+Most of the functions require that the
+.I comm.version
+field of the
+.B pmdaInterface
+structure be set to
+.B PMDA_INTERFACE_2
+or later.
+.B PMDA_INTERFACE_2
+or
+.B PMDA_INTERFACE_3
+implies that the 
+.I version.two
+fields are correctly initialized,
+while
+.B PMDA_INTERFACE_4
+implies that the 
+.I version.four
+fields are correctly initialized
+(see
+.BR pmdaDaemon (3)
+and
+.BR pmdaDSO (3)).
+.SH CAVEAT
+Failing to complete any of the data structures or calling any of the library
+routines out of order may cause unexpected behavior in the
+.BR PMDA .
+.PP
+Due to changes to the
+.BR PMAPI (3)
+and
+.BR PMDA (3)
+API in the PCP 2.0 release, as described in the product release notes, 
+.BR PMDA s
+built using PCP 2.0 must specify 
+.B PMDA_INTERFACE_2
+or later and link with
+.I libpcp_pmda.so.2
+and
+.IR libpcp.so.2 .
+Pre-existing Daemon PMDAs specifying 
+.B PMDA_PROTOCOL_1
+will continue to function using the backwards compatible 
+.I libpcp_pmda.so.1
+and
+.I libpcp.so.1
+libraries and may be recompiled using the headers installed in
+.I "/usr/include/pcp1.x/"
+without any modification.  These backwards compatible headers and libraries
+are contained in the
+.I pcp.sw.compat
+subsystem.
+.SH FILES
+.TP 10
+.I /usr/include/pcp/pmda.h
+Header file for the 
+.B PMDA
+support library.
+.TP
+.I /usr/lib/libpcp_pmda.so
+Dynamic library containing 
+.B PMDA 
+support library routines.
+.TP
+.I $PCP_PMDAS_DIR/trivial
+The source of the
+.BR "trivial PMDA" .
+.TP
+.I $PCP_PMDAS_DIR/simple
+The source of the
+.BR "simple PMDA" .
+.TP
+.I $PCP_PMDAS_DIR/txmon
+The source of the
+.BR "txmon PMDA" .
+.TP
+.I $PCP_PMCDCONF_PATH
+Configuration file for
+.BR pmcd (1).
+.TP
+.I $PCP_VAR_DIR/pmns
+Location of namespace descriptions for every
+.BR PMDA .
+.TP
+.I $PCP_VAR_DIR/pmns/stdpmid
+The unique domain identifiers for each
+.BR PMDA .
+.TP
+.I $PCP_SHARE_DIR/lib/pmdaproc.sh
+Shell procedures for installing and removing a
+.BR PMDA .
+.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).
+Values for these variables may be obtained programmatically
+using the
+.IR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR dbpmda (1),
+.BR newhelp (1),
+.BR pmcd (1),
+.BR pmnsadd (1),
+.BR pmnsdel (1),
+.BR PMAPI (3),
+.BR pmdaConnect (3),
+.BR pmdaDaemon (3),
+.BR pmdaDesc (3),
+.BR pmdaDSO (3),
+.BR pmdaFetch (3),
+.BR pmdaGetOpt (3),
+.BR pmdaInit (3),
+.BR pmdaInstance (3),
+.BR pmdaMain (3),
+.BR pmdaOpenLog (3),
+.BR pmdaProfile (3),
+.BR pmdaStore (3),
+.BR pmdaText (3),
+.BR pmLookupDesc (3)
+and
+.BR pmns (5).
+.PP
+For a complete description of the
+.I pcp_pmda
+library and the PMDA development process, refer to the Insight book
+.IR "Performance Co-Pilot Programmer's Guide" .
diff --git a/man/man3/pmdaattribute.3 b/man/man3/pmdaattribute.3
new file mode 100644
index 0000000..69d1be6
--- /dev/null
+++ b/man/man3/pmdaattribute.3
@@ -0,0 +1,104 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2013 Red Hat.
+.\" 
+.\" 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 PMDAATTRIBUTE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaAttribute\f1 \- informs a PMDA about client connection attributes
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+int pmdaAttribute(int \fIcontext\fP, int \fIkey\fP, char *\fIvalue\fP, int \fIlength\fP, pmdaExt *\fIpmda\fP);
+.sp
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Metrics Domain Agent (PMDA) API (see
+.BR PMDA (3)),
+.B pmdaAttribute
+is the generic callback for responding to client connection attributes.
+These attributes include client credential information, such as user ID
+and group ID.
+.PP
+A PMDA that supports connection attributes will provide a private
+.B pmdaAttribute
+callback
+by assignment to
+.I version.six.attribute
+of the
+.I pmdaInterface
+structure, and implement custom logic for any of the attribute
+.IR key \-\c
+.I value
+pairs of interest to it.
+.PP
+All attributes are associated with a specific client context, and these
+can be uniquely identified using the
+.I ctx
+first argument.
+The PMDA should track client connections, and disconnections using the
+.BR pmdaSetEndContextCallBack (3)
+interface, as a result.
+The
+.BR pmdaGetContext (3)
+interface may be particularly helpful also.
+.PP
+All attributes are passed as 
+.IR key \-\c
+.I value
+pairs and the
+.I value
+is always passed as a null-terminated string of given
+.IR length .
+This includes numeric attributes like the user ID.
+.PP
+The most commonly used attributes would be PCP_ATTR_USERID and PCP_ATTR_GROUPID
+but others may also be optionally passed (such as PCP_ATTR_USERNAME) if they are
+available.
+Some attributes will be consumed by
+.B pmcd
+and never through passed to PMDAs, such as PCP_ATTR_PASSWORD.
+A complete list of all possible attributes can be found in the headers listed
+above, all are prefixed by PCP_ATTR.
+.SH DIAGNOSTICS
+.B pmdaAttribute
+should return either zero on success, or a negative return code
+to indicate an error in handling the attribute.
+This return code cannot be used to indicate a client should be
+disallowed access \- such functionality must be performed by the agent in
+response to callbacks for the client in question (using PM_ERR_PERMISSION
+for those specific callbacks, for that specific client.
+In other words, errors will be be passed to PMCD but there is no guarantee
+made that the error will be return to the client and result in termination
+of the client, for example.
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_PROTOCOL_6 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaDSO (3),
+.BR pmdaMain (3)
+and
+.BR pmdaGetContext (3).
diff --git a/man/man3/pmdacache.3 b/man/man3/pmdacache.3
new file mode 100644
index 0000000..d0b6726
--- /dev/null
+++ b/man/man3/pmdacache.3
@@ -0,0 +1,704 @@
+'\"! tbl | mmdoc
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2013 Red Hat.
+.\" 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 PMDACACHE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaCacheStore\f1,
+\f3pmdaCacheStoreKey\f1,
+\f3pmdaCacheLookup\f1,
+\f3pmdaCacheLookupName\f1,
+\f3pmdaCacheLookupKey\f1,
+\f3pmdaCacheOp\f1,
+\f3pmdaCachePurge\f1 \- manage a cache of instance domain information for a PMDA
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/pmda.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmdaCacheStore(pmInDom \fIindom\fP, int \fIflags\fP, const\ char\ *\fIname\fP, void\ *\fIprivate\fP);
+.br
+.ti -8n
+int pmdaCacheStoreKey(pmInDom \fIindom\fP, int \fIflags\fP, const\ char\ *\fIname\fP, int\ \fIkeylen\fP, const void\ *\fIkey\fP, void\ *\fIprivate\fP);
+.br
+.ti -8n
+int pmdaCacheLookup(pmInDom \fIindom\fP, int \fIinst\fP, char **\fIname\fP, void\ **\fIprivate\fP);
+.br
+.ti -8n
+int pmdaCacheLookupName(pmInDom \fIindom\fP, const char *\fIname\fP, int\ *\fIinst\fP, void\ **\fIprivate\fP);
+.br
+.ti -8n
+int pmdaCacheLookupKey(pmInDom \fIindom\fP, const char *\fIname\fP, int\ \fIkeylen\fP, const void\ *\fIkey\fP, char **\fIoname\fP, int\ *\fIinst\fP, void\ **\fIprivate\fP);
+.br
+.ti -8n
+int pmdaCacheOp(pmInDom \fIindom\fP, int \fIop\fP);
+.br
+.ti -8n
+int pmdaCachePurge(pmInDom \fIindom\fP, time_t \fIrecent\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.de EX
+.in +2n
+.ie t .ft C
+.el .ft B
+.ie t .sp .5v
+.el .sp
+.ta \\w' 'u*8
+.nf
+..
+.de EE
+.fi
+.ie t .sp .5v
+.el .sp
+.ft R
+.in
+..
+.SH DESCRIPTION
+The
+.B pmdaCache
+family of routines provide services to support the maintenance of
+complex instance domains for Performance Co-Pilot PMDAs.
+There is potentially one cache of information for each instance
+domain, and for each instance the cache maintains:
+.PD 0
+.IP \- 2m
+external instance name (supplied by the PMDA)
+.IP \- 2m
+internal instance identifier (assigned by
+.B pmdaCacheStore
+or calculated from a ``hint'' by
+.BR pmdaCacheStoreKey )
+.IP \- 2m
+state, where
+.B active
+instances are visible and part of the current
+instance domain, and
+.B inactive
+instances are hidden, but not forgotten;
+.B pmdaCacheStore
+or
+.B pmdaCacheStoreKey
+may be used to change the state of an instance
+.IP \- 2m
+an optional opaque pointer to data that is associated with the instance,
+but maintained by the PMDA 
+.IP \- 2m
+an optional opaque key that is used as a ``hint'' to
+.B pmdaCacheStoreKey
+when guessing the initial internal instance identifier
+.IP \- 2m
+the last time the cache was saved and the instance had been marked as
+.B active
+at some point since the previous cache load or save operation
+.PD
+.PP
+The semantics of a PCP instance domain require a number of rules to
+be followed, namely:
+.PD 0
+.IP 1. 3n
+Each internal instance identifier must be unique and in the range
+0 to 2^31\0\-\01.
+This rule is enforced by the
+.B pmdaCache
+family of routines.
+.IP 2. 3n
+The external instance name must be unique.  When the instance name
+contains a space, it is further constrained such that the name to
+the left of the first space (the short name) must also be unique.
+Refer to the INSTANCE NAME MATCHING section below.
+The PMDA must honor this rule, the
+.B pmdaCache
+family of routines will detect attempts to violate this rule.
+.IP 3. 3n
+Where an external instance name corresponds to some object or entity,
+there is an expectation that the association between the name and
+the object is fixed, e.g. ``/dev/hda'' is always the name of the same disk
+on a particular system.
+This rule is perhaps the responsibility of the PMDA, but is often
+a characteristic of the environment in which the PMDA runs.
+.IP 4. 3n
+It is preferable, although not mandatory, for the association between
+and external instance name and an internal instance identifier to
+be persistent.
+This rule is supported by the
+.B pmdaCache
+family of routines.
+.IP 5. 3n
+When opaque keys are used, the values of the keys must be unique across all
+instances within an instance domain.
+This rule is enforced by the
+.B pmdaCache
+family of routines.
+.PD
+.PP
+The visible interface to the cache is oriented towards the PMDA
+developer who is most concerned about the names of instances, while
+the details of how the rest of the PCP infrastructure
+expects the internal instance identifiers
+to be managed is not relevant.
+.PP
+Instances are updated in the cache for instance domain
+.I indom
+by calling
+.B pmdaCacheStore
+or
+.B pmdaCacheStoreKey
+with the external name of the instance passed via
+.I name.
+The opaque pointer
+.I private
+may be used to associate additional data with the entry in the cache;
+if no such data is required,
+.I private
+should be NULL.
+Any manipulation of the additional data (including allocation or
+freeing) is the responsibility of the PMDA caller, as the cache simply
+maintains the pointer to the data
+(passed via
+.IR private ).
+.PP
+For cases where the PMDA developer wishes to influence the allocation
+of internal instance identifiers, e.g. for instance domains with more
+than one natural dimension, or where there is a desire to allocate the same
+instance identifier each time the PMDA is started, even on different
+hosts,
+.B pmdaCacheStoreKey
+may be used.
+In this case, an initial ``hint'' for the instance identifier is provided
+as an opqaue key via
+the first
+.I keylen
+bytes in
+.I key
+(which could be any sort of data, including binary values)
+else if
+.I keylen
+is less than 1 or
+.I key
+is
+.B NULL
+then
+.I name
+is used as the ``hint''.
+The ``hint'' is hashed to produce an initial instance identifier in the range
+0 to 2^31\0-\01.  If this instance identifier is already allocated, then the
+value is rehashed.  This procedure is repeated until an unallocated
+instance identifier is found, or
+.B pmdaCacheStoreKey
+gives up and returns
+.BR PM_ERR_GENERIC .
+For each instance domain, the ``hint'' must be unique across all
+instances, else
+.B pmdaCacheStoreKey
+returns
+.BR PM_ERR_INST .
+.PP
+The
+.I flags
+argument controls how the instance should be processed in the cache
+as follows:
+.TP
+PMDA_CACHE_ADD
+Insert the entry into the cache if it is not already there and mark
+it
+.BR active .
+If the entry is already in the cache mark it
+.BR active .
+.TP
+PMDA_CACHE_HIDE
+Mark the entry in the cache as
+.BR inactive ,
+but remember the
+details of the association between the
+external instance name and the internal instance identifier.
+Entries that are
+.B inactive
+will be hidden from cache traversal via PMDA_CACHE_WALK_NEXT
+operations, but remain visible to
+.BR pmdaCacheLookup ,
+.B pmdaCacheLookupName
+and
+.B pmdaCacheLookupKey
+requests.
+.TP
+PMDA_CACHE_CULL
+Remove the entry from the cache.
+.PP
+On success
+.B pmdaCacheStore
+or
+.B pmdaCacheStoreKey
+will return the internal instance identifier of the associated cache
+entry.
+Valid instance identifiers are guaranteed to be unique and non-negative.
+Failure will be indicated by a negative value (suitable for decoding
+with
+.BR pmErrStr (3))
+and most likely PM_ERR_INST to indicate the requested instance is not
+in the cache, or \-EINVAL to indicate a potential violation of the
+short name uniqueness property
+(see the INSTANCE NAME MATCHING section below).
+.PP
+.B pmdaCacheLookup
+is used to search the
+entries in the cache based on the internal
+instance identifier
+.IR inst .
+.PP
+On success the return value will be PMDA_CACHE_ACTIVE or PMDA_CACHE_INACTIVE
+(depending on the
+.B active
+or
+.B inactive
+state of the cache entry),
+.I name
+(if not NULL) and
+.I private
+(if not NULL)
+will be set to the external instance name and the associate additional data
+area as provided when the instance was last activated via
+.B pmdaCacheStore 
+or
+.BR pmdaCacheStoreKey .
+.PP
+.B pmdaCacheLookup
+failure is indicated by a negative return value
+suitable for decoding with
+.BR pmErrStr (3).
+.PP
+The
+.B pmdaCacheLookup
+interface is required by the PMDA's fetch callback
+that is registered via
+.BR pmdaSetFetchCallback (3).
+Here the internal instance identifier is passed to the fetch callback
+to identifier for which instance a value is required.
+Typical usage is shown in the code fragment below.
+.EX
+static int
+foo_callback(pmdaMetric *mdesc, unsigned int inst, pmAtomValue *atom)
+{
+    mydata   *mdp;
+    char     *name;
+    int      sts;
+
+    sts = pmdaCacheLookup(mdesc->m_desc.indom, inst, &name, (void **)&mdp);
+    /*
+     * expect sts == PMDA_CACHE_ACTIVE except for cataclysmic events
+     * use mdp as required, name may be useful for diagnostics
+     */
+    ...
+.EE
+.PP
+.B pmdaCacheLookupName
+is used to search the
+entries in the cache based on the external
+instance name
+.IR name .
+.PP
+On success the return value will be PMDA_CACHE_ACTIVE or PMDA_CACHE_INACTIVE
+(depending on the
+.B active
+or
+.B inactive
+state of the cache entry),
+.I inst
+(if not NULL) and
+.I private
+(if not NULL)
+will be set to the internal instance identifier and the associate additional data
+area as provided when the instance was last activated via
+.B pmdaCacheStore
+or
+.BR pmdaCacheStoreKey .
+.PP
+.B pmdaCacheLookupName
+failure is indicated by a negative return value
+suitable for decoding with
+.BR pmErrStr (3).
+.PP
+The
+.B pmdaCacheLookupName
+interface is useful for PMDAs wishing to update an instance domain based
+on the external instance names.
+.PP
+.B pmdaCacheLookupKey
+is used to search the entries in the cache
+based on an opaque key (or ``hint'') previously used in a call to
+.BR pmdaCacheStoreKey .
+The ``hint'' is provided via the first
+.I keylen
+bytes in
+.IR key .
+For symmetry with
+.BR pmdaCacheStoreKey ,
+if
+.I keylen
+is less than 1 or
+.I key
+is
+.B NULL
+then
+.I name
+is used as the ``hint'' (although the results will be the same as
+calling
+.B pmdaCacheLookupName
+in this case).
+.PP
+On success the return value will be PMDA_CACHE_ACTIVE or PMDA_CACHE_INACTIVE
+(depending on the
+.B active
+or
+.B inactive
+state of the cache entry),
+.I oname
+(if not NULL),
+.I inst
+(if not NULL) and
+.I private
+(if not NULL)
+will be set to the external instance name, the internal instance
+identifier and the associate additional data
+area as provided when the instance was last activated via
+.B pmdaCacheStore 
+or
+.BR pmdaCacheStoreKey .
+.PP
+.B pmdaCacheLookupKey
+failure is indicated by a negative return value
+suitable for decoding with
+.BR pmErrStr (3).
+.PP
+To avoid a persistent cache growing without bound,
+.B pmdaCachePurge
+can be used to cull all entries that have
+.I not
+been
+.B active
+in the last
+.I recent
+seconds.
+For performance reasons, the time accounting is imprecise and the entries
+are timestamped
+at the time of the next cache save operation
+.I after
+the entry has been added or marked
+.B active 
+(refer to PMDA_CACHE_SAVE and PMDA_CACHE_SYNC below).
+On success
+.B pmdaCachePurge
+returns the number of culled entries, else in the case of an error
+the return value is negative (and suitable for decoding with
+.BR pmErrStr (3)).
+.PP
+.B pmdaCacheOp
+may be used to perform additional operations on the cache as follows:
+.TP
+PMDA_CACHE_LOAD
+The cache can optionally be maintained as a persistent external file,
+so that the mapping of instance names to instance identifiers is persistent
+across executions of a PMDA.
+This operation loads the cache from the external file, and then
+all new cache entries are marked
+.BR inactive ,
+and the additional
+data pointer is set to NULL.
+Entries loaded from the external file are checked against the current
+cache contents and if the instance name and instance identifiers match
+then the state in the cache (\c
+.B active
+or
+.BR inactive )
+is not changed. Should a mismatch be found (same instance name and
+different instance identifier, or same instance identifier and different
+instance name, or some but not all of the instance identifier,
+the instance name and the ``hint'' match)
+then the entry from the external file is ignored
+and a warning is issued on
+.IR stderr .
+Typically a PMDA would only
+perform this operation once per execution.
+.TP
+PMDA_CACHE_SAVE
+If any instance has been added to, or deleted from, the instance
+domain since the last PMDA_CACHE_LOAD, PMDA_CACHE_SAVE or PMDA_CACHE_SYNC
+operation, the
+.I entire
+cache is written to the external file as a bulk operation.
+This operation is provided for PMDAs that are
+.I not
+interested
+in using
+.B pmdaCachePurge
+and simply want the external file to reflect the set of known instances
+without accurate details of when they were last marked
+.BR active .
+.RS
+.PP
+Returns the number of instances saved to the external file, else 0
+if the external file was already up to date.
+.RE
+.TP
+PMDA_CACHE_STRINGS
+Annotates this cache as being a special-purpose cache used for string
+de-duplication in PMDAs exporting large numbers of string valued metrics.
+This can be used to reduce the memory footprint of the PMDA (duplicate
+strings hash to the same bucket, and are stored in memory once only).
+Key comparisons are not terminated at the first space but rather the
+entire string is used for matching.
+These are specialised caches not useful for general purpose instance
+domain handling.
+.TP
+PMDA_CACHE_SYNC
+Within an instance domain,
+if any instance has been added to, or deleted from, or marked
+.B active
+since the last PMDA_CACHE_LOAD, PMDA_CACHE_SAVE or PMDA_CACHE_SYNC
+operation, the
+.I entire
+cache is written to the external file as a bulk operation.
+This operation is similar to PMDA_CACHE_SAVE, but will save the
+instance domain more frequently so the timestamps more
+accurately match the semantics expected by
+.BR pmdaCachePurge .
+.RS
+.PP
+Returns the number of instances saved to the external file, else 0
+if the external file was already synchronized.
+.RE
+.TP
+PMDA_CACHE_CHECK
+Returns 1 if a cache exists for the specified instance domain,
+else 0.
+.TP
+PMDA_CACHE_REUSE
+When a new instance is added to the cache,
+the default strategy is to assign instance identifiers in a monotonic
+increasing
+manner.  Once the maximum possible instance identifier value has been
+assigned, the strategy changes to one where starting from 0,
+the next available unused instance identifier will be used.
+Calling
+.B pmdaCacheOp
+with PMDA_CACHE_REUSE forces an irreversible change to a second
+(reuse) strategy where the next unallocated instance identifier
+will be used.  This may be useful in cases where there is a
+desire to restrict the allocated instance identifiers to smaller
+values.  The prevailing strategy will be saved and restored across
+PMDA_CACHE_SAVE and PMDA_CACHE_LOAD operations.
+If
+.B pmdaCacheStoreKey
+is ever used, the associated instance domain will be changed to
+PMDA_CACHE_REUSE mode.
+.TP
+PMDA_CACHE_REORG
+Reorganize the cache to allow faster retrieval of
+.B active
+entries, and the cost of slower retrieval for
+.B inactive
+entries, and reclaim any culled entries.  The cache may be internally
+re-organized as entries are added, so this operation is not required
+for most PMDAs.
+.TP
+PMDA_CACHE_WALK_REWIND
+Prepares for a traversal of the cache in ascending instance identifier
+sequence.
+.TP
+PMDA_CACHE_WALK_NEXT
+Fetch the next
+.B active
+instance identifier from the cache.  Requires a prior
+call using PMDA_CACHE_WALK_REWIND and will return \-1 when all instances
+have been processed.
+.RS
+.PP
+Only one cache walk can be active at any given time, nesting calls
+to PMDA_CACHE_WALK and PMDA_CACHE_REWIND will interfere with each
+other.
+.RE
+.TP
+PMDA_CACHE_ACTIVE
+Changes
+.B every
+.B inactive
+entry in the cache to be marked
+.BR active .
+.TP
+PMDA_CACHE_INACTIVE
+Changes
+.B every
+.B active
+entry in the cache to be marked
+.BR inactive .
+.TP
+PMDA_CACHE_CULL
+Remove 
+.B every
+entry from the cache.
+.TP
+PMDA_CACHE_SIZE
+Return the number of entries in the cache (includes
+.BR active ,
+.B inactive
+and any culled entries that have not yet been reclaimed).
+.TP
+PMDA_CACHE_SIZE_ACTIVE
+Return the number of
+.B active
+entries in the cache.
+.TP
+PMDA_CACHE_SIZE_INACTIVE
+Return the number of
+.B inactive
+entries in the cache.
+.TP
+PMDA_CACHE_DUMP
+Dump the current state of the cache on
+.IR stderr .
+.TP
+PMDA_CACHE_DUMP_ALL
+Like PMDA_CACHE_DUMP, but also dump the internal hashing structures
+used to support lookup by instance name, lookup by instance identifier and
+the collision statistics for ``hint'' hashing from
+.BR pmdaCacheStoreKey .
+.PP
+.B pmdaCacheOp
+returns a non-negative value on success, and failure is indicated
+by a negative return value (suitable for decoding
+with
+.BR pmErrStr (3)).
+.SH OTHER CONSIDERATIONS
+.PP
+When the
+.B pmdaCache
+routines are used for particular instance domain,
+.B pmdaInstance (3)
+and the instance domain enumeration behind
+.BR pmdaFetch (3)
+will attempt to extract instance domain information from the cache, thereby avoiding
+reference to the
+.B pmdaIndom
+data structures that have historically been used to define instance domains
+and service instance requests.
+A PMDA can adopt a hybrid approach and choose to implement some instance
+domains via the traditional
+.B pmdaIndom
+method, and others via the
+.B pmdaCache
+approach, however attempts to manage the
+.I same
+instance domain by both
+methods will result in the
+.B pmdaCache
+method silently prevailing.
+.PP
+If
+.B all
+instances in a PMDA are to be serviced from a
+.B pmdaCache
+then a
+.B pmdaIndom
+is not required, and the
+.B pmdaInit (3)
+call becomes
+.EX
+    pmdaInit(dp, NULL, 0, metrictab, nmetrics);
+.EE
+However, the PMDA will need to explicitly initialize the
+.B indom
+field of the
+.B pmDesc
+in the
+.I metrictab
+entries, as this cannot be done by
+.BR pmdaInit (3)
+if
+.I indomtab
+is missing entries for the instance domains maintained in the cache.
+.PP
+Independent of how the instance domain is being maintained,
+to refresh an instance domain prior to a fetch or an instance domain
+operation, the standard methods of a ``wrapper'' to the
+.B pmdaInstance (3)
+and
+.B pmdaFetch (3)
+methods should be used.
+.PP
+Refer to the
+.B simple
+PMDA source code for an example use of the
+.B pmdaCache
+routines.
+.PP
+When using
+.BR pmdaCacheStoreKey ,
+if there is a desire to ensure the given ``hint'' generates the same
+initial instance identifier across all platforms, then the caller
+should ensure the endian and word-size issues are considered, e.g. if
+the natural data structure used for the
+.I key
+is an array of 32-bit integers, then
+.BR htonl (3)
+should be used on each element of the array before calling
+.B pmdaCacheStoreKey
+or
+.BR pmdaCacheLookupKey .
+.SH INSTANCE NAME MATCHING
+.PP
+The following table summarizes the ``short name'' matching semantics
+for an instance domain (caches other than PMDA_CACHE_STRINGS style).
+.TS
+box, center;
+l | l | l
+l | l | ^
+l | l | l.
+name in	\fBpmdaCacheLookup\fR	result
+cache	name
+_
+foodle	foo	no match (PM_ERR_INST)
+foo	foodle	no match (PM_ERR_INST)
+foo	foo	match
+foo bar	foo	match on short name (instance identifier)
+foo bar	foo bar	match on full name (instance identifier)
+foo	foo bar	bad match (\-EDOM)
+foo bar	foo blah	bad match (\-EDOM)
+.TE
+.SH FILES
+Cache persistence uses files with names constructed from the
+.I indom
+within the
+.B $PCP_VAR_DIR/config/pmda
+directory.
+.SH SEE ALSO
+.BR BYTEORDER (3),
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaInit (3),
+.BR pmdaInstance (3),
+.BR pmdaFetch (3),
+.BR pmdaSetFetchCallback (3),
+.BR pmErrStr (3)
+and
+.BR pmGetInDom (3).
diff --git a/man/man3/pmdachildren.3 b/man/man3/pmdachildren.3
new file mode 100644
index 0000000..d221001
--- /dev/null
+++ b/man/man3/pmdachildren.3
@@ -0,0 +1,132 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000-2004 Silicon Graphics, Inc.  All Rights Reserved.
+.\" Copyright (c) 2009 Ken McDonell.  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 PMDACHILDREN 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaChildren\f1 \- translate a PMID to a set of dynamic performance metric names
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmdaChildren(char *\fIname\fP, int \fItraverse\fP, char\ ***\fIoffspring\fP, int\ **\fIstatus\fP, pmdaExt\ *\fIpmda\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Metrics Domain Agent (PMDA) API (see
+.BR PMDA (3)),
+.BR pmdaChildren
+is the generic callback for
+returning dynamic metric names (and their status) that are descendants of
+.IR name .
+.PP
+Because implementing dynamic performance metrics requires specific
+PMDA support, and the facility is an optional component of a PMDA (most
+PMDAs do
+.B not
+support dynamic performance metrics),
+.B pmdaChildren
+is a skeleton implementation that returns
+.BR PM_ERR_NAME .
+.PP
+A PMDA that supports dynamic performance metrics will provide a private
+callback that replaces
+.B pmdaChildren
+(by assignment to
+.I version.four.children
+of the
+.I pmdaInterface
+structure)
+and takes the initial metric
+.I name
+and returns names via
+.IR offspring []
+and the leaf or non-leaf status of each via
+.IR status [].
+.PP
+If
+.I traverse
+is 0, then the behaviour is akin to
+.BR pmGetChildren (3)
+and
+.IR offspring []
+contains the relative name component for the immediate descendants of
+.IR name.
+.PP
+If
+.I traverse
+is 1, then the behaviour is akin to
+.BR pmTraversePMNS (3)
+and
+.IR offspring []
+contains the absolute names of all dynamic metrics that are decedents
+of
+.IR name .
+.PP
+The resulting list of pointers
+.I offspring
+.B and
+the values
+(the names) that the pointers reference will have been
+allocated by
+.B pmdaChildren
+with a single call to
+.BR malloc (3C),
+and the
+caller of
+.B pmdaChildren
+will call
+.BR free (\c
+.IR offspring )
+to release the space
+when it is no longer required.
+The same holds true for the 
+.I status
+array.
+.SH DIAGNOSTICS
+.B 
+pmdaChildren
+returns
+.B PM_ERR_NAME
+if the name is not recognized or cannot be translated,
+otherwise the number of descendent metric names found.
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_PROTOCOL_4 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaDSO (3),
+.BR pmdaMain (3),
+.BR pmGetChildren (3)
+and
+.BR pmTraversePMNS (3).
diff --git a/man/man3/pmdaconnect.3 b/man/man3/pmdaconnect.3
new file mode 100644
index 0000000..bbfe555
--- /dev/null
+++ b/man/man3/pmdaconnect.3
@@ -0,0 +1,164 @@
+'\"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 PMDACONNECT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaConnect\f1 \- establish a connection between a daemon PMDA and PMCD
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+void pmdaConnect(pmdaInterface *\fIdispatch\fP);
+.sp
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmdaConnect
+initializes an IPC channel between a
+.BR PMDA (3)
+and the 
+.BR pmcd (1)
+process on the local host.  The type of the connection is dependent on the 
+.I e_io
+field of the
+.B pmdaExt
+structure:
+.TP 15
+.B pmdaPipe
+Use 
+.BR stdin / stdout
+to communicate; assumes this is a pipe created by
+.B pmcd
+before the
+.BR PMDA (3)
+was launched.
+.TP
+.B pmdaInet
+Assume
+.BR pmcd (1)
+will establish a connection to an IPv4 internet domain socket set up by the
+.BR PMDA (3).
+The name or number of the port must be specified in the 
+.I e_sockname
+or
+.I e_port
+fields of the
+.B pmdaExt
+structure, respectively.
+.TP
+.B pmdaIPv6
+Assume
+.BR pmcd (1)
+will establish a connection to an IPv6 internet domain socket set up by the
+.BR PMDA (3).
+The name or number of the port must be specified in the 
+.I e_sockname
+or
+.I e_port
+fields of the
+.B pmdaExt
+structure, respectively.
+.TP
+.B pmdaUnix
+Assume
+.BR pmcd (1)
+will establish a connection to a unix domain socket set up by the
+.BR PMDA (3).
+The port number must be specified in the 
+.I e_port
+field of the 
+.B pmdaExt structure.
+.TP
+.B pmdaUnknown
+The initial value of
+.I e_io
+which defaults to using 
+.BR stdin / stdout .
+.PP
+The relevant
+.B pmdaExt
+fields are initialized by
+.BR pmdaDaemon (3)
+and set by 
+.BR pmdaGetOpt (3)
+or
+.BR pmdaGetOptions (3)
+so most PMDAs should not need to access or modify them.
+.PP
+Traditionally most PMDAs have called
+.B pmdaConnect
+after calls to
+.BR pmdaDaemon (3),
+.BR pmdaGetOptions (3)
+(or
+.BR pmdaGetOpt (3))
+and
+.BR pmdaInit (3).
+If the PMDA requires significant processing at startup to identify
+the available metrics and/or instance domains before
+.BR pmdaInit (3)
+can be called, then it risks timing out during the handshake protocol that
+starts as soon as
+.BR pmcd (1)
+launches the PMDA and does not conclude until 
+.B pmdaConnect
+is called.
+In this case, it is advisable to move the
+.B pmdaConnect
+call, so that it comes
+.I after
+the call to
+.BR pmdaGetOptions (3)
+(or
+.BR pmdaGetOpt (3))
+and
+.I before
+the call to
+.BR pmdaInit (3).
+.SH DIAGNOSTICS
+.B pmdaConnect
+will log the type of connection made to 
+.BR pmcd (1)
+if the
+.BR PMAPI (3)
+debug control variable
+.RB ( pmDebug )
+has the
+.B DBG_TRACE_LIBPMDA
+flag set.
+.PP
+If an error occurs that is unrecoverable,
+.I dispatch->status
+is set to a value less than 0, otherwise it is zero or positive.
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_INTERFACE_2 
+or later, as specified in the call to 
+.BR pmdaDaemon (3).
+.SH SEE ALSO
+.BR pmcd (1),
+.BR pipe (2),
+.BR socket (2),
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaGetOpt (3),
+.BR pmdaGetOptions (3)
+and
+.BR pmdaInit (3).
diff --git a/man/man3/pmdadaemon.3 b/man/man3/pmdadaemon.3
new file mode 100644
index 0000000..e96082d
--- /dev/null
+++ b/man/man3/pmdadaemon.3
@@ -0,0 +1,108 @@
+'\"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 PMDADAEMON 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaDaemon\f1 \- initialize the PMDA to run as a daemon
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+void pmdaDaemon(pmdaInterface *\fIdispatch\fP, int \fIinterface\fP, char\ *\fIname\fP, int\ \fIdomain\fP, char\ *\fIlogfile\fP, char\ *\fIhelptext\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmdaDaemon
+initializes the
+.B pmdaInterface
+structure to use the
+.I interface
+extensions assuming the 
+.BR PMDA (3)
+is to be run as a daemon.  The
+.B pmdaInterface
+structure is initialized with:
+.TP 15
+.I name
+The name of the agent.
+.TP
+.I domain
+The default domain number of the agent which uniquely identifies this PMDA
+from other running PMDAs.  This may be subsequently changed by a command line 
+option 
+.B \-d
+(see 
+.BR pmdaGetOpt (3)).
+.TP
+.I logfile
+The default path to the log file.  This may be replaced by the 
+.B \-l
+command line option if using 
+.BR pmdaGetOpt .
+.TP
+.I helptext
+The default path to the help text (see 
+.BR pmdaText (3).
+This may be replaced by the
+.B \-h
+command line option if using
+.BR pmdaGetOpt (3).
+If no help text is installed, or you are not using
+.BR pmdaText (3),
+then this should be set to NULL.
+.PP
+The callbacks are initialized to 
+.BR pmdaProfile (3),
+.BR pmdaFetch (3),
+.BR pmdaDesc (3),
+.BR pmdaText (3),
+.BR pmdaInstance (3)
+and
+.BR pmdaStore (3).
+.SH DIAGNOSTICS
+.TP 15
+.B Unable to allocate memory for pmdaExt structure
+In addition, the 
+.I dispatch->status
+field is set to a value less than zero.
+.TP
+.BI "PMDA interface version " interface " not supported"
+The
+.I interface
+version is not supported by 
+.BR pmdaDaemon .
+.SH CAVEAT
+The PMDA must be using
+.B PMDA_INTERFACE_2
+or later.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDSO (3),
+.BR pmdaGetOpt (3)
+and
+.BR pmdaText (3).
diff --git a/man/man3/pmdadesc.3 b/man/man3/pmdadesc.3
new file mode 100644
index 0000000..a1b0f94
--- /dev/null
+++ b/man/man3/pmdadesc.3
@@ -0,0 +1,61 @@
+'\"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 PMDADESC 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaDesc\f1 \- get the description of a metric from a PMDA
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+int pmdaDesc(pmID \fIpmid\fP, pmDesc *\fIdesc\fP, pmdaExt *\fIpmda\fP);
+.sp
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmdaDesc
+uses the standard 
+.BR PMDA (3)
+data structures to return the
+.B pmDesc
+description in
+.I desc
+for the metric identified by
+.IR pmid .
+.SH DIAGNOSTICS
+If the 
+.I pmid
+does not correspond to any metric supported by this PMDA,
+.B pmdaDesc
+returns 
+.BR PM_ERR_PMID .
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_INTERFACE_2 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaDSO (3)
+and
+.BR pmLookupDesc (3).
diff --git a/man/man3/pmdadso.3 b/man/man3/pmdadso.3
new file mode 100644
index 0000000..655d4e7
--- /dev/null
+++ b/man/man3/pmdadso.3
@@ -0,0 +1,113 @@
+'\"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 PMDADSO 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaDSO\f1 \- initialize the PMDA to run as a DSO
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmdaDSO(pmdaInterface *\fIdispatch\fP, int \fIinterface\fP, char\ *\fIname\fP, char\ *\fIhelptext\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmdaDSO
+initializes the
+.B pmdaInterface
+structure to use the
+.I interface
+extensions,
+assuming the 
+.BR PMDA (3)
+is to be run as a DSO.  The
+.B pmdaInterface
+structure is initialized with:
+.TP 15
+.I name
+The name of the agent.
+.TP
+.I helptext
+The default path to the help text (see 
+.BR pmdaText (3).
+If no help text is installed, or you are not using
+.BR pmdaText (3),
+then this should be set to NULL.
+.PP
+The callbacks are initialized to 
+.BR pmdaProfile (3),
+.BR pmdaFetch (3),
+.BR pmdaDesc (3),
+.BR pmdaText (3),
+.BR pmdaInstance (3)
+and
+.BR pmdaStore (3).
+.PP
+The
+.I interface
+structure also contains the 
+.I domain
+of the
+.BR PMDA (3),
+which is defined in the
+.BR pmcd (1)
+configuration file. The
+.I domain
+is used to initialize the metric and instance descriptors (see 
+.BR pmdaInit (3)).
+.SH DIAGNOSTICS
+.TP 15
+.B Incompatible version of pmcd detected
+When
+.BR pmcd (1)
+creates the
+.B pmdaInterface
+structure, the
+.I dispatch.comm.version
+field is set to the highest protocol that
+.BR pmcd (1)
+understands.  This message indicates that the
+.BR pmcd (1)
+process does not understand the protocol used by
+.BR pmdaDSO .
+.TP
+.B Unable to allocate memory for pmdaExt structure
+In addition, 
+.I dispatch->status
+is set to a value less than zero.
+.SH CAVEAT
+The PMDA must be using
+.B PMDA_INTERFACE_2
+or later.
+.SH SEE ALSO
+.BR pmcd (1),
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaInit (3)
+and
+.BR pmdaText (3).
diff --git a/man/man3/pmdaeventarray.3 b/man/man3/pmdaeventarray.3
new file mode 100644
index 0000000..1951edb
--- /dev/null
+++ b/man/man3/pmdaeventarray.3
@@ -0,0 +1,311 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2014 Red Hat.
+.\" Copyright (c) 2010 Ken McDonell.  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 PMDAEVENTARRAY 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+.ad l
+\f3pmdaEventNewArray\f1,
+\f3pmdaEventResetArray\f1,
+\f3pmdaEventReleaseArray\f1,
+\f3pmdaEventAddRecord\f1,
+\f3pmdaEventAddMissedRecord\f1,
+\f3pmdaEventAddParam\f1,
+\f3pmdaEventGetAddr\f1,
+\f3pmdaEventNewHighResArray\f1,
+\f3pmdaEventResetHighResArray\f1,
+\f3pmdaEventReleaseHighResArray\f1,
+\f3pmdaEventAddHighResRecord\f1,
+\f3pmdaEventAddHighResMissedRecord\f1,
+\f3pmdaEventHighResAddParam\f1,
+\f3pmdaEventHighResGetAddr\f1 \- utilities for PMDAs to build packed arrays of event records
+.br
+.ad
+.SH "C SYNOPSIS"
+.ft 3
+.nf
+#include <pcp/pmapi.h>
+#include <pcp/impl.h>
+#include <pcp/pmda.h>
+.fi
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmdaEventNewArray(void);
+.br
+.ti -8n
+int pmdaEventResetArray(int \fIidx\fP);
+.br
+.ti -8n
+int pmdaEventReleaseArray(int \fIidx\fP);
+.br
+.ti -8n
+int pmdaEventAddRecord(int \fIidx\fP, struct timeval *\fItp\fP, int\ \fIflags\fP);
+.br
+.ti -8n
+int pmdaEventAddMissedRecord(int \fIidx\fP, struct timeval *\fItp\fP, int\ \fInmissed\fP);
+.br
+.ti -8n
+int pmdaEventAddParam(int \fIidx\fP, pmID \fIpmid\fP, int \fItype\fP, pmAtomValue\ *\fIavp\fP);
+.br
+.ti -8n
+pmEventArray *pmdaEventGetAddr(int \fIidx\fP);
+.sp
+.in
+.hy
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmdaEventNewHighResArray(void);
+.br
+.ti -8n
+int pmdaEventResetHighResArray(int \fIidx\fP);
+.br
+.ti -8n
+int pmdaEventReleaseHighResArray(int \fIidx\fP);
+.br
+.ti -8n
+int pmdaEventAddHighResRecord(int \fIidx\fP, struct timespec *\fIts\fP, int\ \fIflags\fP);
+.br
+.ti -8n
+int pmdaEventAddHighResMissedRecord(int \fIidx\fP, struct timespec *\fIts\fP, int\ \fInmissed\fP);
+.br
+.ti -8n
+int pmdaEventHighResAddParam(int \fIidx\fP, pmID \fIpmid\fP, int \fItype\fP, pmAtomValue\ *\fIavp\fP);
+.br
+.ti -8n
+pmHighResEventArray *pmdaEventHighResGetAddr(int \fIidx\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+A Performance Metrics Domain Agent (PMDA) that wishes to export
+event records (or trace records) is encouraged to use a metric of
+either type
+.B PM_TYPE_EVENT
+or
+.B PM_TYPE_HIGHRES_EVENT
+to encode a group of event records into a single packed array.
+.PP
+The only difference between the two metric types is the resolution
+of the timestamp associated with each \- in high resolution form it
+is nanosecond scale (see
+.BR clock_gettime (2)),
+otherwise it is microseconds (see
+.BR gettimeofday (2)).
+For simplicity, we will only refer to the lower resolution API and
+data structures hereafter \- however, the higher resolution variants
+are all named similarly and are used in the same way.
+.PP
+The packed array of event records format is defined in
+.I <pcp/pmapi.h>
+and consists of a
+.B pmEventArray
+structure containing a variable number of
+.B pmEventRecord
+structures, each of which contains a variable number of
+.B pmEventParameter
+structures, which in turn may contain a variable length value for
+each parameter of each event record.
+.PP
+The higher resolution equivalents are defined in the same location,
+and the structures are named the same.
+Note that the
+.B pmEventParameter
+structure has no timestamp associated with it, hence it this does not
+have a high resolution counterpart.
+.PP
+The routines described here are designed to assist the PMDA developer
+in building a packed array of event records, and managing all of the
+memory allocations required to hold each instance of an array of event
+records in a contiguous buffer.  Normal use would be as part of PMDA's
+.B pmdaFetchCallBack
+method.
+.PP
+.B pmdaEventNewArray
+is used to create a new event array.  The return value is a small integer that
+is used as the
+.I idx
+parameter to the other routines to identify a specific event array.
+If needed, a PMDA can create and use multiple event arrays.
+.PP
+To start a new cycle and refill an event array from the beginning, call
+.BR pmdaEventResetArray .
+.PP
+If the PMDA has finished with an event array,
+.B pmdaEventReleaseArray
+may be used to release the underlying storage and ``close'' the event
+array so that subsequent attempts to use
+.I idx
+will return
+.BR PM_ERR_NOCONTEXT .
+.PP
+To start a new event record, use
+.BR pmdaEventAddRecord .
+The timestamp for the event record is given via
+.I tp
+and the
+.I flags
+parameter may be used to set the control field that determines the
+type of the event record \-
+.I flags
+may be the bit-wise ``or'' of one or more of the
+.B PM_EVENT_FLAG_*
+values defined in
+.I <pcp/pmapi.h>
+(but note that
+.B PM_EVENT_FLAG_MISSED
+should not be used in this context).
+.PP
+If event records have been missed, either because the PMDA cannot keep
+up or because the PMAPI client cannot keep up, then
+.B pmdaEventAddMissedRecord
+may be used.
+.I
+idx
+and
+.I tp
+have the same meaning as for
+.B pmdaEventAddRecord
+and
+.I nmissed
+is the number of event records that have been missed at this point
+in the time-series of event records.
+.B pmdaEventAddMissedRecord
+may be called multiple times for a single batch of event records
+if there are more than one ``missed event record'' episode.
+.PP
+Once an event record has been started by calling
+.BR pmdaEventAddRecord ,
+one or more event parameters may be added using
+.BR pmdaEventAddParam .
+The
+.I pmid
+and
+.I type
+parameters decribe the PMID of the parameter and the data type
+(one of the
+.B PM_TYPE_*
+values from
+.IR <pcp/pmapi.h> )
+of the value that is passed via
+.IR avp .
+.I type
+should one where the size of the value is implied by the
+.I type
+or by the length of a string value (for
+.BR PM_TYPE_STRING )
+or encoded within
+.I avp->vbp
+(for
+.BR PM_TYPE_AGGREGATE ).
+.PP
+Once the packed array has been constructed,
+.B pmdaEventGetAddr
+should be used to initialize the
+.B ea_type
+and
+.B ea_len
+fields at the start of the
+.B pmEventArray
+and return the base address of the event array
+that is assigned to the
+.B vp
+field of the
+.B pmAtomValue
+structure that the
+.B pmdaFetchCallBack
+method should return.
+.SH EXAMPLE
+The following skeletal code shows how these routines might be used.
+.PP
+.ft CW
+.ps -1
+.nf
+int             sts;
+int             myarray;
+int             first = 1;
+pmEventArray    eap;
+
+if (first) {
+   first = 0;
+   if ((myarray = pmdaEventNewArray()) < 0) {
+      // report error and fail
+   }
+}
+
+pmdaEventResetArray(myarray);
+
+// loop over all event records to be exported
+\&... {
+   struct timeval   stamp;
+   int              flags;
+
+   // establish timestamp and set flags to 0 or some combination
+   // of PM_EVENT_FLAG_POINT, PM_EVENT_FLAG_START, PM_EVENT_FLAG_ID,
+   // etc
+   if ((sts = pmdaEventAddRecord(myarray, &stamp, flags)) < 0) {
+      // report error and fail
+   }
+
+   // loop over all parameters for this event record
+   ... {
+      pmID          pmid;
+      int           type;
+      pmAtomValue   atom;
+      
+      // construct pmid, type and atom for the parameter and
+      // its value
+      if ((sts = pmdaEventAddParam(myarray, pmid, type, &atom)) < 0) {
+	 // report error and fail
+      }
+   }
+
+   // if some event records were missed (could be at the start
+   // of the exported set, or at the end, or in the middle, or
+   // a combination of multiple missed record episodes)
+   ... {
+      int              nmiss;
+      struct timeval   stamp;
+
+      if ((sts = pmdaEventAddMissedRecord(myarray, &stamp, nmiss)) < 0) {
+	 // report error and fail
+      }
+   }
+}
+
+// finish up
+eap = pmdaEventGetAddr(myarray);
+.fi
+.ps
+.ft
+.SH SEE ALSO
+.BR clock_gettime (2),
+.BR gettimeofday (2),
+.BR pmdaEventNewQueue (3),
+.BR pmdaEventNewClient (3),
+.BR PMDA (3)
+and
+.BR pmEventFlagsStr (3).
diff --git a/man/man3/pmdaeventclient.3 b/man/man3/pmdaeventclient.3
new file mode 100644
index 0000000..5230d0b
--- /dev/null
+++ b/man/man3/pmdaeventclient.3
@@ -0,0 +1,95 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2013 Red Hat.
+.\" Copyright (c) 2011 Nathan Scott.  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 PMDAEVENTCLIENT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+.ad l
+\f3pmdaEventNewClient\f1,
+\f3pmdaEventEndClient\f1,
+\f3pmdaEventClients\f1 \- client context tracking interfaces for event queues
+.br
+.ad
+.SH "C SYNOPSIS"
+.ft 3
+.nf
+#include <pcp/pmapi.h>
+#include <pcp/impl.h>
+#include <pcp/pmda.h>
+.fi
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmdaEventNewClient(int \fIcontext\fP);
+.br
+.ti -8n
+int pmdaEventEndClient(int \fIcontext\fP);
+.br
+.ti -8n
+int pmdaEventClients(pmAtomValue *\fIavp\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+A Performance Metrics Domain Agent (PMDA) that exports event records
+needs to track which clients are connected to it, in order that it can
+track which events have been sent to which clients so far.
+Only once an event has been sent to all monitoring tools that registered
+an interest can the event be discarded and any memory reclaimed.
+.PP
+The
+.BR PMDA (3)
+library provides callback routines for PMDA developers to provide custom
+handling of client connections and disconnections.
+If the PMDA is making use of the event queueing mechanism provided by
+.BR pmdaEventNewQueue (3)
+and friends, client connections and disconnections must be tracked via
+calls to
+.B pmdaEventNewClient
+and
+.B pmdaEventEndClient
+respectively.
+This allows the library to keep track of when events can be discarded
+from a queue, for example, for the
+.I context
+specified.
+This parameter is passed into the e_endCallBack function directly,
+and for other callback functions is available via the e_context field
+of the pmdaExt structure.
+Additionally, it can be queried at any time using
+.BR pmdaGetContext (3).
+.PP
+Sometimes it is useful for the PMDA to export a metric indicating the
+current count of attached clients \- this is available using the
+.B pmdaEventClients
+routine, which will fill in the
+.I avp
+pmAtomValue structure on behalf of a PMDA fetch callback routine.
+.SH SEE ALSO
+.BR pmdaEventNewArray (3),
+.BR pmdaEventNewQueue (3),
+.BR PMAPI (3),
+.BR PMDA (3)
+and
+.BR pmEventFlagsStr (3).
diff --git a/man/man3/pmdaeventqueue.3 b/man/man3/pmdaeventqueue.3
new file mode 100644
index 0000000..43f243b
--- /dev/null
+++ b/man/man3/pmdaeventqueue.3
@@ -0,0 +1,190 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2011-2012 Nathan Scott.  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 PMDAEVENTQUEUE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+.ad l
+\f3pmdaEventNewQueue\f1,
+\f3pmdaEventNewActiveQueue\f1,
+\f3pmdaEventQueueHandle\f1,
+\f3pmdaEventQueueAppend\f1,
+\f3pmdaEventQueueRecords\f1,
+\f3pmdaEventQueueClients\f1,
+\f3pmdaEventQueueCounter\f1,
+\f3pmdaEventQueueBytes\f1,
+\f3pmdaEventQueueMemory\f1 \- utilities for PMDAs managing event queues
+.br
+.ad
+.SH "C SYNOPSIS"
+.ft 3
+.nf
+#include <pcp/pmapi.h>
+#include <pcp/impl.h>
+#include <pcp/pmda.h>
+.fi
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmdaEventNewQueue(const char *\fIname\fP, size_t \fImaxmem\fP);
+.br
+.ti -8n
+int pmdaEventNewActiveQueue(const char *\fIname\fP, size_t \fImaxmem\fP,  int \fInclients\fP);
+.br
+.ti -8n
+int pmdaEventQueueHandle(const char *\fIname\fP);
+.br
+.ti -8n
+int pmdaEventQueueAppend(int \fIhandle\fP, void *\fIbuffer\fP, size_t \fIbytes\fP, struct timeval *\fItv\fP);
+.br
+.sp
+.in
+.hy
+.ad
+.in +8n
+.ti -8n
+typedef int (*pmdaEventDecodeCallBack)(int, void *, int, struct timeval *, void *);
+.br
+.ti -8n
+int pmdaEventQueueRecords(int \fIhandle\fP, pmAtomValue *\fIavp\fP, int \fIcontext\fP, pmdaEventDecodeCallBack \fIdecoder\fP, void *\fIdata\fP);
+.br
+.ti -8n
+int pmdaEventQueueClients(int \fIhandle\fP, pmAtomValue *\fIavp\fP);
+.br
+.ti -8n
+int pmdaEventQueueCounter(int \fIhandle\fP, pmAtomValue *\fIavp\fP);
+.br
+.ti -8n
+int pmdaEventQueueBytes(int \fIhandle\fP, pmAtomValue *\fIavp\fP);
+.br
+.ti -8n
+int pmdaEventQueueMemory(int \fIhandle\fP, pmAtomValue *\fIavp\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+A Performance Metrics Domain Agent (PMDA) that exports event records
+must effectively act an event multiplexer.
+Events consumed by the PMDA may have to be forwarded on to any number
+of monitoring tools (or "client contexts").
+These tools may be requesting events at different sampling intervals,
+and are very unlikely to request an event at the exact moment it arrives
+at the PMDA, making some form of event buffering and queueing scheme a
+necessity.
+Events must be held by the PMDA until either all registered clients
+have been sent them, or until a memory limit has been reached by the
+PMDA at which point it must discard older events as new ones arrive.
+.PP
+The routines described here are designed to assist the PMDA developer
+in managing both client contexts and queues of events at a high level.
+These fit logically above lower level primitives, such as those
+described in
+.BR pmdaEventNewArray (3),
+and shield the average PMDA from the details of directly building event
+record arrays for individual client contexts.
+.PP
+The PMDA registers a new queue of events using either
+.B pmdaEventNewQueue
+or
+.BR pmdaEventNewActiveQueue .
+These are passed an identifying
+.I name
+(for diagnostic purposes, and for subsequent lookup by
+.BR pmdaEventQueueLookup )
+and
+.IR maxmem ,
+an upper bound on the memory (in bytes) that can be consumed by events
+in this queue, before beginning to discard them (resulting in "missed"
+events for any client that has not kept up).
+If a queue is dynamically allocated (such that the PMDA may already have
+clients connected) the
+.B pmdaEventNewActiveQueue
+interface should be used, with the additional
+.I numclients
+parameter indicating the count of active client connections.
+The return is a negative error code on failure, suitable for decoding
+by the
+.BR pmErrStr (3)
+routine.
+Any non-negative value indicates success, and provides a
+.I handle
+suitable for passing into the other API routines.
+.PP
+For each new event received by the PMDA, the
+.B pmdaEventQueueAppend
+routine should be called, placing that event into the queue identified
+by
+.IR handle .
+The event itself must be contained in the passed in
+.IR buffer ,
+having
+.I bytes
+length.
+The timestamp associated with the event (time at which the event
+occurred) is passed in via the final
+.I tv
+parameter.
+.PP
+In the PMDAs specific implementation of its fetch callback, when values
+for an event metric have been requested, the
+.BR pmdaEventQueueRecords
+routine should be used.
+It is passed the queue
+.I handle
+and the
+.I avp
+pmAtomValue structure to fill with event records, for the client making
+that fetch request (identified by the 
+.I context
+parameter).
+Finally, the PMDA must also pass in an event decoding routine, which is
+responsible for decoding the fields of a single event into the individual
+event parameters of that event.
+The
+.I data
+parameter is an opaque cookie that can be used to pass situation-specific
+information into each
+.I decoder
+invocation.
+.PP
+Under some situations it is useful for the PMDA to export state about
+the queues under its control.
+The accessor routines \- 
+.BR pmdaEventQueueClients ,
+.BR pmdaEventQueueCounter ,
+.BR pmdaEventQueueBytes
+and
+.BR pmdaEventQueueMemory
+provide a mechanism for querying a queue by its
+.I handle
+and filling in a
+.B pmAtomValue
+structure that the
+.B pmdaFetchCallBack
+method should return.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaEventNewClient (3)
+and
+.BR pmdaEventNewArray (3).
diff --git a/man/man3/pmdafetch.3 b/man/man3/pmdafetch.3
new file mode 100644
index 0000000..63a083b
--- /dev/null
+++ b/man/man3/pmdafetch.3
@@ -0,0 +1,397 @@
+'\"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 PMDAFETCH 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaFetch\f1,
+\f3pmdaSetFetchCallBack\f1 \- fill a pmResult structure with the requested metric values
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmdaFetch(int \fInumpmid\fP, pmID *\fIpmidlist\fP, pmResult **\fIresp\fP, pmdaExt\ *\fIpmda\fP);
+.br
+.ti -8n
+void pmdaSetFetchCallBack(pmdaInterface *\fIdispatch\fP, pmdaFetchCallBack\ \fIcallback\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmdaFetch
+is a generic callback used by a 
+.BR PMDA (3)
+to process a fetch request from
+.BR pmcd (1).
+The request from
+.B pmcd
+is initiated by a client calling
+.BR pmFetch (3).
+.PP
+This is the only generic callback in
+.I libpcp_pmda
+(see
+.BR PMDA (3))
+that is incomplete, requiring
+a further
+.B pmdaFetchCallBack
+method of its own.  The additional callback should be registered using
+.B pmdaSetFetchCallBack
+and the
+.B pmdaFetchCallBack
+method has the following prototype:
+.nf
+.ft CW
+.ps -1
+int func(pmdaMetric *mdesc, unsigned int inst, pmAtomValue *avp)
+.ps
+.ft
+.fi
+.PP
+.B pmdaFetch
+will allocate and resize the
+.I resp
+result structure, to store values for the
+.I numpmid 
+metrics listed in
+.IR pmidlist .
+.PP
+For each instance listed in the profile (see
+.BR pmdaProfile (3))
+of each metric listed in 
+.IR pmidlist ,
+the
+.B pmdaFetchCallBack
+method is called to fill the 
+.B pmAtomValue
+structure identified by
+.I avp
+with a value for a specific metric-instance pair identified
+by the metric descriptor
+.I mdesc
+and the instance
+.IR inst .
+This value is then copied into the
+.B pmResult
+structure.
+.PP
+The
+.B pmdaFetchCallBack
+method should return a value less than zero for an error, and the most
+likely cases would be
+.B PM_ERR_PMID
+if the metric identified by
+.I mdesc
+is not known to the method, or
+.B PM_ERR_INST
+if the method believes the instance
+.I inst
+is not known for the metric identified by
+.IR mdesc .
+.PP
+The success error codes depend on the version of
+.B PMDA_INTERFACE
+the PMDA is using.
+.PP
+If the PMDA is using
+.B PMDA_INTERFACE_2 
+then on success the
+.B pmdaFetchCallBack
+method should return
+.BR 0 .
+.PP
+If the PMDA is using
+.B PMDA_INTERFACE_3 
+or
+.B PMDA_INTERFACE_4 
+then on success the
+.B pmdaFetchCallBack
+method should return
+.B 1
+if a value is returned via
+.IR avp ,
+else
+.B 0
+if no values are currently available for the requested metric-instance pair
+although
+.I mdesc
+and
+.I inst
+both seem reasonable.
+.PP
+If the PMDA is using
+.B PMDA_INTERFACE_5 
+or later then on success the
+.B pmdaFetchCallBack
+method should return
+.B PMDA_FETCH_STATIC
+(\c
+.BR 1 )
+if the value returned via
+.I avp
+can be ignored by
+.B pmdaFetch
+once it has been copied into the
+.B pmResult
+structure, else
+.B PMDA_FETCH_DYNAMIC
+(\c
+.BR 2 )
+if the value returned via
+.I avp
+uses the either the
+.B vp
+or
+.B cp
+fields of the
+.B pmAtomValue
+and the associated value (buffer) was allocated using
+one of
+.BR malloc (3),
+.BR calloc (3),
+.BR realloc (3),
+.B strdup (3)
+etc. and 
+.B pmdaFetch
+should release the memory by calling
+.IR free (3)
+once a new buffer has been allocated and the value copied,
+else
+.B PMDA_FETCH_NOVALUES
+(\c
+.BR 0 )
+if no values are currently available for the requested metric-instance pair
+although
+.I mdesc
+and
+.I inst
+both seem reasonable.
+.PP
+If the
+.B pmdaFetchCallBack
+method returns a value for an instance of a metric of type
+.B PM_TYPE_STRING
+or
+.B PM_TYPE_AGGREGATE
+some special care is needed \(en
+the method should either use a static buffer, set
+.I avp->cp
+or
+.I avp->vp
+to the address of the buffer and return
+.BR PMDA_FETCH_STATIC ,
+or use a dynamically allocated buffer, keep a static reference to
+the buffer's address, return
+.B PMDA_FETCH_STATIC
+and
+.I free (3)
+or
+.I realloc (3)
+or reuse the buffer the next time the
+.B pmdaFetchCallBack
+method is called,
+else use a dynamically allocated buffer
+and return
+.BR PMDA_FETCH_DYNAMIC .
+.SH EXAMPLE
+.PP
+The following code fragments are for a hypothetical PMDA has with metrics (A, B, C and D) and an instance
+domain (X) with two instances (X1 and X2).  The instance domain and
+metrics description tables (see
+.BR pmdaInit (3))
+could be defined as:
+.PP
+.nf
+.ft CW
+.ps -1
+.in +0.5i
+static pmdaInstid _X[] = {
+    { 0, "X1" }, { 1, "X2" }
+};
+.sp 0.5v
+static pmdaIndom indomtab[] = {
+#define X_INDOM 0
+    { 0, 2, _X },
+};
+.sp 0.5v
+static pmdaMetric metrictab[] = {
+/* A */
+    { (void *)0, 
+      { PMDA_PMID(0,0), PM_TYPE_32, PM_INDOM_NULL,
+        PM_SEM_INSTANT, {0,0,0,0,0,0} }, },
+/* B */
+    { (void *)0, 
+      { PMDA_PMID(0,1), PM_TYPE_DOUBLE, X_INDOM,
+        PM_SEM_INSTANT, {0,1,0,0,PM_TIME_SEC,0} }, },
+/* C */
+    { (void *)0, 
+      { PMDA_PMID(0,2), PM_TYPE_STRING, PM_INDOM_NULL,
+        PM_SEM_INSTANT, {0,0,0,0,0,0} }, },
+/* D */
+    { (void *)0, 
+      { PMDA_PMID(0,3), PM_TYPE_STRING, PM_INDOM_NULL,
+        PM_SEM_INSTANT, {0,0,0,0,0,0} }, },
+};
+.in
+.ps
+.ft
+.fi
+.br
+.PP
+A
+.B pmdaFetchCallBack
+method to be called from
+.B pmdaFetch
+could be defined as:
+.PP
+.nf
+.ft CW
+.ps -1
+.in +0.5i
+int
+myFetchCallBack(pmdaMetric *mdesc, unsigned int inst, pmAtomValue *avp)
+{
+  static char sbuf[20]; // reuse this buffer
+  char        *dbuf;    // malloc'd
+.sp 0.5v
+  switch (pmid_item(mdesc->m_desc.pmid)) {
+    case 0:
+      /* assign some value for metric A */;
+      avp->l = ...
+      break;
+    case 1:
+      switch (inst) {
+          case 0:
+	      /* assign a value for metric B, instance X1 */;
+              avp->d = ...
+              break;
+          case 1:
+	      /* assign a value for metric B, instance X2 */;
+              avp->d = ...
+              break;
+          default:
+              return PM_ERR_INST;
+      }
+    case 2:
+      /* place value for metric C in dbuf[] */
+      memcpy(dbuf, ...);
+      avp->cp = dbuf;
+      break;
+    case 3:
+      avp->cp = (char *)malloc(somesize);
+      /* place value in avp->cp */
+      snprintf(avp->cp, somesize, ...);
+      return PMDA_FETCH_DYNAMIC;
+.sp 0.5v
+    default:
+      return PM_ERR_PMID;
+  }
+  return PMDA_FETCH_STATIC;
+}
+.in
+.ps
+.ft
+.fi
+.PP
+.SH DIAGNOSTICS
+The following error messages indicate that there is discrepancy between the
+namespace, 
+.B pmdaMetric
+and
+.B pmdaIndom
+tables passed to
+.BR pmdaInit (3),
+and the registered fetch callback:
+.TP 15
+.BI "pmdaFetch: Requested metric " metric " is not defined"
+A requested metric
+.I metric
+is not listed in the 
+.B pmdaMetric
+table.  The namespace for this 
+.BR PMDA (3)
+may contain additional metrics.
+.TP
+.BI "pmdaFetch: PMID " pmid " not handled by fetch callback"
+The
+.B pmdaFetchCallBack
+method has returned
+.BR PM_ERR_PMID .
+This indicates that a metric may be listed in the
+.B pmdaMetric
+table, but is not supported by the callback method.
+.TP
+.BI "pmdaFetch: Instance " inst " of PMID " pmid " not handled by fetch callback"
+The
+.B pmdaFetchCallBack
+method has returned
+.BR PM_ERR_INST .
+This indicates that an instance of metric is listed in the
+.B pmdaIndom
+table, but is not supported by the callback method.
+.TP
+.B pmdaFetch: Fetch callback error:
+The
+.B pmdaFetchCallBack
+method returned a result other than 
+.BR PMDA_FETCH_NOVALUES ,
+.BR PMDA_FETCH_STATIC ,
+.BR PMDA_FETCH_DYNAMIC ,
+.B PM_ERR_PMID
+or
+.BR PM_ERR_INST .
+.TP
+.BI "pmdaFetch: Descriptor type (" type ") for metric " pmid " is bad"
+The data type 
+.I type
+specified for the metric
+.I pmid
+in the
+.B pmdaMetric
+table is illegal.
+.PP
+.B pmdaFetch
+will return
+.B \-errno
+if an error occurred while allocating the
+.B pmResult
+structure or copying the value from the
+.BR pmAtomValue .
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_INTERFACE_2 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.SH SEE ALSO
+.BR pmcd (1),
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaDSO (3),
+.BR pmdaInit (3)
+and
+.BR pmFetch (3).
diff --git a/man/man3/pmdagetoptions.3 b/man/man3/pmdagetoptions.3
new file mode 100644
index 0000000..cc4c419
--- /dev/null
+++ b/man/man3/pmdagetoptions.3
@@ -0,0 +1,239 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2014 Red Hat.
+.\" 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 PMDAGETOPTIONS 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaGetOpt\f1,
+\f3pmdaGetOptions\f1 \- get options from arguments, parsing generic PMDA options
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmdaGetOptions(int \fIargc\fP, char *const *\fIargv\fP, pmdaOptions *\fIopts\fP, pmdaInterface\ *\fIdispatch\fP);
+.sp
+.in
+.hy
+.ad
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmdaGetOpt(int \fIargc\fP, char *const *\fIargv\fP, const\ char\ *\fIoptstring\fP, pmdaInterface\ *\fIdispatch\fP, int\ *\fIerr\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+These functions are wrappers for
+.BR pmgetopt_r (3).
+The behavior of each function is that certain options are
+assumed to have a predefined behavior which initializes
+several fields in the
+.B pmdaInterface
+structure.
+The
+.B pmdaGetOptions
+interface allows both short and long options to be given,
+whereas
+.B pmdaGetOpt
+allows for short form options only.
+.PP
+The options that both
+.B pmdaGetOptions
+and
+.B pmdaGetOpt
+will trap are:
+.TP 15
+.BI \-D trace
+Set the 
+.BR PMAPI (3)
+debug control variable
+.RB ( pmDebug )
+to 
+.IR trace .
+Used for controlling levels of trace output while debugging.
+.TP
+.BI \-d domain
+Set the 
+.I domain
+number of this agent.
+.TP
+.BI \-h helpfile
+Obtain the help text (see
+.BR pmdaText (3))
+for the metrics from this file rather than from the path specified with
+.BR pmdaDSO (3)
+or
+.BR pmdaDaemon (3).
+.TP
+.BI \-i port
+Expect PMCD to connect on inet 
+.I port
+(number or name).
+.TP
+.BI \-6 port
+Expect PMCD to connect on ipv6 
+.I port
+(number or name).
+.TP
+.BI \-l logfile
+Redirect diagnostics and trace output to 
+.IR logfile .
+.TP
+.B \-p
+Expect PMCD to supply stdin/stdout pipe.
+.TP
+.BI \-u socket
+Expect PMCD to connect on unix domain 
+.IR socket .
+.PP
+The
+.B pmdaGetOptions
+interface will also capture the following options, and store them
+within the
+.I opts
+parameter:
+.TP 15
+.BI \-U username
+Set the user account name under which the PMDA should execute.
+.PP
+Only one of 
+.BR \-i ,
+.BR \-6 ,
+.BR \-p 
+and
+.B \-u
+may be specified.  If none of these three options is given, a pipe 
+.RB ( \-p )
+is assumed.  When these options are encountered by
+.BR pmdaGetOpt ,
+the option is processed and the next option is examined.  Therefore,
+.B pmdaGetOpt
+will only return when an option other than those listed above is found, or the
+end of the list is reached.  The returned value will be the argument or
+EOF, respectively.
+.PP
+A PMDA can control which of these options the program will accept with
+either the
+.I opts
+or
+.I optstring
+argument.  To accept all the options, the PMDA should call
+.B pmdaGetOptions
+with the short_options field of the
+.I opts
+structure set to the PMDA_OPTIONS macro,
+or
+.B pmdaGetOpt
+with the option string "D:d:h:i:l:pu:".
+Any PMDA specific options should be added to these strings in the style of
+.BR getopt (3),
+and will be returned by both
+.B pmdaGetOptions
+and
+.B pmdaGetOpt
+if encountered.
+.PP
+When a command line option usage error is detected in the
+.B pmdaGetOptions
+interface, the error field of the
+.I opts
+structure will contain a non-zero error count.
+.PP
+.B pmdaGetOpt
+takes a pointer to an int,
+.IR err ,
+which is used as an error count.  This variable should be initialized to zero
+before 
+.B pmdaGetOpt 
+is first called, and tested when
+.B pmdaGetOpt
+returns EOF.
+.PP
+Neither
+.B pmdaGetOptions
+nor
+.B pmdaGetOpt
+modify their
+.I argc
+or
+.I argv
+parameters.
+.PP
+The global variables used by the system
+.B getopt (3)
+interface may also be used by the caller of
+.B pmdaGetOpt
+within the argument parsing loop.
+.PP
+On the other hand, the
+.B pmdaGetOptions
+interface does not utilize global variables at all (neither reading
+nor modifying them).
+Instead, these variables can be access via the
+.I opts
+fields of the same name.
+.SH DIAGNOSTICS
+Both
+.B pmdaGetOptions
+and
+.B pmdaGetOpt
+will display the same error messages as 
+.BR getopt .
+.SH CAVEAT
+The options 
+.BR \-D ,
+.BR \-d ,
+.BR \-i ,
+.BR \-l ,
+.BR \-p
+and
+.B \-u
+cannot be reused for other purposes by the PMDA, unless using the
+.I override
+method provided by the
+.B pmdaGetOptions
+interface, which operates in the same way as described for the
+.BR pmGetOptions (3)
+interface used by PMAPI client tools.
+.PP
+The PMDA must be using 
+.B PMDA_INTERFACE_2 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.SH SEE ALSO
+.BR pmdbg (1),
+.BR getopt (3),
+.BR pmgetopt_r (3),
+.BR pmGetOptions (3),
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaDSO (3)
+and
+.BR pmdaText (3).
diff --git a/man/man3/pmdahelp.3 b/man/man3/pmdahelp.3
new file mode 100644
index 0000000..5d517f0
--- /dev/null
+++ b/man/man3/pmdahelp.3
@@ -0,0 +1,102 @@
+'\"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 PMDAHELP 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaOpenHelp\f1,
+\f3pmdaGetHelp\f1,
+\f3pmdaGetInDomHelp\f1,
+\f3pmdaCloseHelp\f1 \- help text support for a PMDA
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+int pmdaOpenHelp(char *\fIfname\fP);
+.br
+char *pmdaGetHelp(int \fIhandle\fP, pmID \fIpmid\fP, int \fItype\fP);
+.br
+char *pmdaGetInDomHelp(int \fIhandle\fP, pmInDom \fIindom\fP, int \fItype\fP);
+.br
+void pmdaCloseHelp(int \fIhandle\fP);
+.sp
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Metrics Domain Agent (PMDA) API (see
+.BR PMDA (3)),
+this group of routines is used to implement the processing of a PMDA's metric
+help information.
+.PP
+These routines are really intended for internal use, and should not
+need to be called directly from any PMDA code.
+.PP
+Briefly, the base name of the help text file (as created by
+.BR newhelp (1))
+is passed in via a
+.B \-h
+command line option for a daemon PMDA or as an argument to
+.BR pmdaDaemon (3)
+or
+.BR pmdaDSO (3).
+Then
+.B pmdaOpenHelp
+is called from
+.BR pmdaInit (3)
+and returns a
+.I handle
+that is used in subsequent calls to identify a particular help
+text collection (each PMDA typically has only one such collection).
+.PP
+Requests for help text are passed to
+.BR pmdaText (3)
+which calls
+.B pmdaGetHelp
+or
+.B pmdaGetInDomHelp
+as required.
+.PP
+Other than error cases in
+.BR pmdaOpenHelp ,
+.B pmdaCloseHelp
+is not called.
+.SH DIAGNOSTICS
+.B pmdaOpenHelp
+returns a negative value for failure, suitable for decoding with
+.BR pmErrStr (3).
+.B pmdaGetHelp
+and
+.B pmdaGetInDomHelp
+return NULL if the corresponding help text does not exist.
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_PROTOCOL_2 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.SH SEE ALSO
+.BR newhelp (1),
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaDSO (3),
+.BR pmdaInit (3),
+.BR pmdaText (3)
+and
+.BR pmErrStr (3).
diff --git a/man/man3/pmdainit.3 b/man/man3/pmdainit.3
new file mode 100644
index 0000000..1a53e37
--- /dev/null
+++ b/man/man3/pmdainit.3
@@ -0,0 +1,299 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2013 Red Hat.
+.\" 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 PMDAINIT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaInit\f1,
+\f3pmdaRehash\f1,
+\f3pmdaSetFlags\f1 \- initialize a PMDA
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+void pmdaInit(pmdaInterface *\fIdispatch\fP, pmdaIndom *\fIindoms\fP, int\ \fInindoms\fP, pmdaMetric\ *\fImetrics\fP, int\ \fInmetrics\fP);
+.br
+.ti -8n
+void pmdaRehash(pmdaExt *\fIpmda\fP, pmdaMetric\ *\fImetrics\fP, int\ \fInmetrics\fP);
+.br
+.ti -8n
+void pmdaSetFlags(pmdaInterface *\fIdispatch\fP, int \fIflags\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmdaInit
+initializes a PMDA so that it is ready to receive PDUs from
+.BR pmcd (1).
+The function expects as arguments the instance domain table 
+.RI ( indoms )
+and the metric description table
+.RI ( metrics )
+that are initialized by the PMDA. The arguments
+.I nindoms
+and
+.I nmetrics
+should be set to the number of instances and metrics in the tables,
+respectively.
+.PP
+Much of the
+.B
+pmdaInterface
+structure can be automatically initialized with 
+.BR pmdaDaemon (3),
+.BR pmdaGetOpt (3)
+and
+.BR pmdaDSO (3).
+.B pmdaInit
+completes the PMDA initialization phase with three operations.
+The first operation adds the domain and instance numbers to the instance and
+metric tables.  Singular metrics (metrics without an instance domain) should
+have the instance domain
+.B PM_INDOM_NULL
+set in the
+.I indom
+field of the
+.B pmDesc
+structure (see
+.BR pmLookupDesc (3)).
+Metrics with an instance domain should set this field to be the serial number
+of the instance domain in the
+.I indoms
+table.
+.PP
+The instance domain table may be made empty by setting
+.I indoms
+to NULL and
+.I nindoms
+to 0.
+This allows the caller to provide custom Fetch and Instance callback functions.
+The metric table may be made empty by setting
+.I metrics
+to NULL and
+.I nmetrics
+to 0.
+This allows the caller to provide custom Fetch and Descriptor callback functions.
+.SH EXAMPLE
+For example, a PMDA has three metrics: A, B and C, and two instance
+domains X and Y, with two instances in each instance domain.  The instance
+domain and metrics description tables could be defined as:
+.PP
+.nf
+.ft CW
+.in +0.5i
+static pmdaInstid _X[] = {
+    { 0, "X1" }, { 1, "X2" }
+};
+
+static pmdaInstid _Y[] = {
+    { 0, "Y1" }, { 1, "Y2" }
+};
+
+static pmdaIndom indomtab[] = {
+#define X_INDOM 0
+    { X_INDOM, 2, _X },
+#define Y_INDOM 3
+    { Y_INDOM, 2, _Y }
+};
+
+static pmdaMetric metrictab[] = {
+/* A */
+    { (void *)0, 
+      { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT, 
+        { 0,0,0,0,0,0} }, },
+/* B */
+    { (void *)0, 
+      { PMDA_PMID(0,1), PM_TYPE_U32, X_INDOM, PM_SEM_INSTANT, 
+        { 0,0,0,0,0,0} }, },
+/* C */
+    { (void *)0, 
+      { PMDA_PMID(0,2), PM_TYPE_DOUBLE, Y_INDOM, PM_SEM_INSTANT, 
+        { 0,1,0,0,PM_TIME_SEC,0} }, }
+};
+.in
+.fi
+.PP
+The metric description table defines metric A with no instance domain,
+metric B with instance domain X and metric C with instance domain Y.  Metric
+C has units of seconds, while the other metrics have no units (simple counters).
+.B pmdaInit
+will take these structures and assign the
+.BR PMDA (3)
+domain number to the
+.I it_indom
+field of each instance domain.  This identifier also replaces the
+.I indom
+field of all metrics which have that instance domain, so that they are
+correctly associated.
+.PP
+The second stage opens the 
+help text file, if one was specified with the
+.B \-h
+command line option (see
+.BR pmdaGetOpt (3))
+or as a
+.I helptext
+argument to
+.BR pmdaDSO (3)
+or
+.BR pmdaDaemon (3).
+.PP
+The final stage involves preparing the metric table lookup strategy.
+.SH "METRIC LOOKUP"
+When fetch and descriptor requests are made of the PMDA, each
+requested PMID must be mapped to a metric table entry.
+There are currently three strategies for performing this mapping \-
+direct, linear and hashed.
+Each has its own set of tradeoffs and an appropriate strategy
+should be selected for each PMDA.
+.PP
+If all of the metric PMID item numbers correspond to the position
+in the 
+.I metrics
+table, then direct mapping is used.
+This is the most efficient of the lookup functions as it involves
+a direct array index (no additional memory is required nor any
+additional processing overhead).
+If the PMID numbering requirement is met by the PMDA, it is ideal.
+This strategy can be explicitly requested by calling
+.BR pmdaSetFlags \c
+(\f2pmda\f1, \f2PMDA_FLAG_EXT_DIRECT\f1)
+before calling
+.BR pmdaInit .
+In this case, if the direct mapping is not possible (e.g. due to
+an oversight on the part of the PMDA developer), a warning is
+logged and the linear strategy is used instead.
+.PP
+The second strategy (linear search) is the default, when a direct
+mapping cannot be established.
+This provides greater flexibility in the PMID numbering scheme,
+as the PMDA item numbers do not have to be unique (hence, the PMID
+cluster numbers can be used more freely, which is often extremely
+convenient for the PMDA developer).
+However, lookup involves a linear walk from the start of the metric
+table until a matching PMID is found, for each requested PMID in a
+request.
+.PP
+The third strategy (hash lookup) can be requested by calling
+.BR pmdaSetFlags \c
+(\f2pmda\f1, \f2PMDA_FLAG_EXT_HASHED\f1)
+before calling
+.BR pmdaInit .
+This strategy is most useful for PMDAs with large numbers of metrics
+(many hundreds, or thousands).
+Such PMDAs will almost always use the cluster numbering scheme, so
+the direct lookup scheme becomes inappropriate.
+They may also be prepared to sacrifice a small amount of additional
+memory for a hash table, mapping PMID to metric table offsets, to
+speed up lookups in their vast metric tables.
+.PP
+This final strategy can also be used by PMDAs serving up dynamically
+numbered metrics.
+For this case, the
+.B pmdaRehash
+function should be used to replace the metric table when new metrics
+become available, or existing metrics are removed.
+The PMID hash mapping will be recomputed at the same time that the
+new metric table is installed.
+
+.SH DIAGNOSTICS
+.B pmdaInit
+will set
+.I dispatch->status
+to a value less than zero if there is an error that would prevent the 
+.BR PMDA (3)
+from successfully running.  
+.BR pmcd (1)
+will terminate the connection to the
+.BR PMDA (3)
+if this occurs.
+.PP
+.B pmdaInit
+may issue any of these messages:
+.TP 15
+.BI "PMDA interface version " interface " not supported"
+The
+.I interface
+version is not supported by 
+.BR pmdaInit .
+.TP
+.B "Using pmdaFetch() but fetch call back not set"
+The fetch callback,
+.BR pmdaFetch (3),
+requires an additional callback to be provided using
+.BR pmdaSetFetchCallBack (3).
+.TP
+.BI "Illegal instance domain " inst " for metric " pmid
+The instance domain
+.I inst
+that was specified for metric
+.I pmid
+is not within the range of the instance domain table.
+.TP
+.B No help text path specified
+The help text callback,
+.BR pmdaText (3),
+requires a help text file for the metrics to have been opened, however
+no path to the help text was specified as a command line option, or as an
+argument to
+.BR pmdaDSO (3)
+or
+.BR pmdaDaemon (3).
+This message is only a warning.
+.TP
+.BI "Direct mapping for metrics disabled @ " num
+The unit numbers of the metrics did not correspond to the index in the
+metric description table.  The direct mapping failed for metric number
+.I num
+in the
+.I metrics
+table.  This is less efficient but is not fatal and the message is only a 
+warning.
+.TP
+.BI "Hashed mapping for metrics disabled @ " num
+A memory allocation failure occurred while building the hash table to
+index the metric description table.
+This is a non-fatal warning message - a fallback to linear searching
+will be automatically performed should this situation arise.
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_INTERFACE_2 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.SH SEE ALSO
+.BR newhelp (1),
+.BR pmcd (1),
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaDSO (3),
+.BR pmdaFetch (3),
+.BR pmdaGetOpt (3),
+.BR pmdaText (3)
+and
+.BR pmLookupDesc (3).
diff --git a/man/man3/pmdainstance.3 b/man/man3/pmdainstance.3
new file mode 100644
index 0000000..8b7fd97
--- /dev/null
+++ b/man/man3/pmdainstance.3
@@ -0,0 +1,148 @@
+'\"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 PMDAINSTANCE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaInstance\f1 \- return instance descriptions for a PMDA
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmdaInstance(pmInDom \fIindom\fP, int \fIinst\fP, char *\fIname\fP, __pmInResult\ **\fIresult\fP, pmdaExt\ *\fIpmda\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmdaInstance
+uses the standard
+.BR PMDA (3)
+data structures to return information concerning the instance domain
+.IR indom .
+.PP
+The
+.I result
+structure is constructed by
+.B pmdaInstance
+and will contain one or more instance names and/or identifiers as specified by
+the 
+.I inst
+and
+.I name
+arguments.
+.PP
+If 
+.I inst
+has the value 
+.B PM_IN_NULL
+and 
+.I name
+is a null string,
+.I result
+will contain all the instances names and identifiers in the instance domain.
+.PP
+If
+.I inst
+is 
+.B PM_IN_NULL
+but
+.I name
+is the name of an instance in the instance domain
+.IR indom ,
+then
+.I result
+will contain the instance identifier for instance
+.IR name .
+Note that if 
+.I name 
+contains no spaces, partial matching up to the first space in the
+instance name is performed, i.e. 
+.RB `` 1 ''
+will match instance name 
+.RB `` 1
+.BR minute ''.
+If 
+.I name
+contains an embedded space, then no partial matching is performed and
+.I name
+should match one of the instance names exactly.
+.PP
+If 
+.I name
+is a null string but
+.I inst
+is an instance identifier in the instance domain
+.IR indom ,
+then
+.I result
+will contain the name for instance
+.IR inst .
+The
+.I result
+structure is allocated with
+.BR malloc (3)
+and should be released by the caller with
+.BR free (3).
+.SH DIAGNOSTICS
+If any errors occur during the execution of
+.BR pmdaInstance ,
+the
+.I result
+structure is deallocated.  If the instance domain
+.I indom
+is not supported by the PMDA, 
+.B pmdaInstance
+will return
+.BR PM_ERR_INDOM .
+.PP
+If the
+.I inst
+or
+.I name
+does not correspond to any instances in the 
+.I indom
+domain, 
+.B pmdaInstance
+will return
+.BR PM_ERR_INST .
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_INTERFACE_2 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.PP
+Because of optional partial matching up to the first space in the instance 
+name, the
+.B PMDA
+developer should ensure that if instance names are allowed to have
+spaces, the names are unique up to the first space.
+.SH SEE ALSO
+.BR malloc (3),
+.BR PMAPI (3),
+.BR PMDA (3)
+and
+.BR pmGetInDom (3).
diff --git a/man/man3/pmdamain.3 b/man/man3/pmdamain.3
new file mode 100644
index 0000000..41550a9
--- /dev/null
+++ b/man/man3/pmdamain.3
@@ -0,0 +1,299 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2013 Red Hat.
+.\" 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 PMDAMAIN 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaMain\f1,
+\f3pmdaGetContext\f1,
+\f3pmdaSetResultCallBack\f1,
+\f3pmdaSetCheckCallBack\f1,
+\f3pmdaSetDoneCallBack\f1,
+\f3pmdaSetEndContextCallBack\f1 \- generic PDU processing for a PMDA
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+cc ... \-lpcp_pmda \-lpcp
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+void pmdaMain(pmdaInterface *\fIdispatch\fP);
+.br
+.ti -8n
+void pmdaSetCheckCallBack(pmdaInterface *\fIdispatch\fP, pmdaCheckCallBack\ \fIcallback\fP);
+.br
+.ti -8n
+void pmdaSetDoneCallBack(pmdaInterface *\fIdispatch\fP, pmdaDoneCallBack\ \fIcallback\fP);
+.br
+.ti -8n
+void pmdaSetResultCallBack(pmdaInterface *\fIdispatch\fP, pmdaResultCallBack\ \fIcallback\fP);
+.br
+.ti -8n
+void pmdaSetEndContextCallBack(pmdaInterface *\fIdispatch\fP, pmdaEndContextCallBack\ \fIcallback\fP);
+.br
+.ti -8n
+int pmdaGetContext(void);
+.sp
+.in
+.hy
+.ad
+.ft 1
+.SH DESCRIPTION
+For Performance Metric Domain Agents 
+.RB ( PMDA (3)) 
+using the binary PDU protocols to communicate with
+.BR pmcd (1),
+the routine
+.B pmdaMain
+provides a generic implementation of the PDU-driven main loop. 
+.PP
+.I dispatch
+describes how to process each incoming PDU. It
+is a vector of function pointers, one per request PDU type,
+as used in the DSO interface for a PMDA, namely:
+.PP
+.nf
+.ft CW
+/*
+ * Interface Definitions for PMDA Methods
+ */
+typedef struct {
+    int domain;         /* set/return performance metrics domain id here */
+    struct {
+        unsigned int    pmda_interface: 8; /* PMDA DSO interface version */
+        unsigned int    pmapi_version : 8; /* PMAPI version */
+        unsigned int    flags : 16;        /* optional feature flags */
+    } comm;             /* set/return communication and version info */
+    int status;         /* return initialization status here */
+
+    union {
+        struct {                              /* PMDA_INTERFACE_2 or _3 */
+            pmdaExt *ext;
+            int (*profile)(__pmProfile *, pmdaExt *);
+            int (*fetch)(int, pmID *, pmResult **, pmdaExt *);
+            int (*desc)(pmID, pmDesc *, pmdaExt *);
+            int (*instance)(pmInDom, int, char *, __pmInResult **, pmdaExt *);
+            int (*text)(int, int, char **, pmdaExt *);
+            int (*store)(pmResult *, pmdaExt *);
+        } two, three;
+
+        struct {                              /* PMDA_INTERFACE_4 or _5 */
+            pmdaExt *ext;
+            int     (*profile)(__pmProfile *, pmdaExt *);
+            int     (*fetch)(int, pmID *, pmResult **, pmdaExt *);
+            int     (*desc)(pmID, pmDesc *, pmdaExt *);
+            int     (*instance)(pmInDom, int, char *, __pmInResult **, pmdaExt *);
+            int     (*text)(int, int, char **, pmdaExt *);
+            int     (*store)(pmResult *, pmdaExt *);
+            int     (*pmid)(char *, pmID *, pmdaExt *);
+            int     (*name)(pmID, char ***, pmdaExt *);
+            int     (*children)(char *, int, char ***, int **, pmdaExt *);
+        } four, five;
+
+        struct {                              /* PMDA_INTERFACE_6 */
+            pmdaExt *ext;
+            int     (*profile)(__pmProfile *, pmdaExt *);
+            int     (*fetch)(int, pmID *, pmResult **, pmdaExt *);
+            int     (*desc)(pmID, pmDesc *, pmdaExt *);
+            int     (*instance)(pmInDom, int, char *, __pmInResult **, pmdaExt *);
+            int     (*text)(int, int, char **, pmdaExt *);
+            int     (*store)(pmResult *, pmdaExt *);
+            int     (*pmid)(char *, pmID *, pmdaExt *);
+            int     (*name)(pmID, char ***, pmdaExt *);
+            int     (*children)(char *, int, char ***, int **, pmdaExt *);
+            int     (*attribute)(int, int, const char *, int, pmdaExt *);
+        } six;
+    } version;
+
+} pmdaInterface;
+.fi
+.PP
+This structure has been extended to incorporate the multiple interface versions
+that have evolved over time.
+For
+.BR pmdaMain,
+.I dispatch->domain
+and
+.I dispatch->status
+are ignored.  The 
+.I comm.pmda_interface
+field is used to determine the interface used by the PMDA.  Setting this field
+to
+.B PMDA_INTERFACE_2
+or
+.B PMDA_INTERFACE_3
+will force 
+.B pmdaMain
+to use the callbacks in the
+.I version.two
+or
+.I version.three
+structure.
+A setting of
+.B PMDA_INTERFACE_4
+or
+.B PMDA_INTERFACE_5
+will force 
+.B pmdaMain
+to use the callbacks in the
+.I version.four
+or
+.I version.five
+structure, and similarly a
+.B PMDA_INTERFACE_6
+setting forces
+.B pmdaMain
+to use the callbacks in the
+.I version.six
+structure.
+Any other value will result in an error and termination of
+.BR pmdaMain .
+.PP
+Note that the use of
+.B dispatch
+as the interface between the
+.BR pmcd (1)
+and the methods of the PMDA allows each PMDA to be implemented as
+though it were a DSO, with
+.B pmdaMain
+providing a convenient wrapper that may be used to convert from the
+DSO interface to the binary PDU (daemon PMDA) interface.
+.PP
+.B pmdaMain
+executes as a continuous loop, returning only when an end of file
+is encountered on the PDU input file descriptor.
+.SH CALLBACKS
+In addition to the individual PDU processing callbacks \-
+.BR pmdaProfile (3),
+.BR pmdaFetch (3),
+.BR pmdaDesc (3),
+.BR pmdaInstance (3),
+.BR pmdaText (3),
+.BR pmdaStore (3),
+.BR pmdaPMID (3),
+.BR pmdaName (3),
+.BR pmdaChildren (3),
+and
+.BR pmdaAttribute (3)
+there are other callbacks that can affect or inform all PDU
+processing within a PMDA, namely
+.IR check ,
+.I done
+and
+.IR end .
+These callbacks should be set with 
+.BR pmdaSetCheckCallBack ,
+.B pmdaSetDoneCallBack
+and
+.BR pmdaSetEndContextCallBack .
+.PP
+If not null, 
+.I check 
+is called after each PDU is received (but before it was processed), and 
+.I done
+is called after each PDU is sent.  
+If
+.I check
+returns a value less than zero (typically PM_ERR_AGAIN),
+the PDU processing is skipped and in most cases the
+function value is returned as an error PDU to
+.BR pmcd (1)
+\- this may be used for
+PMDAs that require some sort of deferred connection or reconnect
+protocols for the underlying sources of performance metrics, e.g. a DBMS.
+The error indication from
+.I check
+is not passed back to
+.BR pmcd (1)
+in the cases where no acknowledgment is expected, e.g. for a PDU_PROFILE.
+.PP
+The
+.I end
+callback allows a PMDA to keep track of state for individual clients that
+are requesting it to perform actions (PDU processing).
+Using
+.B pmdaGetContext
+a PMDA can determine, at any point, an integer identifier that uniquely
+identifies the client tools at the remote end of PMCD (for local context
+modes, this identifier is always zero).
+This becomes very important for handling event metrics, where each
+event must be propogated once only to each interested client.
+It also underlies the mechanism whereby connection information is passed
+to the PMDA, such as the the credentials (user and group identifiers) for
+the client tool.
+.PP
+One final callback mechanism is provided for handling the
+.B pmResult
+built for a PDU_RESULT in response to a PDU_FETCH request.
+By default,
+.B pmdaMain
+will free the
+.B pmResult
+once the result has been sent to the
+.BR pmcd (1).
+For some PMDAs this is inappropriate, e.g. the
+.B pmResult
+is statically allocated, or contains a hybrid of pinned PDU buffer
+information and dynamically allocated information.
+.B pmdaSetResultCallback
+may be used to define an alternative
+.B callback
+from
+.BR pmdaMain .
+.SH DIAGNOSTICS
+These messages may be appended to the PMDA's log file:
+.TP 25
+.BI "PMDA interface version " interface " not supported"
+The
+.I interface
+version is not supported by 
+.BR pmdaMain .
+.TP
+.B Unrecognized pdu type
+The PMDA received a PDU from 
+.B pmcd
+that it does not recognize. This may indicate that the
+.B pmcd
+process is using a more advanced interface than
+.BR pmdaMain .
+.PP
+If the 
+.BR PMAPI (3)
+debug control variable
+.RB ( pmdebug )
+has the DBG_TRACE_LIBPMDA flag set then each PDU that is received is reported
+in the PMDA's log file.
+.SH SEE ALSO
+.BR pmcd (1),
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaProfile (3),
+.BR pmdaFetch (3),
+.BR pmdaDesc (3),
+.BR pmdaInstance (3),
+.BR pmdaText (3),
+.BR pmdaStore (3),
+.BR pmdaPMID (3),
+.BR pmdaName (3),
+.BR pmdaChildren (3),
+and
+.BR pmdaAttribute (3).
diff --git a/man/man3/pmdaname.3 b/man/man3/pmdaname.3
new file mode 100644
index 0000000..2c81493
--- /dev/null
+++ b/man/man3/pmdaname.3
@@ -0,0 +1,89 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000-2004 Silicon Graphics, Inc.  All Rights Reserved.
+.\" Copyright (c) 2009 Ken McDonell.  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 PMDANAME 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaName\f1 \- translate a PMID to a set of dynamic performance metric names
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+int pmdaName(pmID \fIpmid\fP, char ***\fInameset\fP, pmdaExt *\fIpmda\fP);
+.sp
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Metrics Domain Agent (PMDA) API (see
+.BR PMDA (3)),
+.BR pmdaName
+is the generic callback for
+translating a
+.I pmid
+into one or more dynamic metric names (\c
+.IR nameset ).
+.PP
+Because implementing dynamic performance metrics requires specific
+PMDA support, and the facility is an optional component of a PMDA (most
+PMDAs do
+.B not
+support dynamic performance metrics),
+.B pmdaName
+is a skeleton implementation that returns
+.BR PM_ERR_NAME .
+.PP
+A PMDA that supports dynamic performance metrics will provide a private
+callback that replaces
+.B pmdaName
+(by assignment to
+.I version.four.name
+of the
+.I pmdaInterface
+structure)
+and implements the translation from a
+.I pmid
+to a set of dynamic performance metric names returned via
+.IR nameset .
+The behaviour, return values and memory allocation rules for
+.I nameset
+are the same as for
+.BR pmNameAll (3).
+.SH DIAGNOSTICS
+.B 
+pmdaName
+returns
+.B PM_ERR_PMID
+if the name is not recognized or cannot be translated,
+otherwise the number of metric names found (most commonly 1).
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_PROTOCOL_4 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaDSO (3),
+.BR pmdaMain (3),
+.BR pmNameAll (3)
+and
+.BR pmNameID (3).
diff --git a/man/man3/pmdaopenlog.3 b/man/man3/pmdaopenlog.3
new file mode 100644
index 0000000..22762c6
--- /dev/null
+++ b/man/man3/pmdaopenlog.3
@@ -0,0 +1,78 @@
+'\"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 PMDAOPENLOG 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaOpenLog\f1 \- redirect stderr to a logfile
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+void pmdaOpenLog(pmdaInterface * \fIdispatch\fP);
+.sp
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmdaOpenLog
+redirects
+.I stderr
+to the logfile specified in the 
+.I dispatch
+structure, set by the previous call to
+.BR pmdaDaemon (3)
+or
+.BR pmdaGetOpt (3).
+The first line of the log file will detail the name of the calling process,
+the host the process is running on, and the current time.  In addition, the 
+log is appended with the exit time of the process by
+a routine registered with 
+.BR atexit (3C).
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_PROTOCOL_2 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.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).
+Values for these variables may be obtained programmatically
+using the
+.IR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR pmcd (1),
+.BR atexit (2),
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3)
+and
+.BR pmdaGetOpt (3).
diff --git a/man/man3/pmdapmid.3 b/man/man3/pmdapmid.3
new file mode 100644
index 0000000..295d939
--- /dev/null
+++ b/man/man3/pmdapmid.3
@@ -0,0 +1,81 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000-2004 Silicon Graphics, Inc.  All Rights Reserved.
+.\" Copyright (c) 2009 Ken McDonell.  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 PMDAPMID 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaPMID\f1 \- translate a dynamic performance metric name into a PMID
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+int pmdaPMID(char *\fIname\fP, pmID *\fIpmid\fP, pmdaExt *\fIpmda\fP);
+.sp
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Metrics Domain Agent (PMDA) API (see
+.BR PMDA (3)),
+.BR pmdaPMID
+is the generic callback for translating a dynamic metric
+.I name
+into a PMID (\c
+.IR pmid ).
+.PP
+Because implementing dynamic performance metrics requires specific
+PMDA support, and the facility is an optional component of a PMDA (most
+PMDAs do
+.B not
+support dynamic performance metrics),
+.B pmdaPMID
+is a skeleton implementation that returns
+.BR PM_ERR_NAME .
+.PP
+A PMDA that supports dynamic performance metrics will provide a private
+callback that replaces
+.B pmdaPMID
+(by assignment to
+.I version.four.pmid
+of the
+.I pmdaInterface
+structure)
+and implements the translation from a dynamic performance metric
+.I name
+into the associated
+.IR pmid .
+.SH DIAGNOSTICS
+.B pmdaPMID
+returns
+.B PM_ERR_NAME
+if the name is not recognized or cannot be translated, else returns 0.
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_PROTOCOL_4 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaDSO (3),
+.BR pmdaMain (3)
+and
+.BR pmLookupName (3).
diff --git a/man/man3/pmdaprofile.3 b/man/man3/pmdaprofile.3
new file mode 100644
index 0000000..0f64da3
--- /dev/null
+++ b/man/man3/pmdaprofile.3
@@ -0,0 +1,59 @@
+'\"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 PMDAPROFILE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaProfile\f1 \- update instance profile for PMDA in preparation for the next fetch from PMCD
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+int pmdaProfile(__pmProfile *\fIprof\fP, pmdaExt *\fIpmda\fP);
+.sp
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Metrics Domain Agent (PMDA) API (see
+.BR PMDA (3)),
+.B pmdaProfile
+is the default callback which handles the receipt of a 
+.B __pmProfile
+from 
+.BR pmcd (1).
+A profile describes the instances that 
+.B pmcd
+requires in the 
+.B pmResult
+structure returned by the next fetch.
+.B pmdaProfile
+simply stores the new profile.
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_PROTOCOL_2 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaDSO (3)
+and
+.BR pmdaFetch (3).
diff --git a/man/man3/pmdastore.3 b/man/man3/pmdastore.3
new file mode 100644
index 0000000..dcf8840
--- /dev/null
+++ b/man/man3/pmdastore.3
@@ -0,0 +1,62 @@
+'\"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 PMDASTORE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaStore\f1 \- store a value into a metric for a PMDA
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+int pmdaStore(pmResult *\fIresult\fP, pmdaExt *\fIpmda\fP);
+.sp
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Metrics Domain Agent (PMDA) API (see
+.BR PMDA (3)),
+.BR pmdaStore
+is the generic callback for storing a value into a metric.
+.B pmdaStore
+is usually a no-op as, by default, no metrics can be altered.  
+Also, the implementation of a store callback which does permit
+metrics to be altered by
+.BR pmstore (1)
+is very application dependent.
+.SH DIAGNOSTICS
+.B 
+pmdaStore
+returns
+.B PM_ERR_PERMISSION
+to indicate that no metrics may be modified.
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_PROTOCOL_2 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.SH SEE ALSO
+.BR pmstore (1),
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaDSO (3)
+and
+.BR pmStore (3).
diff --git a/man/man3/pmdatext.3 b/man/man3/pmdatext.3
new file mode 100644
index 0000000..ef21e6a
--- /dev/null
+++ b/man/man3/pmdatext.3
@@ -0,0 +1,120 @@
+'\"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 PMDATEXT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdaText\f1 \- extract metric help text for a PMDA
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+int pmdaText(int \fIident\fP, int \fItype\fP, char **\fIbuffer\fP, pmdaExt *\fIpmda\fP);
+.sp
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Metrics Domain Agent (PMDA) API (see
+.BR PMDA (3)),
+.B pmdaText
+uses the standard
+.BR PMDA (3)
+data structures to return the help text for metric
+.I ident
+in
+.IR buffer .
+The help text must be located in help text files
+created with
+.BR newhelp (1),
+and the associated files are automatically opened by
+.BR pmdaInit (3).
+.PP
+The path to the (basename of the) help text files can be set in the calls to
+.BR pmdaDSO (3)
+or
+.BR pmdaDaemon (3)
+and overridden by the 
+.B \-h
+command line option in
+.BR pmdaGetOpt (3).
+.PP
+The encoding of
+.I ident
+follows the internal scheme used below the routines
+.BR pmLookupText (3)
+and
+.BR pmLookupInDomText (3),
+namely
+.I ident
+encodes either a metric identifier or an instance domain
+identifier, according to the value
+of
+.IR type .
+.PP
+The
+.I type
+argument is a bit mask that encodes the interpretation of
+.I ident
+and the requested form of help text,
+as follows:
+either
+.B PM_TEXT_PMID
+if
+.I ident
+is a metric identifier, or
+.B PM_TEXT_INDOM
+if
+.I ident
+is an instance domain identifier, plus
+either
+.B PM_TEXT_ONELINE
+for the one line help text or
+.B PM_TEXT_HELP
+for the full help text.
+.PP
+The
+.I buffer
+is managed internally (usually it is cached),
+and it should
+.B not
+be released or freed by the caller of
+.BR pmdaText .
+.SH DIAGNOSTICS
+If the requested help text
+could not be obtained, 
+.B pmdaText
+will return
+.BR PM_ERR_TEXT .
+.SH CAVEAT
+The PMDA must be using 
+.B PMDA_PROTOCOL_2 
+or later, as specified in the call to 
+.BR pmdaDSO (3)
+or 
+.BR pmdaDaemon (3).
+.SH SEE ALSO
+.BR newhelp (1),
+.BR malloc (3),
+.BR PMAPI (3),
+.BR PMDA (3),
+.BR pmdaDaemon (3),
+.BR pmdaDSO (3),
+.BR pmdaInit (3),
+.BR pmLookupInDomText (3)
+and
+.BR pmLookupText (3).
diff --git a/man/man3/pmdatrace.3 b/man/man3/pmdatrace.3
new file mode 100644
index 0000000..a9c1569
--- /dev/null
+++ b/man/man3/pmdatrace.3
@@ -0,0 +1,341 @@
+'\"! 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 PMDATRACE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmtracebegin\f1,
+\f3pmtraceend\f1,
+\f3pmtraceabort\f1,
+\f3pmtracepoint\f1,
+\f3pmtraceobs\f1,
+\f3pmtracecounter\f1,
+\f3pmtracestate\f1,
+\f3pmtraceerrstr\f1 \- application-level performance instrumentation services
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/trace.h>
+.sp
+.nf
+int pmtracebegin(const char *\fItag\fP);
+int pmtraceend(const char *\fItag\fP);
+int pmtraceabort(const char *\fItag\fP);
+int pmtracepoint(const char *\fItag\fP);
+int pmtraceobs(const char *\fItag\fP, double \fIvalue\fP);
+int pmtracecounter(const char *\fItag\fP, double \fIvalue\fP);
+char *pmtraceerrstr(int \fIcode\fP);
+int pmtracestate(int \fIflags\fP);
+.fi
+.sp
+cc ... \-lpcp_trace
+.ft 1
+.SH "FORTRAN SYNOPSIS"
+.ft 3
+.nf
+character*(*) \fItag\fP
+integer \fIcode\fP
+integer \fIflags\fP
+integer \fIstate\fP
+character*(*) \fIestr\fP
+real*8 \fIvalue\fP
+.fi
+.sp
+.nf
+\fIcode\fP = pmtracebegin(\fItag\fP)
+\fIcode\fP = pmtraceend(\fItag\fP)
+\fIcode\fP = pmtraceabort(\fItag\fP)
+\fIcode\fP = pmtracepoint(\fItag\fP)
+\fIcode\fP = pmtraceobs(\fItag\fP, \fIvalue\fP)
+\fIcode\fP = pmtracecounter(\fItag\fP, \fIvalue\fP)
+pmtraceerrstr(\fIcode\fP, \fIestr\fP)
+\fIstate\fP = pmtracestate(\fIflags\fP)
+.fi
+.sp
+.nf
+f77 ... \-lpcp_trace  \f1or\f3  f90 ... \-lpcp_trace
+.fi
+.ft 1
+.SH "JAVA SYNOPSIS"
+.ft 3
+.nf
+.sp
+import sgi.pcp.trace;
+.sp
+.nf
+int trace.pmtracebegin(String \fItag\fP);
+int trace.pmtraceend(String \fItag\fP);
+int trace.pmtraceabort(String \fItag\fP);
+int trace.pmtracepoint(String \fItag\fP);
+int trace.pmtraceobs(String \fItag\fP, double \fIvalue\fP);
+int trace.pmtracecounter(String \fItag\fP, double \fIvalue\fP);
+String trace.pmtraceerrstr(int \fIcode\fP);
+int trace.pmtracestate(int \fIflags\fP);
+.fi
+.sp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+The
+.I pcp_trace
+library functions provide a mechanism for identifying sections of a program
+as transactions or events for use by the trace Performance Metrics Domain Agent
+(refer to
+.BR pmdatrace (1)
+and
+.BR PMDA (3)).
+.PP
+The monitoring of transactions using the Performance Co-Pilot (PCP)
+infrastructure is initiated through a call to 
+.BR pmtracebegin .
+Time will be recorded from the end of each
+.B pmtracebegin
+call to the start of the following call to
+.BR pmtraceend ,
+where the same \f2tag\f1 identifier is used in both calls.
+Following from this, no visible recording will occur until at least one call to 
+.B pmtraceend
+is made referencing a \f2tag\f1 previously used in a call to
+.BR pmtracebegin .
+.PP
+A transaction which is currently in progress can be cancelled by calling
+.BR pmtraceabort .
+No transaction data gathered for that particular transaction will be exported,
+although data from previous and subsequent successful transactions with that
+.I tag
+name are still exported.  This is most useful when an error condition
+arises during transaction processing and the transaction does not run to
+completion.
+.PP
+The \f2tag\f1 argument to 
+.BR pmtracebegin ,
+.B pmtraceend
+and
+.B pmtraceabort
+is used to uniquely identify each transaction within the
+.I pcp_trace
+library and later by the trace PMDA as the instance domain identifiers for the
+transaction performance metrics which it exports.
+These routines are most useful when used around blocks of code which are
+likely to be executed a number of times over some relatively long time
+period (in a daemon process, for example).
+.PP
+.B pmtracebegin
+has two distinct roles \- firstly as the initiator of a new transaction,
+and secondly as a mechanism for setting a new start time.
+Similarly,
+.B pmtraceend
+is used to register a new \f2tag\f1 and its initial state with the trace
+PMDA, or alternatively to update the statistics which the PMDA currently
+associates with the given \f2tag\f1.
+.PP
+A second form of program instrumentation can be obtained from
+.BR pmtracepoint .
+This is a simpler form of monitoring as it exports only the number of times
+that a particular point in a program has been passed.  This differs to the
+transaction monitoring offered by
+.B pmtracebegin
+and
+.BR pmtraceend ,
+which exports a running count of successful transaction completions as well as
+statistics on the time interval between the start and end points of each
+transaction.
+This function is most useful when start and end points are not well defined.
+Examples of this would be when the code branches in such a way that a transaction
+cannot be clearly identified, or when processing does not follow a transactional
+model, or the desired instrumentation is akin to event rates rather than event
+service times.
+.PP
+The
+.BR pmtraceobs
+and
+.BR pmtracecounter
+functions have similar semantics to
+.BR pmtracepoint ,
+but also allow an arbitrary numeric \f2value\f1 to be passed to the trace
+PMDA.
+The most recent \f2value\f1 for each \f2tag\f1 is then immediately available
+from the PMDA.  The only difference between
+.BR pmtraceobs
+and
+.BR pmtracecounter
+is that the value exported via
+.BR pmtracecounter
+is assumed to be a monotonically increasing counter value (e.g. the number
+of bytes read from a socket), whereas the value exported via
+.BR pmtraceobs
+can be any value at all.
+.PP
+.B pmtracestate
+allows the application to set state \f2flags\f1 which are honoured by
+subsequent calls to the \f2pcp_trace\f1 library routines.
+There are currently two types of flag \- debugging flags and the asynchronous
+protocol flag.  A single call may specify a number of \f2flags\f1 together,
+combined using a (bitwise) logical OR operation, and overrides the previous
+state setting.
+.PP
+The debugging flags to
+.B pmtracestate
+cause \f2pcp_trace\f1 to print diagnostic messages
+on the standard output stream at important processing points.
+The default protocol used between the trace PMDA and individual \f2pcp_trace\f1
+client applications is a synchronous protocol, which allows for dropped
+connections to be reestablished at a later stage should this become possible.
+An asynchronous protocol is also available which does not provide the
+reconnection capability, but which does away with much of the overhead
+inherent in synchronous communication.
+This behaviour can be toggled using the
+.B pmtracestate
+call, but must be called before other calls to the library.  This
+differs to the debugging state behaviour, which can be altered at any time.
+.B pmtracestate
+returns the previous state (setting prior to being called).
+.PP
+The following table describes each of the
+.B pmtracestate
+\f2flags\f1 - examples of the use of these flags in each supported language are
+given in the demo applications (refer to the ``FILES'' section below).
+.TS
+box,center;
+cf(R) | cf(R)
+lf(CW) | lf(R).
+State Flags	Semantics
+_
+0  NONE	Synchronous PDUs and no diagnostics (default)
+1  API	Shows processing just below the API (debug)
+2  COMMS	Shows network-related activity (debug)
+4  PDU	Shows app<->PMDA IPC traffic (debug)
+8  PDUBUF	Shows internal IPC buffer management (debug)
+16 NOAGENT	No PMDA communications at all (debug)
+32 ASYNC	Use the asynchronous PDU protocol (control)
+.TE
+.PP
+Should any of the
+.I pcp_trace
+library functions return a negative value,
+an error has occurred.  This can be diagnosed further using the
+.B pmtraceerrstr
+routine, which takes the negative return value as its \f2code\f1 argument,
+and in the C-callable interface returns a pointer to the associated error
+message.
+This points into a static error table, and should therefore not be passed to
+.BR free (3).
+The Fortran-callable interface has a slightly different syntax, requiring the
+destination character array to be passed in as the second argument.
+The Java-callable interface returns a UTF-8 string, created using the JNI
+(Java Native Interface) routine
+.BR NewStringUTF .
+.SH ENVIRONMENT
+The
+.I pcp_trace
+routines communicate with the trace PMDA via a socket connection, which by
+default uses TCP/IP port number 4323.  This can be over-ridden by setting
+\f3PCP_TRACE_PORT\f1 to a different port number when the application is
+started.  The host where the trace PMDA is running is by default the
+localhost, but this can be changed using \f3PCP_TRACE_HOST\f1.
+When attempting to connect to a remote trace PMDA, after some specified time
+interval has elapsed, the connection attempt will be aborted and an error
+status will be returned.  The default timeout interval is 3 seconds, and this
+can be modified by setting \f3PCP_TRACE_TIMEOUT\f1 in the environment to a
+real number of seconds for the desired timeout.  This is most useful in cases
+where the remote host is at the end of a slow network, requiring longer
+latencies to establish the connection correctly.
+.SH NOTES
+The \f2pcp_trace\f1 Java class interface has been developed and verified using
+version 1.1 of the Java Native Interface (JNI) specification.
+.SH FILES
+.TP 10
+.B $PCP_DEMOS_DIR/trace/*.c
+Sample C programs and source for
+.BR pmtrace (1).
+Use
+.BR make (1)
+to build these programs.
+.TP
+.B $PCP_DEMOS_DIR/trace/fapp1.f
+Sample Fortran program.
+Call `make fortran77' or `make fortran90' to build this program.
+.TP
+.B $PCP_DEMOS_DIR/trace/japp1.java
+Sample Java program.
+`make java' builds the java class file.
+.TP
+.B /usr/java/classes/sgi/pcp/trace.java
+Java trace class definition.
+.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).
+Values for these variables may be obtained programmatically
+using the
+.IR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.B file:$PCP_DOC_DIR/Tutorial/trace.html,
+.B pcp.man.tutorial,
+Provided the,
+.BR make (1),
+.BR pmcd (1),
+.BR pmdatrace (1),
+.BR pmprobe (1),
+.BR pmtrace (1),
+Relevant information is also available from the on-line PCP Tutorial,
+subsystem from the PCP images has been installed, access the URL
+and
+from your web browser.
+.SH DIAGNOSTICS
+A negative return value from a \f2pcp_trace\f1 function indicates that an
+error has occurred \- if this is the case, the return value can be passed
+to 
+.B pmtraceerrstr
+to obtain the associated error message.
+.PP
+Success is indicated by a return value of zero.
+.PP
+.B pmtracestate
+also returns an integer representing the state \f2flags\f1 which were set
+prior to the call.
+.SH CAVEAT
+.P
+Applications that use
+.BR gethostbyname (3N)
+should exercise caution because the static fields in
+.I "struct hostent"
+may not be preserved across some
+.I pcp_trace
+calls.
+In particular,
+.BR pmtracebegin ,
+.BR pmtraceend ,
+.BR pmtracepoint ,
+.BR pmtracecounter ,
+and
+.B pmtraceobs
+may all call
+.BR gethostbyname (3N)
+internally.
diff --git a/man/man3/pmdelprofile.3 b/man/man3/pmdelprofile.3
new file mode 100644
index 0000000..09cd0d2
--- /dev/null
+++ b/man/man3/pmdelprofile.3
@@ -0,0 +1,110 @@
+'\"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 PMDELPROFILE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmDelProfile\f1 \- delete instance(s) from the current PMAPI instance profile
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmDelProfile(pmInDom \fIindom\fP, int \fInuminst\fP, int *\fIinstlist\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+The set of instances for performance metrics returned from a
+.BR pmFetch (3)
+call may be filtered or restricted using an instance profile.
+There is one instance profile for each context the application
+creates at the Performance Metrics Application Programming Interface (PMAPI),
+and each instance profile may include instances from one or more
+instance domains (see
+.BR pmLookupDesc (3)).
+.PP
+.B pmDelProfile
+may be used to
+delete instance specifications from the instance profile of the current
+PMAPI context.
+.PP
+In the simplest variant, the list of instances identified by the
+.I instlist
+argument for the
+.I indom
+instance domain are removed from the instance
+profile.
+The list of instance identifiers contains
+.I numinst
+values.
+.PP
+The
+.I indom
+value would normally be extracted from a call to
+.BR pmLookupDesc (3)
+for a particular performance metric, and the instances in
+.I instlist
+would typically be determined by calls to
+.BR pmGetInDom (3)
+or
+.BR pmLookupInDom (3).
+.PP
+If
+.I indom
+equals
+.B PM_INDOM_NULL
+or
+.I numinst
+is zero,
+then all instance domains are selected for deletion.  If
+.I instlist
+is
+.CW "NULL" ,
+then all instances in the selected domain(s) are removed
+from the profile.
+.PP
+To disable all available instances in all domains, use
+.CW "pmDelProfile(PM_INDOM_NULL, 0, NULL)" .
+This is the only situation in which
+.I indom
+may be
+.BR PM_INDOM_NULL .
+.SH SEE ALSO
+.BR pmAddProfile (3),
+.BR PMAPI (3),
+.BR pmFetch (3),
+.BR pmGetInDom (3),
+.BR pmLookupDesc (3),
+.BR pmLookupInDom (3),
+.BR pmNewContext (3),
+.BR pmUseContext (3)
+and
+.BR pmWhichContext (3).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_PROFILESPEC\f1
+.I indom
+was
+.B PM_INDOM_NULL
+and
+.I instlist
+was not empty
+.SH CAVEAT
+It is possible to delete non-existent instance domains and non-existent
+instances from an instance profile.  None of the routines that use the instance
+profile will ever issue an error if you do this.  The cost of checking, when
+checking is possible, outweighs any benefits.
diff --git a/man/man3/pmderivederrstr.3 b/man/man3/pmderivederrstr.3
new file mode 100644
index 0000000..e8c2789
--- /dev/null
+++ b/man/man3/pmderivederrstr.3
@@ -0,0 +1,38 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2009 Ken McDonell.  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 PMDERIVEDERRSTR 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmDerivedErrStr\f1 \- return error message from failure to parse derived metric definition
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+char *pmDerivedErrStr(void);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.PP
+When
+.BR pmRegisterDerived (3)
+is called to add a new derived metric definition and an error occurs,
+.B pmDerivedErrStr
+may be called to return the associated error message.
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR PMAPI (3)
+and
+.BR pmRegisterDerived (3).
diff --git a/man/man3/pmdestroycontext.3 b/man/man3/pmdestroycontext.3
new file mode 100644
index 0000000..72d41ea
--- /dev/null
+++ b/man/man3/pmdestroycontext.3
@@ -0,0 +1,79 @@
+'\"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 PMDESTROYCONTEXT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmDestroyContext\f1 \- destroy a PMAPI context
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmDestroyContext(int \fIhandle\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+An application using the
+Performance Metrics Application Programming Interface (PMAPI)
+may manipulate several concurrent contexts,
+each associated with a source of performance metrics, e.g. \c
+.BR pmcd (1)
+on some host, or an archive log of performance metrics as created by
+.BR pmlogger (1).
+.PP
+.B pmDestroyContext
+destroys the PMAPI context identified by
+.IR handle .
+Typically this would imply some termination of a connection
+to a PMCD or closing an archive log file, and orderly clean-up.
+.PP
+The context
+must have been previously created using
+.BR pmNewContext (3)
+or
+.BR pmDupContext (3).
+.PP
+On success,
+.B pmDestroyContext
+returns zero.
+If
+.I handle
+was the current
+PMAPI context, then the current context becomes undefined.
+This means the application must explicitly re-establish a valid
+PMAPI context with
+.BR pmUseContext (3),
+or create a new context with
+.BR pmNewContext (3)
+or
+.BR pmDupContext (3),
+before the next PMAPI operation that requires a PMAPI context.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmDupContext (3),
+.BR pmNewContext (3),
+.BR pmUseContext (3)
+and
+.BR pmWhichContext (3).
+.SH DIAGNOSTICS
+.P
+.B PM_ERR_NOCONTEXT
+.IP
+.I handle
+does not identify a valid PMAPI context
diff --git a/man/man3/pmdiscoverservices.3 b/man/man3/pmdiscoverservices.3
new file mode 100644
index 0000000..cfe7a77
--- /dev/null
+++ b/man/man3/pmdiscoverservices.3
@@ -0,0 +1,154 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2014 Red Hat.
+.\" 
+.\" 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 PMDISCOVERSERVICES 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmDiscoverServices\f1 \- discover PCP services on the network
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmDiscoverServices(const char *\fIservice\fP, const char *\fImechanism\fP, const char *\fIglobalOptions\fP, char ***\fIurls\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Given a PCP service name, as identified by
+.IR service ,
+and using the type of discovery optionally specified in
+.IR mechanism ,
+.B pmDiscoverServices
+returns, via
+.IR urls ,
+a list of URLs representing the services discovered on the network.
+.PP 
+.I service
+specifies the PCP service to be discovered. Currently supported services are
+.B PM_SERVER_SERVICE_SPEC,
+.B PM_PROXY_SERVICE_SPEC
+and
+.B PM_WEBD_SERVICE_SPEC,
+which search for
+.BR pmcd (1),
+.BR pmproxy (1),
+and
+.BR pmwebd (1),
+servers respectively.
+.PP 
+.IR mechanism
+specifies the style of discovery to be used.
+.PP
+The currently supported mechanisms are:
+.TP
+.B avahi
+This searches for services which are broadcasting using mDNS via
+.BR avahi-daemon (8).
+An optional suffix \fB",timeout=NNNN"\fP may be added
+to specify the discovery timeout, in floating-point multiples of one
+second.  The default timeout is 0.5 seconds, which may be overridden
+by the \fBAVAHI_DISCOVERY_TIMEOUT\fP environment variable, also
+specified in floating-point multiples of one second.
+.TP
+.B probe=<net-address>/<mask-bits>
+Actively probes the given subnet for the requested PCP service(s).
+<net-address> is an inet or ipv6
+network address and <mask-bits> is the number of bits used to define the
+subnet. For example, 192.168.1.0/24 defines an 8 bit subnet consisting of the
+addresses 192.168.1.0 through 192.168.1.255.
+An optional suffix \fB",maxThreads=N"\fP may be added to limit the number of
+threads used while probing. The default is no fixed limit, which is to say that
+the process' rlimits for the number of threads and open file descriptors
+will be respected.
+.PP
+.IR mechanism
+may also be NULL, which means to use all available discovery mechanisms.
+.PP 
+.I globalOptions
+is a string containing options to be applied to the entire
+discovery process. Currently, the only supported option is \fB"resolve"\fP.
+Normally the
+results are reported as a list of urls containing the network addresses
+of the discovered servers. The \fB"resolve"\fP option requests
+that an attempt be made to resolve these addresses. If successful, the host
+name will be reported instead. If unsuccessful, then the address will be
+reported.
+.PP 
+.B pmDiscoverServices
+will return the number of services discovered, else a value
+less than zero for an error.
+The value zero indicates that no services were discovered.
+.PP
+The resulting list of pointers,
+.IR urls ,
+.B and
+the values
+(the URLs) that the pointers reference will have been
+allocated by
+.B pmDiscoverServices
+with a single call to
+.BR malloc (3C),
+and it is the
+responsibility of the
+.B pmDiscoverServices
+caller to
+.BR free (\c
+.IR urls )
+to release the space
+when it is no longer required.
+.PP
+When an error occurs, or no services are discovered,
+.I urls
+is undefined (no space will have been
+allocated, and so calling
+.BR free (3C)
+is a singularly bad idea).
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmcd (1),
+.BR pmproxy (1),
+.BR pmwebd (1),
+.BR pmfind (1),
+.BR pmGetConfig (3),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR avahi-daemon (8).
+.SH DIAGNOSTICS
+.IP \f3EOPNOTSUPP\f1
+The specified \fImechanism\fP is not supported.
diff --git a/man/man3/pmdupcontext.3 b/man/man3/pmdupcontext.3
new file mode 100644
index 0000000..e106aa4
--- /dev/null
+++ b/man/man3/pmdupcontext.3
@@ -0,0 +1,54 @@
+'\"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 PMDUPCONTEXT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmDupContext\f1 \- duplicate a PMAPI context
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmDupContext(void);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+An application using the
+Performance Metrics Application Programming Interface (PMAPI)
+may manipulate several concurrent contexts,
+each associated with a source of performance metrics, e.g. \c
+.BR pmcd (1)
+on some host, or an archive log of performance metrics as created by
+.BR pmlogger (1).
+.PP
+Calling
+.B pmDupContext
+will
+replicate the current PMAPI context,
+returning a handle for the new context that may be used with subsequent
+calls to
+.BR pmUseContext (3).
+.PP
+Once created, the duplicated context and the original context have independent
+existence, and so their instance profiles and 
+collection time (relevant only for archive contexts)
+may be independently varied.
+.PP
+The newly replicated context becomes the current context.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmNewContext (3)
+and
+.BR pmUseContext (3).
diff --git a/man/man3/pmerrstr.3 b/man/man3/pmerrstr.3
new file mode 100644
index 0000000..3b26dc2
--- /dev/null
+++ b/man/man3/pmerrstr.3
@@ -0,0 +1,69 @@
+'\"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 PMERRSTR 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmErrStr\f1,
+\f3pmErrStr_r\f1 \- convert a PMAPI error code into a string
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+const char *pmErrStr(int \fIcode\fP);
+.br
+char *pmErrStr_r(int \fIcode\fP, char *\fIbuf\fP, int \fIbuflen\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+Translate an error code into a text string, suitable for generating a
+diagnostic message.
+The
+.B pmErrStr_r
+function does the same, but stores the result in a user-supplied buffer
+.I buf
+of length
+.IR buflen ,
+which should have room for at least
+.B PM_MAXERRMSGLEN
+bytes.
+.PP
+By convention, all error codes are negative.
+The small
+values are assumed to be negated versions of the Unix error codes as defined
+in
+.B <errno.h>
+and the strings returned are as per
+.BR strerror (3C).
+The larger, negative error codes are
+Performance Metrics Application Programming Interface (PMAPI)
+error conditions and
+.BR pmErrStr (3)
+returns an appropriate PMAPI error string, as determined by
+.IR code .
+.SH NOTES
+.B pmErrStr
+returns a pointer to a static buffer,
+so the returned value is only valid until the next call to
+.B pmErrStr
+and hence is not thread-safe.
+Multi-threaded applications should use
+.B pmErrStr_r
+instead.
+.SH SEE ALSO
+.BR pmerr (1),
+.BR PMAPI (3)
+and
+.BR perror (3C).
diff --git a/man/man3/pmeventflagsstr.3 b/man/man3/pmeventflagsstr.3
new file mode 100644
index 0000000..08b2077
--- /dev/null
+++ b/man/man3/pmeventflagsstr.3
@@ -0,0 +1,68 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 PMEVENTFLAGSSTR 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmEventFlagsStr\f1,
+\f3pmEventFlagsStr_r\f1 \- convert an event record flags value into a string
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+const char *pmEventFlagsStr(int \fIflags\fP);
+.br
+char *pmEventFlagsStr_r(int \fIflags\fP, char *\fIbuf\fP, int \fIbuflen\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+For use in error and diagnostic messages,
+.B pmEventFlagsStr
+returns a `human readable' version of
+the value
+.IR flags ,
+assuming this to be the
+.B er_flags
+field of a
+.B pmEventRecord
+or
+.BR pmEventHighResRecord .
+The
+.B pmEventFlagsStr_r
+function does the same, but stores the result in a user-supplied buffer
+.I buf
+of length
+.IR buflen ,
+which should have room for at least 64 bytes.
+.PP
+The string value result from
+.B pmEventFlagsStr
+is held in a single static buffer, so the returned value is
+only valid until the next call to
+.BR pmEventFlagsStr .
+.SH NOTES
+.B pmEventFlagsStr
+returns a pointer to a static buffer and hence is not thread-safe.
+Multi-threaded applications should use
+.B pmEventFlagsStr_r
+instead.
+.SH SEE ALSO
+.BR PMAPI (3)
+and
+.BR pmdaEventAddRecord (3).
diff --git a/man/man3/pmextractvalue.3 b/man/man3/pmextractvalue.3
new file mode 100644
index 0000000..4f7266c
--- /dev/null
+++ b/man/man3/pmextractvalue.3
@@ -0,0 +1,255 @@
+'\"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 PMEXTRACTVALUE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmExtractValue\f1 \- extract a performance metric value from a pmResult structure
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmExtractValue(int \fIvalfmt\fP, const pmValue *\fIival\fP, int\ \fIitype\fP, pmAtomValue\ *\fIoval\fP, int\ \fIotype\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+The
+.CW pmValue
+structure is embedded within the
+.CW pmResult
+structure that is used to return one or more performance metrics;
+see
+.BR pmFetch (3).
+.PP
+All performance metric values may be encoded in a
+.CW pmAtomValue
+union, defined as follows;
+.PP
+.ft CW
+.nf
+.in +0.5i
+typedef union {
+    __int32_t    l;     /* 32-bit signed */
+    __uint32_t   ul;    /* 32-bit unsigned */
+    __int64_t    ll;    /* 64-bit signed */
+    __uint64_t   ull;   /* 64-bit unsigned */
+    float        f;     /* 32-bit floating point */
+    double       d;     /* 64-bit floating point */
+    char         *cp;   /* char ptr */
+    pmValueBlock *vbp;  /* pmValueBlock ptr */
+} pmAtomValue;
+.in
+.fi
+.ft 1
+.PP
+The routine
+.B pmExtractValue
+provides a convenient mechanism for extracting values from the 
+.CW pmValue
+part of a
+.CW pmResult
+structure, optionally converting the data type, and making the result 
+available to the application programmer.
+.PP
+.I itype 
+defines the data type of the input value held in
+.I ival
+according to the storage format defined by
+.I valfmt
+(see
+.BR pmFetch (3)).
+.I otype
+defines the data type of the result to be placed in
+.IR oval .
+.PP
+The value for
+.I itype
+is typically extracted from a
+.CW pmDesc
+structure, following a call to
+.BR pmLookupDesc (3)
+for a particular performance metric.
+.PP
+The
+.I otype
+value should be one of the defined
+.BR PM_TYPE_ ...
+values, that have a
+1:1 correspondence with the fields in the
+.CW pmAtomValue
+union.
+.PP
+Normally the
+.I valfmt
+parameter would be plucked from the same
+.CW pmResult
+structure that provides the
+.I ival
+parameter, and if
+.I valfmt
+specifies
+.BR PM_VAL_INSITU ,
+then the
+following types are not allowed, as these cannot be encoded in 32-bits;
+.BR __int64_t ,
+.BR __uint64_t , 
+.BR double ,
+.B char *
+and
+.B void *
+(the corresponding
+.I itype
+values are
+.BR PM_TYPE_64 ,
+.BR PM_TYPE_U64 ,
+.BR PM_TYPE_DOUBLE ,
+.BR PM_TYPE_STRING ,
+.B PM_TYPE_AGGREGATE
+and
+.B PM_TYPE_EVENT
+respectively).
+If
+.I valfmt
+specifies
+.BR PM_VAL_PTR ,
+then the value will be extracted from the associated
+.CW pmValueBlock
+structure, and the
+.BR __int32_t ,
+.B __uint32_t
+and
+.B float
+options (\c
+.I itype
+being 
+.BR PM_TYPE_32 ,
+.B PM_TYPE_U32
+and
+.B PM_TYPE_FLOAT
+respectively) are not allowed, as
+.B PM_VAL_INSITU
+is the appropriate encoding for these.
+.PP
+The following table defines the various possibilities for the type
+conversion -- the input type (\c
+.IR itype )
+is shown vertically, and the output type (\c
+.IR otype )
+is shown horizontally.
+Y means the conversion is always acceptable, N means the conversion can never be performed (the function returns 
+.BR PM_ERR_CONV ),
+P means the conversion may lose accuracy (but no error status is returned),
+T means the result may be subject to high-order truncation (in which case
+the function returns
+.BR PM_ERR_TRUNC )
+and S means the conversion may be impossible due to the
+sign of the input value (in which case the function returns
+.BR PM_ERR_SIGN ).
+If an error occurs, the value represented by
+.I oval
+will be zero (or
+.BR NULL ).
+.PP
+Note that although some of the conversions involving the types
+.B PM_TYPE_STRING
+and
+.B PM_TYPE_AGGREGATE
+are indeed possible, but are marked N \- the rationale
+is that
+.B pmExtractValue
+should not be attempting to duplicate functionality
+already available in the C library via
+.BR sscanf (3)
+and
+.BR sprintf (3).
+.PP
+No conversion involving the type
+.B PM_TYPE_EVENT
+is supported.
+.PP
+.ft CW
+.nf
+      | 32  |  U32  | 64  |  U64  | FLOAT | DBLE | STRNG | AGGR | EVENT
+======|=====|=======|=====|=======|=======|======|=======|======|=======
+32    |  Y  |   S   |  Y  |   S   |   P   |  P   |   N   |  N   |   N
+U32   |  T  |   Y   |  Y  |   Y   |   P   |  P   |   N   |  N   |   N
+64    |  T  |  T,S  |  Y  |   S   |   P   |  P   |   N   |  N   |   N
+U64   |  T  |   T   |  T  |   Y   |   P   |  P   |   N   |  N   |   N
+FLOAT | P,T | P,T,S | P,T | P,T,S |   Y   |  Y   |   N   |  N   |   N
+DBLE  | P,T | P,T,S | P,T | P,T,S |   P   |  Y   |   N   |  N   |   N
+STRNG |  N  |   N   |  N  |   N   |   N   |  N   |   Y   |  N   |   N
+AGGR  |  N  |   N   |  N  |   N   |   N   |  N   |   N   |  Y   |   N
+EVENT |  N  |   N   |  N  |   N   |   N   |  N   |   N   |  N   |   N
+.fi
+.ft 1
+.PP
+In the cases where multiple conversion errors could occur, the first
+encountered error will be notified, and the order of checking is not defined.
+.PP
+If the output conversion is to one of the pointer types, i.e. \c
+.I otype
+is
+.B PM_TYPE_STRING
+or
+.BR PM_TYPE_AGGREGATE ,
+then the value buffer will have been allocated by
+.BR pmExtractValue (3)
+using
+.BR malloc (3C),
+and it is the caller's responsibility to free the space when it is no longer
+required.
+.PP
+Although this function appears rather complex, it has been constructed to
+assist the development of performance tools that wish to convert values,
+whose type is only known via the
+.CW type
+field in a 
+.CW pmDesc
+structure, into a canonical type for local processing.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmAtomStr (3),
+.BR pmConvScale (3),
+.BR pmFetch (3),
+.BR pmLookupDesc (3),
+.BR pmPrintValue (3),
+.BR pmTypeStr (3),
+.BR pmUnitsStr (3)
+and
+.BR pmUnpackEventRecords (3).
+.SH DIAGNOSTICS
+.P
+.B PM_ERR_CONV
+.IP
+Impossible conversion, marked by N in above table
+.P
+.B PM_ERR_TRUNC
+.IP
+High-order truncation occurred
+.P
+.B PM_ERR_SIGN
+.IP
+Conversion of negative value to unsigned type attempted
diff --git a/man/man3/pmfetch.3 b/man/man3/pmfetch.3
new file mode 100644
index 0000000..893c59f
--- /dev/null
+++ b/man/man3/pmfetch.3
@@ -0,0 +1,376 @@
+'\"! 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 PMFETCH 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmFetch\f1 \- get performance metric values
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmFetch(int \fInumpmid\fP, pmID *\fIpmidlist\fP, pmResult **\fIresult\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\fR\\$2
+.el \fI\\$1\fR\\$2
+..
+.\" some useful acronyms ... always cite the full text at the first use
+.\" and use uppercase acronym thereafter
+.\" Performance Metrics Application Programming Interface (PMAPI)
+.\" Performance Metrics Name Space (PMNS)
+.\" Performance Metrics Collector Daemon (PMCD)
+.\" Performance Metric ID (PMID)
+Given a list of Performance Metric IDs (PMID)s,
+e.g. as constructed by
+.BR pmLookupName (3),
+via
+.I pmidlist
+and
+.IR numpmid ,
+fetch the values for these performance metrics.
+.PP
+The call to
+.B pmFetch
+is executed in the context of a source of metrics,
+instance profile and collection time,
+previously established by calls to
+the appropriate context and profile functions, namely some of
+.BR pmNewContext (3),
+.BR pmDupContext (3),
+.BR pmUseContext (3),
+.BR pmAddProfile (3),
+.BR pmDelProfile (3)
+and
+.BR pmSetMode (3).
+.PP
+The principal result from
+.B pmFetch
+is returned in the
+argument
+.I result
+as a tree, using the following component data structures;
+.PP
+.ft CW
+.nf
+.in +0.5i
+typedef struct {
+      unsigned int vtype : 8;        /* value type (same as pmDesc.type) */
+      unsigned int vlen : 24;        /* bytes for vtype/vlen + vbuf */
+      char         vbuf[1];          /* one or more values */
+} pmValueBlock;
+
+typedef struct {
+      int      inst;                 /* instance identifier */
+      union {
+            pmValueBlock *pval;      /* pointer to value-block */
+            int          lval;       /* integer value insitu */
+      } value;
+} pmValue;
+
+typedef struct {
+      pmID      pmid;                /* metric identifier */
+      int       numval;              /* number of values or error code */
+      int       valfmt;              /* value style, insitu or ptr */
+      pmValue   vlist[1];            /* set of instances/values */
+} pmValueSet;
+
+/* Result returned by pmFetch() */
+typedef struct {
+      struct timeval timestamp;      /* time stamped by collector */
+      int            numpmid;        /* number of PMIDs */
+      pmValueSet     *vset[1];       /* set of value sets */
+} pmResult;
+.in
+.fi
+.ft 1
+.PP
+To accommodate metrics with multiple value instances, the
+.CW numval
+field indicates how many values are returned for each requested PMID.
+The field
+.CW valfmt
+in the 
+.CW pmValueSet
+structure indicates if the values for this metric are stored
+.I insitu
+in the 
+.CW lval
+field, i.e. a 32-bit integer quantity (either int, unsigned int,
+long or unsigned long) or if the values are held in associated 
+.CW pmValueBlock
+structures.
+The
+.CW pmValueBlock
+structure is always used for floating point values (float or double)
+and also accommodates arbitrary sized binary data such as
+`string-valued' metrics and metrics with aggregated or complex data types.
+The maximum length of a
+.CW pmValueBlock
+buffer is
+.B PM_VAL_VLEN_MAX
+bytes.
+If the
+.CW pmValueBlock
+format is used, the
+.CW vtype
+field indicates the data type of the value.
+This field has the same interpretation as the
+.CW type
+field in the
+.B pmDesc
+structure,
+see
+.BR pmLookupDesc (3).
+.PP
+Note that the insitu value may be a signed or unsigned 32 bit integer,
+signed or unsigned 32 bit long value (on 32 bit platforms),
+In the special cases described below, it may also be a 32 bit floating
+point value.
+If the application needs to know the type of an insitu value,
+which is almost always the case, it is necessary to
+fetch the descriptor for the metric
+and interpret the
+.B type
+field, as described in detail in
+.BR pmLookupDesc (3).
+When the
+.CW pmResult
+is received from a PCP1.x
+.BR pmcd ,
+insitu values may also be 32 bit floating point values
+(of type
+.BR PM_TYPE_FLOAT ).
+In all cases, it is good practice to use
+.BR pmLookupDesc (3)
+to fetch the descriptor for the metric and interpret the
+.B type
+field therein.
+Note also that the
+.BR PMAPI (3)
+will automatically translate from the PCP2.0 format
+to the PCP1.x format when a PCP1.x client requests 32 bit floating point values
+from a PCP2.0
+.BR pmcd ,
+but the reverse translation does not occur (because the PCP2.0
+.B pmcd
+cannot automatically distinguish between arbitrary 32 bit floating point values
+and 32 bit integers).
+.PP
+If one value (i.e. associated with a particular instance)
+for a requested metric is `unavailable' (at the requested time),
+then there is no associated 
+.CW pmValue
+structure in the 
+.IR result .
+If there are no available values for a metric,
+then
+.CW numval
+will be zero and the associated 
+.CW pmValue[]
+instance will be empty (\c
+.CW valfmt
+is undefined in these circumstances,
+however 
+.CW pmid
+will be correctly set to the PMID of the metric with no values).
+.PP
+As an extension of this protocol,
+if the Performance Metrics Collection System (PMCS)
+is able to provide a reason why no values are available 
+for a particular metric,
+this is encoded as a standard error code in the corresponding 
+.CW numval .
+Since the error codes are all negative,
+values for a requested metric are `unavailable' if
+.CW numval
+is less than, or equal to, zero.
+A performance metric's value may be `unavailable'
+for any of the following reasons;
+.IP "+" 3n
+The metric is not supported in this version
+of the software for the associated Performance Metric Domain
+.IP "+"
+Collection is not currently activated
+in the software for the associated Performance Metric Domain
+.IP "+"
+The associated PMID is not known
+.IP "+"
+The current system configuration does not include
+the associated hardware component and/or the associated software module,
+e.g. a disk is not installed, or off-line, or Oracle is not installed
+.IP "+"
+The metric is one for which an instance profile is required,
+and none was provided (there are a small number of metrics in this category,
+typically ones with very large, and/or very 
+dynamic instance domains, and/or expensive metric instantiation methods).
+.PP
+In general, we may not be able to differentiate between the various cases,
+and if differentiation is not possible, 
+.CW numval
+will simply be zero.
+.PP
+The argument definition and the result specifications have been constructed
+to ensure that for each PMID in the requested 
+.I pmidlist
+there is exactly one 
+.CW pmValueSet
+in the 
+.IR result ,
+and further the PMIDs appear in exactly the same sequence in both
+.I pmidlist
+and 
+.IR result .
+This makes the number 
+and order of entries in 
+.I result
+completely deterministic,
+and greatly simplifies the application programming logic
+after the call to 
+.BR pmFetch .
+.PP
+The 
+.I result
+structure returned by 
+.B pmFetch
+is dynamically allocated using
+a combination of 
+.BR malloc (3C)
+calls
+and specialized allocation strategies,
+and should be released when no longer required by calling
+.BR pmFreeResult (3)
+\- under no circumstances should 
+.BR free (3C)
+be called directly to release this space.
+.PP
+As common error conditions are encoded
+in the 
+.I result
+data structure, we'd expect only cataclysmic events
+to cause an error value to be returned.
+One example would be if the metrics source context was a remote host,
+and that host or the PMCS on that host became unreachable.
+Otherwise the value returned by the 
+.B pmFetch
+function will be non-negative.
+.PP
+If the current context involves fetching metrics from a
+Performance Metrics Collector Daemon (PMCD), then the return value
+may be used to encode out-of-band changes in the state of the
+PMCD and the associated
+Performance Metrics Daemon Agents (PMDAs), as a bit-wise ``or'' of the
+following values:
+.sp 0.5v
+.IP \fBPMCD_RESTART_AGENT\fR 20n
+An attempt has been made to restart at least one failed PMDA.
+.IP \fBPMCD_ADD_AGENT\fR
+At least one PMDA has been started.
+.IP \fBPMCD_DROP_AGENT\fR
+PMCD has noticed the termination of at least one PMDA.
+.PP
+The default is to return zero to indicate
+no change in state, however
+the
+.CW pmResult
+returned by
+.B pmFetch
+has the same interpretation independent of the return value being
+zero or greater than zero.
+.SH SEE ALSO
+.BR pmcd (1),
+.BR pmAddProfile (3),
+.BR PMAPI (3),
+.BR pmDelProfile (3),
+.BR pmDupContext (3),
+.BR pmExtractValue (3),
+.BR pmFetchArchive (3),
+.BR pmFreeResult (3),
+.BR pmGetInDom (3),
+.BR pmLookupDesc (3),
+.BR pmLookupName (3),
+.BR pmNewContext (3),
+.BR pmSetMode (3),
+.BR pmUseContext (3)
+and
+.BR pmWhichContext (3).
+.PP
+Note that
+.B pmFetch
+is the most primitive method of fetching metric values from the PMCS.
+More user friendly interfaces to the PMCS are available or currently
+under development \- these higher level fetch methods insulate
+the user from the intricacies of context creation,
+setting up instance profiles, 
+.CW pmResult
+traversal, and splitting fetches into batches to minimize PDU traffic
+or according to other optimization criteria.
+.SH DIAGNOSTICS
+As mentioned above,
+.B pmFetch
+returns error codes
+.I insitu
+in the argument
+.IR result .
+If no result is returned,
+e.g. due to IPC failure using the current PMAPI context, or
+end of file on an archive log,
+then
+.B pmFetch
+will return a negative error code which may be examined using
+.BR pmErrStr (3).
+.IP \f3PM_ERR_EOL\f1
+When fetching records from an archive log,
+.B pmFetch
+returns this error code to indicate the end of the log has been
+passed (or the start of the log has been passed, if the direction
+of traversal is backwards in time).
+If the ``mode'' for the current PMAPI context (see
+.BR pmSetMode (3))
+is
+.B PM_MODE_INTERP
+then the time origin is advanced, even when this error code is
+returned.
+In this way applications that position the time outside the range
+defined by the records in the archive, and then commence to
+.B pmFetch
+will eventually see valid results once the time origin moves inside
+the temporal span of the archive.
+.SH ENVIRONMENT
+Many of the performance metrics exported from PCP agents have the
+semantics of
+.I counter
+meaning they are expected to be monotonically increasing.
+Under some circumstances, one value of these metrics may be smaller
+than the previously fetched value.
+This can happen when a counter of finite precision overflows, or
+when the PCP agent has been reset or restarted, or when the
+PCP agent is exporting values from some
+underlying instrumentation that is subject to some asynchronous
+discontinuity.
+.sp 0.5v
+The environment variable
+.B PCP_COUNTER_WRAP
+may be set to indicate that all such cases of a decreasing ``counter''
+should be treated
+as a counter overflow, and hence the values are assumed to have
+wrapped once in the interval between consecutive samples.
+This ``wrapping'' behavior was the default in earlier PCP versions, but
+by default has been disabled in PCP version 1.3 and later.
diff --git a/man/man3/pmfetcharchive.3 b/man/man3/pmfetcharchive.3
new file mode 100644
index 0000000..25c1c6a
--- /dev/null
+++ b/man/man3/pmfetcharchive.3
@@ -0,0 +1,83 @@
+'\"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 PMFETCHARCHIVE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmFetchArchive\f1 \- get performance metrics directly from an archive log
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmFetchArchive(pmResult **\fIresult\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmFetchArchive
+is a variant of 
+.BR pmFetch (3)
+that may only be used when the current
+Performance Metrics Application Programming Interface (PMAPI)
+context
+is associated with an archive log.
+.PP
+The
+.I result
+is instantiated with all of the metrics (and instances)
+from the next archive record,
+consequently there is no notion of a list of desired metrics,
+and the instance profile of the PMAPI context is ignored.
+.PP
+It is expected that 
+.B pmFetchArchive
+would be used to create utilities that scan archive logs,
+while the more common access to the archives would be via the 
+.BR pmFetch (3)
+interface.
+.PP
+To skip records within the archive log, use
+.BR pmSetMode (3)
+to change the collection time within the current
+PMAPI context, then call
+.BR pmFetchArchive.
+.PP
+Note that the
+.I result
+returned by
+.B pmFetchArchive
+is dynamically allocated, and
+must be released using
+.BR pmFreeResult (3),
+not
+.BR free (3C).
+See
+.BR pmFetch (3)
+and
+.BR pmFreeResult (3)
+for further details.
+.PP
+.B pmFetchArchive
+returns zero on success.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmFetch (3),
+.BR pmFreeResult (3),
+.BR pmNewContext (3),
+.BR pmSetMode (3)
+and
+.BR pmTrimNameSpace (3).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOTARCHIVE\f1
+the current PMAPI context is not associated with an archive log
diff --git a/man/man3/pmfreeeventresult.3 b/man/man3/pmfreeeventresult.3
new file mode 100644
index 0000000..6076122
--- /dev/null
+++ b/man/man3/pmfreeeventresult.3
@@ -0,0 +1,66 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2014 Red Hat.
+.\" Copyright (c) 2010 Ken McDonell.  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 PMFREEEVENTRESULT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmFreeEventResult\f1,
+\f3pmFreeHighResEventResult\f1 \- release storage allocated for unpacked event records
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+void pmFreeEventResult(pmResult **\fIrset\fP);
+.br
+void pmFreeHighResEventResult(pmHighResResult **\fIhrset\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+When processing event records, if
+.BR pmUnpackEventRecords (3)
+is used to unpack event records from a metric within a
+.I pmResult
+structure with a value of type
+.B PM_TYPE_EVENT
+then the structure returned from
+.BR pmUnpackEventRecords (3)
+is a NULL pointer terminated array of pointers to
+.I pmResult
+structures, one for each event record.
+.PP
+.B pmFreeEventResult
+is a convenience method that frees all of the
+.I pmResult
+structures and the array of pointers (\c
+.IR rset ).
+.PP
+Similarly,
+.B pmFreeHighResEventResult
+may be used to free the
+.I pmHighResResult
+structures and array returned from the
+.BR pmUnpackHighResEventRecords
+routine when using
+.BR PM_TYPE_HIGHRES_EVENT
+metrics.
+.SH SEE ALSO
+.BR PMAPI (3)
+and
+.BR pmUnpackEventRecords (3).
diff --git a/man/man3/pmfreeprofile.3 b/man/man3/pmfreeprofile.3
new file mode 100644
index 0000000..8cdf0eb
--- /dev/null
+++ b/man/man3/pmfreeprofile.3
@@ -0,0 +1,41 @@
+'\"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 PMFREEPROFILE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3__pmFreeProfile\f1 \- free a PMAPI instance profile
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+void __pmFreeProfile(__pmProfile *\fIprof\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B __pmFreeProfile
+frees the storage for the PMAPI instance profile
+.IR prof ,
+assuming the
+storage was allocated using
+.BR malloc (3C)
+according to the scheme used in
+.BR __pmDecodeProfile (3).
+.SH SEE ALSO
+.BR PMAPI (3)
+and
+.BR __pmDecodeProfile (3).
diff --git a/man/man3/pmfreeresult.3 b/man/man3/pmfreeresult.3
new file mode 100644
index 0000000..8c3d570
--- /dev/null
+++ b/man/man3/pmfreeresult.3
@@ -0,0 +1,61 @@
+'\"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 PMFREERESULT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmFreeResult\f1 \- release storage allocated for performance metrics values
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+void pmFreeResult(pmResult *\fIresult\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+The variable sized results returned by
+.BR pmFetch (3)
+are allocated below the
+Performance Metrics Application Programming Interface (PMAPI)
+using a combination of dynamic (i.e. \c
+.BR malloc (3))
+and specialized allocation strategies.
+.PP
+Applications should call
+.B pmFreeResult
+to release the storage previously allocated for
+.I result
+by
+.BR pmFetch (3),
+when the application no longer requires access to the
+.CW pmResult
+structure.
+.PP
+Under
+.B no
+circumstances should an application use
+.CW "free(result)"
+to release storage previously allocated for a
+.CW pmResult
+by
+.BR pmFetch (3).
+.SH SEE ALSO
+.BR PMAPI (3)
+and
+.BR pmFetch (3).
diff --git a/man/man3/pmgetarchiveend.3 b/man/man3/pmgetarchiveend.3
new file mode 100644
index 0000000..265a602
--- /dev/null
+++ b/man/man3/pmgetarchiveend.3
@@ -0,0 +1,99 @@
+'\"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 PMGETARCHIVEEND 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmGetArchiveEnd\f1 \- locate logical end of file for an archive log
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmGetArchiveEnd(struct timeval *\fItvp\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+Assuming the current PMAPI context
+is associated with an archive log,
+.B pmGetArchiveEnd
+will attempt to find the logical end of file (after
+the last complete record in the archive),
+and return the last recorded timestamp via
+.IR tvp .
+This timestamp may be passed to
+.BR pmSetMode (3)
+to reliably position the context at the last valid
+log record, e.g. in preparation for subsequent reading in
+reverse chronological order. 
+.PP
+For archive logs that are not concurrently being written, the
+physical end of file and the logical end of file are co-incident.
+However if an archive log is being written by
+.BR pmlogger (1)
+at the same time an application is trying to read the archive,
+the logical end of file may be before the physical end of file
+due to write buffering that is not aligned with the logical record
+boundaries.
+.PP
+.B pmGetArchiveEnd
+returns an error less than zero if the context is neither valid,
+nor associated with an archive, or the archive is seriously
+corrupted.
+Otherwise, the return value is 0 if there has been no change of
+state since the last call, or 1 if the logical end of file has
+advanced since the last call.
+.PP
+In the absence of an error, the result returned via
+.I tvp
+is well-defined.
+.PP
+.BR pmGetArchiveEnd
+preserves the positioning state of the log file prior to
+this function call. 
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmFetch (3),
+.BR pmFetchArchive (3),
+.BR pmGetArchiveLabel (3),
+.BR pmGetConfig (3),
+.BR pmSetMode (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOCONTEXT\f1
+the current PMAPI context
+is either invalid, or not associated with an archive log
+.IP \f3PM_ERR_LOGREC\f1
+the archive is sufficiently damaged, that not a single valid
+record can be found
diff --git a/man/man3/pmgetarchivelabel.3 b/man/man3/pmgetarchivelabel.3
new file mode 100644
index 0000000..3649fa6
--- /dev/null
+++ b/man/man3/pmgetarchivelabel.3
@@ -0,0 +1,123 @@
+'\"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 PMGETARCHIVELABEL 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmGetArchiveLabel\f1 \- fetch the label record from a performance metrics archive log
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmGetArchiveLabel(pmLogLabel *\fIlp\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Within the framework of the
+Performance Co-Pilot (PCP), archive logs of performance metrics values
+may be accumulated and saved using the program
+.BR pmlogger (1).
+.PP
+The routine
+.B pmGetArchiveLabel
+may be used to fetch the label record from an archive log that has already
+been opened using
+.BR pmNewContext (3),
+or
+.BR pmDupContext (3),
+and thereby associated with the current
+Performance Metrics Application Programming Interface (PMAPI)
+context.
+.PP
+The result returned via the pointer
+.I lp
+is a structure that must be pre-allocated by the caller
+and has the following format (defined in
+.BR pmapi.h ).
+.PP
+.in +0.2i
+.ft CW
+.nf
+/*
+ * Label Record at the start of every log file
+ */
+typedef struct {
+  int        ll_magic;    /* PM_LOG_MAGIC | log format version no. */
+  pid_t      ll_pid;      /* PID of logger */
+  struct timeval ll_start;/* start of this log */
+  char       ll_hostname[PM_LOG_MAXHOSTLEN]; /* name of collection host */
+  char       ll_tz[40];   /* $TZ at collection host */
+} pmLogLabel;
+.fi
+.ft 1
+.in
+.PP
+For an application, the most useful information from the archive label
+is likely to be in the fields
+.CW ll_start ,
+.CW ll_hostname
+or
+.CW ll_tz .
+.PP
+Note that the size of the
+.CW ll_hostname
+field is
+.CW PM_LOG_MAXHOSTLEN
+(64 bytes)
+which is less than
+.BR MAXHOSTNAMELEN
+(see
+.BR gethostbyname (3))
+on some platforms.
+These semantics are necessary to retain backwards compatibility with the
+PCP archive file format.
+.PP
+.B pmGetArchiveLabel
+returns zero for success.
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR pmlogger (1),
+.BR PMAPI (3),
+.BR pmDupContext (3),
+.BR pmGetConfig (3),
+.BR pmNewContext (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOCONTEXT\f1
+the current PMAPI context
+is either invalid, or not associated with an archive log
diff --git a/man/man3/pmgetchildren.3 b/man/man3/pmgetchildren.3
new file mode 100644
index 0000000..a2518e4
--- /dev/null
+++ b/man/man3/pmgetchildren.3
@@ -0,0 +1,130 @@
+'\"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 PMGETCHILDREN 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmGetChildren\f1 \- return the descendent nodes of a PMNS node
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmGetChildren(const char *\fIname\fP, char ***\fIoffspring\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Given a fully qualified pathname to a node in the current Performance
+Metrics Name Space (PMNS), as identified by
+.IR name ,
+.B pmGetChildren
+returns via
+.I offspring
+a list of the relative names of
+all of the immediate descendent nodes of
+.I name
+in the current PMNS.
+.PP
+As a
+special case, if
+.I name
+is an empty string (i.e.\f3""\f1), the immediate descendants of
+the root node in the PMNS will be returned.
+.PP 
+Normally,
+.B pmGetChildren
+will return the number of descendent names discovered, else a value
+less than zero for an error.
+The value zero indicates that
+.I name
+is a valid metric name, i.e. is associated with a leaf node in the PMNS.
+.PP
+The resulting list of pointers
+.I offspring
+.B and
+the values
+(the relative names) that the pointers reference will have been
+allocated by
+.B pmGetChildren
+with a single call to
+.BR malloc (3C),
+and it is the
+responsibility of the
+.B pmGetChildren
+caller to
+.BR free (\c
+.IR offspring )
+to release the space
+when it is no longer required.
+.PP
+When an error occurs, or
+.I name 
+is a leaf node (i.e. the result of
+.B pmGetChildren
+is less than one),
+.I offspring
+is undefined (no space will have been
+allocated, and so calling
+.BR free (3C)
+is a singularly bad idea).
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetChildrenStatus (3),
+.BR pmGetConfig (3),
+.BR pmLoadASCIINameSpace (3),
+.BR pmLoadNameSpace (3),
+.BR pmLookupName (3),
+.BR pmNameID (3),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR pmns (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOPMNS\f1
+Failed to access a PMNS for operation.
+Note that if the application hasn't a priori called pmLoadNameSpace(3)
+and wants to use the distributed PMNS, then a call to
+.B pmGetChildren
+must be made inside a current context.
+.IP \f3PM_ERR_NAME\f1
+The pathname
+.I name
+is not valid in the current PMNS
+.IP \f3PM_ERR_*\f1
+Other diagnostics are for protocol failures when
+accessing the distributed PMNS.
diff --git a/man/man3/pmgetchildrenstatus.3 b/man/man3/pmgetchildrenstatus.3
new file mode 100644
index 0000000..155d6d0
--- /dev/null
+++ b/man/man3/pmgetchildrenstatus.3
@@ -0,0 +1,152 @@
+'\"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 PMGETCHILDRENSTATUS 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmGetChildrenStatus\f1 \- return the descendent nodes of a PMNS node and their respective status
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmGetChildrenStatus(const char *\fIname\fP, char ***\fIoffspring\fP, int\ **\fIstatus\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Given a fully qualified pathname to a node in the current Performance
+Metrics Name Space (PMNS), as identified by
+.IR name ,
+.B pmGetChildrenStatus
+returns via
+.I offspring
+a list of the relative names of
+all of the immediate descendent nodes of
+.I name
+in the current PMNS.
+.PP
+As a
+special case, if
+.I name
+is an empty string (i.e.\f3""\f1), the immediate descendants of
+the root node in the PMNS will be returned.
+.PP
+If 
+.IR status 
+is not NULL, then 
+.B pmGetChildrenStatus
+will also return the status of each child via
+.IR status.
+The status will refer to either a leaf node (with value 
+.B PMNS_LEAF_STATUS
+) or a non-leaf node (with value
+.B PMNS_NONLEAF_STATUS
+).
+.PP 
+Normally,
+.B pmGetChildrenStatus
+will return the number of descendent names discovered, else a value
+less than zero for an error.
+The value zero indicates that
+.I name
+is a valid metric name, i.e. is associated with a leaf node in the PMNS.
+.PP
+The resulting list of pointers
+.I offspring
+.B and
+the values
+(the relative names) that the pointers reference will have been
+allocated by
+.B pmGetChildrenStatus
+with a single call to
+.BR malloc (3C),
+and it is the
+responsibility of the
+.B pmGetChildrenStatus
+caller to
+.BR free (\c
+.IR offspring )
+to release the space
+when it is no longer required.
+The same holds true for the 
+.I status
+array.
+.PP
+When an error occurs, or
+.I name 
+is a leaf node (i.e. the result of
+.B pmGetChildrenStatus
+is less than one), both
+.I offspring
+and
+.I status
+are undefined (no space will have been
+allocated, and so calling
+.BR free (3C)
+is a singularly bad idea).
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetChildren (3),
+.BR pmGetConfig (3),
+.BR pmLoadASCIINameSpace (3),
+.BR pmLoadNameSpace (3),
+.BR pmLookupName (3),
+.BR pmNameID (3),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR pmns (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOPMNS\f1
+Failed to access a PMNS for operation.
+Note that if the application hasn't a priori called pmLoadNameSpace(3)
+and wants to use the distributed PMNS, then a call to
+.B pmGetChildrenStatus
+must be made inside a current context.
+.IP \f3PM_ERR_NAME\f1
+The pathname
+.I name
+is not valid in the current PMNS
+.IP \f3PM_ERR_*\f1
+Other diagnostics are for protocol failures when
+accessing the distributed PMNS.
diff --git a/man/man3/pmgetconfig.3 b/man/man3/pmgetconfig.3
new file mode 100644
index 0000000..0fdbe10
--- /dev/null
+++ b/man/man3/pmgetconfig.3
@@ -0,0 +1,124 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2012 Red Hat.
+.\" Copyright (c) 2000 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 PMGETCONFIG 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmGetConfig\f1 \- return Performance Co-Pilot configuration variable
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+char *pmGetConfig(const char *\fIvariable\fP);
+.sp
+#include <pcp/impl.h>
+.br
+char *__pmGetAPIConfig(const char *\fIfeature\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+The
+.B pmGetConfig
+function searches for
+.I variable
+first in the environment and then, if not found, in
+the Performance Co-Pilot (PCP) configuration file
+and returns the string result.
+If
+.I variable
+is not already in the environment,
+it is added with a call to
+.BR putenv (3)
+before returning.
+.PP
+The default location of the PCP configuration file is
+.B /etc/pcp.conf
+but this may be changed by setting
+.B PCP_CONF
+in the environment to a new location,
+as described in
+.BR pcp.conf (5).
+.PP
+The internal
+.B __pmGetAPIConfig
+function reports on features of the PCP library.
+It can be used to query support for multi-threading, security extensions,
+and other features.
+.PP
+The
+.BR pmconfig (1)
+utility provides command line access to both of these interfaces, and also
+provides a mechanism for listing all available
+.B variables
+and
+.B features
+that are valid arguments to these routines.
+.SH "RETURN VALUE"
+If
+.I variable
+is not found in either the environment nor the PCP configuration file then
+the return value is an empty string.
+If the
+PCP configuration file is not found
+then a fatal error message is printed and the process will
+.BR exit (2)
+\- although this sounds drastic, it is the only course of action available
+because the PCP configuration/installation is fatally flawed.
+.PP
+If the
+.B pmGetConfig
+function returns a non-empty string,
+the returned value points into the environment and so changing
+it is a bad idea.
+This function returns the same type as the 
+.BR getenv (3)
+function (which should probably be a
+.IR "const char *" ).
+.PP
+The
+.B __pmGetAPIConfig
+routine on the other hand returns NULL on failure to lookup the requested
+.IR feature .
+It does not modify the environment, and returns a pointer to a static
+read-only string which also should not be modified or freed by the caller.
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR pmconfig (1),
+.BR exit (2),
+.BR PMAPI (3),
+.BR getenv (3C),
+.BR putenv (3C),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR environ (5).
diff --git a/man/man3/pmgetcontexthostname.3 b/man/man3/pmgetcontexthostname.3
new file mode 100644
index 0000000..5826861
--- /dev/null
+++ b/man/man3/pmgetcontexthostname.3
@@ -0,0 +1,114 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2013 Red Hat.
+.\" 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 PMGETCONTEXTHOSTNAME 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmGetContextHostName\f1,
+\f3pmGetContextHostName_r\f1 \- return the hostname associated with a Performance Co-Pilot context
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+const char *pmGetContextHostName(int \fIid\fP);
+.br
+char *pmGetContextHostName_r(int \fIid\fP, char *\fIbuf\fP, int \fIbuflen\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+Given a valid PCP context identifier previously created with
+.BR pmNewContext (3)
+or
+.BR pmDupContext (3),
+the
+.B pmGetContextHostName
+function returns the hostname associated with 
+.IR id .
+The
+.B pmGetContextHostName_r
+function does the same, but stores the result in a user-supplied buffer
+.I buf
+of length
+.IR buflen ,
+which should have room for at least
+.B MAXHOSTNAMELEN
+bytes.
+.PP
+If the context
+.I id
+is associated with an archive source of data, the
+hostname returned is extracted from the archive label using
+.BR pmGetArchiveLabel (3).
+.PP
+For live contexts, an attempt will first be made to retrieve
+the hostname from the PCP collector system using
+.BR pmFetch (3)
+with the
+.I pmcd.hostname
+metric.
+This allows client tools using this interface to retrieve an
+accurate host identifier even in the presence of port forwarding
+and tunnelled connections.
+.PP
+Should this not succeed, then a fallback method is used.
+For local contexts \- with local meaning any of DSO, ``localhost''
+or Unix domain socket connection \- a hostname will be sought via
+.BR gethostname (3).
+For other contexts, the hostname extracted from the initial
+context host specification will be used.
+.SH "RETURN VALUE"
+If
+.I id
+is not a valid PCP context identifier,
+the returned hostname is a zero length string.
+.SH NOTES
+.B pmGetContextHostName
+returns a pointer to a static buffer,
+so the returned value is only valid until the next call to
+.B pmGetContextHostName
+and hence is not thread-safe.
+Multi-threaded applications should use
+.B pmGetContextHostName_r
+instead.
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR PMAPI (3),
+.BR gethostname (3),
+.BR pmDupContext (3),
+.BR pmFetch (3),
+.BR pmGetArchiveLabel (3),
+.BR pmNewContext (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
diff --git a/man/man3/pmgetindom.3 b/man/man3/pmgetindom.3
new file mode 100644
index 0000000..f9ebf14
--- /dev/null
+++ b/man/man3/pmgetindom.3
@@ -0,0 +1,113 @@
+'\"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 PMGETINDOM 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmGetInDom\f1 \- get instance identifiers for a performance metrics instance domain
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmGetInDom(pmInDom \fIindom\fP, int **\fIinstlist\fP, char ***\fInamelist\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+In the current
+Performance Metrics Application Programming Interface (PMAPI)
+context,
+locate the description of the instance domain
+.IR indom ,
+and return via
+.I instlist
+the internal instance identifiers for all instances,
+and via
+.I namelist
+the full external identifiers for all instances.
+The number of instances found is returned as the function value 
+(else less than zero to indicate an error).
+.PP
+The value for the instance domain
+.I indom
+is typically extracted from a
+.CW pmDesc
+structure, following a call to
+.BR pmLookupDesc (3)
+for a particular performance metric.
+.PP
+The resulting lists of instance identifiers (\c
+.I instlist
+and
+.IR namelist ),
+and the names that the elements of
+.I namelist
+point to, will have been allocated by
+.B pmGetInDom
+with two calls to 
+.BR malloc (3C), 
+and it is the responsibility of the caller to
+.CW free(instlist)
+and
+.CW free(namelist)
+to release the space when it is no longer required.
+.PP
+When the result of
+.B pmGetInDom
+is less than one, both
+.I instlist
+and
+.I namelist
+are undefined (no space will have been allocated,
+and so calling 
+.BR free (3C)
+is a singularly bad idea).
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetConfig (3),
+.BR pmGetInDomArchive (3),
+.BR pmLookupDesc (3),
+.BR pmLookupInDom (3),
+.BR pmNameInDom (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_INDOM\f1
+.I indom
+is not a valid instance domain identifier
diff --git a/man/man3/pmgetindomarchive.3 b/man/man3/pmgetindomarchive.3
new file mode 100644
index 0000000..4b0d714
--- /dev/null
+++ b/man/man3/pmgetindomarchive.3
@@ -0,0 +1,120 @@
+'\"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 PMGETINDOMARCHIVE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmGetInDomArchive\f1 \- get instance identifiers for a performance metrics instance domain
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmGetInDomArchive(pmInDom \fIindom\fP, int **\fIinstlist\fP, char ***\fInamelist\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Provided the current
+Performance Metrics Application Programming Interface (PMAPI)
+context is associated with an archive log,
+.B pmGetInDomArchive
+will scan the union of all the instance domain metadata
+for the instance domain
+.IR indom ,
+and return via
+.I instlist
+the internal instance identifiers for all instances,
+and via
+.I namelist
+the full external identifiers for all instances.
+.PP
+This routine is a specialized version of the more general PMAPI
+routine
+.BR pmGetInDom .
+.PP
+The number of instances found is returned as the function value 
+(else less than zero to indicate an error).
+.PP
+The value for the instance domain
+.I indom
+is typically extracted from a
+.CW pmDesc
+structure, following a call to
+.BR pmLookupDesc (3)
+for a particular performance metric.
+.PP
+The resulting lists of instance identifiers (\c
+.I instlist
+and
+.IR namelist ),
+and the names that the elements of
+.I namelist
+point to, will have been allocated by
+.B pmGetInDomArchive
+with two calls to 
+.BR malloc (3C), 
+and it is the responsibility of the caller to
+.CW free(instlist)
+and
+.CW free(namelist)
+to release the space when it is no longer required.
+.PP
+When the result of
+.B pmGetInDomArchive
+is less than one, both
+.I instlist
+and
+.I namelist
+are undefined (no space will have been allocated,
+and so calling 
+.BR free (3C)
+is a singularly bad idea).
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetConfig (3),
+.BR pmGetInDom (3),
+.BR pmLookupDesc (3),
+.BR pmLookupInDomArchive (3),
+.BR pmNameInDomArchive (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOTARCHIVE\f1
+the current PMAPI context is not associated with an archive log
+.IP \f3PM_ERR_INDOM_LOG\f1
+.I indom
+is not a defined instance domain identifier for the archive log
diff --git a/man/man3/pmgetoptions.3 b/man/man3/pmgetoptions.3
new file mode 100644
index 0000000..a713b2b
--- /dev/null
+++ b/man/man3/pmgetoptions.3
@@ -0,0 +1,481 @@
+.\"
+.\" Copyright (c) 2014 Red Hat.
+.\" 
+.\" 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 PMGETOPTIONS 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmgetopt_r\f1,
+\f3pmGetOptions\f1,
+\f3pmGetContextOptions\f1,
+\f3pmFreeOptions\f1,
+\f3pmUsageMessage\f1 \- command line handling for PMAPI tools
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.br
+int pmgetopt_r(int \fIargc\fP, char *const *\fIargv\fP, pmOptions *\fIopts\fP);
+.br
+int pmGetOptions(int \fIargc\fP, char *const *\fIargv\fP, pmOptions *\fIopts\fP);
+.br
+int pmGetContextOptions(int \fIctx\fP, pmOptions *\fIopts\fP);
+.br
+void pmUsageMessage(pmOptions *\fIopts\fP);
+.br
+void pmFreeOptions(pmOptions *\fIopts\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+The
+.B pmGetOptions
+function provides command line option processing services for both
+monitor and collector
+.BR PMAPI (3)
+tools.
+It is modelled on the thread-safe variants of the GNU
+.BR getopt_long (3)
+API, and primarily differs in its focus on providing generalised
+processing for the (de-facto) standard PCP command line options
+described in
+.BR PCPIntro (1).
+These common options include the host and archive specification,
+time windows, timezones, sample counts, time intervals, and so on.
+.PP
+The primary interface is
+.BR pmGetOptions ,
+which should be passed the
+.I argc
+argument count and
+.I argv
+array, as passed to the
+.IR main()
+function on program invocation.
+The final
+.I opts
+argument describes the set of long and short options the tools is
+prepared to process, and other metadata regarding how those options
+should be processed.
+.PP
+The
+.B pmgetopt_r
+interface, used internally by
+.BR pmGetOptions ,
+behaves in a similar fashion, but it does not perform any common
+option processing.
+It is more suited to PCP collector processes, whereas PCP monitor
+tools tend to use
+.BR pmGetOptions .
+.PP
+The
+.I opts
+argument consists of an array of
+.I pmLongOpts
+entries describing the arguments, as well as the enclosing
+.I pmOptions
+struct, which are defined as follows (internal fields are not
+presented, for brevity):
+.PP
+.sp 0.5v
+.ft CW
+.nf
+.in +0.25i
+typedef struct {
+    const char *        long_opt;
+    int                 has_arg;
+    int                 short_opt;
+    const char *        argname;
+    const char *        message;
+} pmLongOptions;
+
+typedef struct {
+    int                 version;
+    int                 flags;
+    const char *        short_options;
+    pmLongOptions *     long_options;
+    const char *        short_usage;
+    pmOptionOverride    override;
+
+    int                 index;
+    int                 optind;
+    int                 opterr;
+    int                 optopt;
+    char                *optarg;
+    /* [internal fields, undocumented] */
+
+    int                 errors;
+    int                 context; /* PM_CONTEXT_{HOST,ARCHIVE,LOCAL} */
+    int                 nhosts;
+    int                 narchives;
+    char **             hosts;
+    char **             archives;
+    struct timeval      start;
+    struct timeval      finish;
+    struct timeval      origin;
+    struct timeval      interval;
+    char *              align_optarg;
+    char *              start_optarg;
+    char *              finish_optarg;
+    char *              origin_optarg;
+    char *              guiport_optarg;
+    char *              timezone;
+    int                 samples;
+    int                 guiport;
+    int                 padding;
+    unsigned int        guiflag : 1;
+    unsigned int        tzflag  : 1;
+    unsigned int        nsflag  : 1;
+    unsigned int        Lflag   : 1;
+    unsigned int        zeroes  : 28;
+} pmOptions;
+.in -0.25i
+.fi
+.ft R
+.PP
+The initial
+.I flags
+and
+.I version
+fields describe how the rest of the pmOptions structure is to be
+interpreted.
+These fields can be zeroed, specifying a default interpretation.
+Alternatively, the PMAPI_VERSION macro can be used to specify the
+API level to use (currently, values of 2 or less are allowed).
+The
+.I flags
+field can be used to modify option processing behaviour as
+described in the ``FLAGS VALUES'' section below.
+.PP
+The array of
+.I long_options
+pmLongOpts structures must be terminated by a sentinel and the
+PMAPI_OPTIONS_END macro can be used to effect this termination.
+Individual records within the
+.I long_options
+array can be of two types \- options headers, or actual options.
+An options header is constructed using the PMAPI_OPTIONS_HEADER
+macro, and is used for usage message option grouping.
+Free form text can be inserted into the usage message at any
+point using the PMAPI_OPTIONS_TEXT macro \- this is intended
+for additional explanatory text covering detailed usage that
+is beyond the scope of the individual headers or options.
+Otherwise, the array entry specifies an option.
+These should be named (\c
+.IR long_opt )
+if a long-option form is allowed,
+specify whether or not they take an argument (\c
+.IR has_arg ),
+specify the single character variant argument (\c
+.IR short_opt )
+if a short-option form is allowed,
+and finally specify how to present the option in the usage message.
+This latter component consists of a short, one-word description of
+the optional argument (\c
+.IR argname )
+and a one-line description of what the command-line option does (\c
+.IR message ).
+.PP
+The
+.I short_usage
+string is also used only when constructing the usage message.
+It forms the component of the usage message that follows the
+program name (i.e. \c
+.IR argv[0] ).
+.PP
+The optional
+.I short_options
+string is the normal
+.I getopt
+command-line option specification string, using individual
+characters (those with arguments are designated as such
+using the ':' character) \- as used by all
+.I getopt
+implementations.
+.PP
+A facility is provided to extend the existing set of common options
+with additional options, as well as to re-task the standard options
+into non-standard roles for individual tools.
+The latter is achieved using the
+.I override
+method, which allows a callback function to be provided which will
+be called on receipt of every argument, prior to common processing.
+If this callback returns a non-zero value the common processing will
+be short-circuited for that option, otherwise processing continues.
+Thus, aach client tool is free to choose exactly which of the standard
+options they wish to support \- this can be all, some, or none, and
+no matter what they choose, each tool always has access to the long
+option parsing capability and the usage message generation facility.
+.PP
+The remaining pmOptions structure fields are filled in as a result
+of processing the arguments, and are largely self-explanatory.
+Further discussion of these is deferred to the ``FLAGS VALUES''
+section below.
+The
+.I error
+field contains a count of errors detected during option processing.
+These can be either usage or runtime errors, as indicated by the
+.I flags
+field (set, and passed out to the caller).
+Typically, a command line tool will fail to start successfully and
+will produce an error message (e.g. via
+.BR pmUsageMessage )
+if the
+.I error
+field is non-zero at the end of either
+.B pmGetOptions
+or
+.BR pmGetContextOptions .
+.PP
+Some command line option post-processing can only be performed once
+the tool has established a PMAPI context via
+.BR pmNewContext (3).
+This processing includes use of context-aware timezones (\f3\-z\f1),
+and time window processing (\f3\-A\f1, \f3\-O\f1, \f3\-S\f1, \f3\-T\f1)
+that may be affected by the timezone, for example.
+The
+.B pmGetContextOptions
+function is available for such situations, and it completes any
+remaining processing of
+.I opts
+with respect to the
+.I ctx
+context identifier given.
+.PP
+The
+.B pmUsageMessage
+function generates a usage message for the tool, and included both
+standard PCP options and custom options for each tool, as specified
+by the pmLongOptions array.
+It supports grouping of options (via PMAPI_OPTIONS_HEADER) as well
+as neat formatting of all options \- short and long \- their
+arguments, and individual explanatory messages.
+It will build this usage message using
+.BR pmprintf (3)
+upon which it will issue a single
+.BR pmflush (3)
+before returning to the caller, provided the PM_OPTFLAG_USAGE_ERR
+flag is set in
+.IR flags ,
+which will happen automatically during option parsing, when usage
+errors are detected.
+.PP
+In certain situations, such as recording lists of host specifications
+or PCP archive paths, the
+.B pmGetOptions
+routine may allocate memory, and store pointers to it within
+.IR opts .
+Should a program wish to free this memory before exiting, it can
+use the
+.B pmFreeOptions
+routine to do so.
+This is safe to call irrespective of whether memory was allocated
+dynamically, provided that
+.I opts
+was zeroed initially.
+.SH "FLAGS VALUES"
+.TP
+.B PM_OPTFLAG_INIT
+Used internally within the library to indicate initialisation has been
+done, so that on subsequent calls it will not be done again.
+.TP
+.B PM_OPTFLAG_DONE
+Used primarily internally within the library to indicate that the final
+option processing has been completed.
+This processing involves cross-referencing a number of the options, to
+check for mutual exclusion, for example.
+There may be other post-processing at this stage also, provided it does
+not require a PMAPI context.
+.TP
+.B PM_OPTFLAG_MULTI
+Allow more than one host or archive to be specified.
+The default is to allow one source of metrics only, however some of the
+more sophisticated tools permit multiple metric sources.
+See also
+.BR PM_OPTFLAG_MIXED .
+.TP
+.B PM_OPTFLAG_USAGE_ERR
+Indicates that the library has detected a command-line usage error.
+This is an error such as when an option requires an argument but none
+is supplied, or conflicting options are specified (such as \f3\-s\f1
+and \f3-T\f1).
+.TP
+.B PM_OPTFLAG_RUNTIME_ERR
+Indicates that the library has detected an error at run time.
+This is an error such as failing to retrieve timezone information
+from
+.B pmcd (1)
+or
+failing to load an alternate metric namespace from a local file
+(via the \f3-n\f1 option).
+.TP
+.B PM_OPTFLAG_EXIT
+Indicates a suggestion from the library that the tool exit cleanly.
+This is used when the version number is requested, for example (the
+\f3\-V\f1 option and PMOPT_VERSION macro).
+.TP
+.B PM_OPTFLAG_POSIX
+Use strict POSIX command line argument handling.
+This means options and following arguments will not be reordered,
+so additional options cannot follow command line arguments.
+This may be important for tools where the arguments can be negative
+numbers, for example, as these should not be treated as command line
+options in this case.
+.TP
+.B PM_OPTFLAG_MIXED
+Allow both live and archive metric sources to be specified.
+The default is to allow one type of metric context only, however some
+of the more sophisticated tools permit multiple context types.
+See also
+.BR PM_OPTFLAG_MULTI .
+.TP
+.B PM_OPTFLAG_ENV_ONLY
+Many options can be specified through the either the command line
+or from similarly-named environment variables.
+This flag disables all argument parsing, and only changes
+.I opts
+based on the environment variables.
+This may be useful for tools wishing to ensure no command line option
+conflicts occur between their own set and the standard PCP option set
+(such as an existing tool, reimplemented using PMAPI services).
+.TP
+.B PM_OPTFLAG_LONG_ONLY
+Only process long options, not short options.
+.TP
+.B PM_OPTFLAG_BOUNDARIES
+The default
+.B pmGetOptions
+behaviour is to parse the time window options (namely, \f3\-A\f1,
+\f3\-O\f1, \f3\-S\f1 and \f3\-T\f1), only if one of those options
+has been specified on the command line.
+However, this flag can be used (particularly with archive contexts)
+to find the
+.I start
+and
+.I finish
+times associated with the context(s) even if no time window options
+were specified.
+In the case of multiple archives, the time window is defined as the
+time window spanning all of the archives.
+.TP
+.B PM_OPTFLAG_STDOUT_TZ
+The timezone being used will be reported on the standard output
+stream during option parsing.
+The default behaviour is to not report, but simply return timezone
+information via the
+.I timezone
+(\f3\-Z\f1)
+and
+.I tzflag
+(\f3\-z\f1)
+fields in the
+.I opts
+structure.
+.TP
+.B PM_OPTFLAG_NOFLUSH
+The final
+.B pmflush
+call issued by
+.B pmUsageMessage
+will be skipped if this flag is set.
+This is useful in situations where the caller wishes to append
+additional test to the generated usage message before flushing.
+.TP
+.B PM_OPTFLAG_QUIET
+Suppress messages from
+.B pmgetopt_r
+about unrecognised command line options.
+This is the equivalent to setting the
+.I opterr
+field in the
+.I opt
+parameter (which mimics the
+.B getopt
+variable of the same name).
+.SH "RETURN VALUE"
+The
+.B pmGetOptions
+function returns either when it detects a command-line option that
+is not one of the standard PCP set, or when the end of the command
+line options has been reached (at which point -1 is returned).
+Both the
+.B pmgetopt_r
+and
+.B pmGetOptions
+routines return control to the caller in the same way that a regular
+.B getopt
+call would, with the return value indicating either the end of all
+processing (-1), or the single character form of the option currently
+being processed, or zero for the special long-option-only case.
+For all option-processing cases, the
+.I opts
+structure is returned containing filled out
+.IR optarg ,
+.IR opterr ,
+.IR optopt ,
+.IR optind ,
+and
+.I index
+fields as normal (do
+.B NOT
+use the global optarg or optind from your platform C library,
+these will
+.B NOT
+be modified).
+.PP
+.B pmGetOptions
+does not return to the caller when any of the standard PCP options are
+being processed (although the
+.I override
+mechanism can be used to still detect such options if needed).
+.PP
+The
+.B pmGetContextOptions
+function returns zero on success, or a negative PCP error code
+on failure.
+The
+.I error
+field within the
+.I
+opts
+parameter will also be non-zero in the latter case.
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetOptions (3)
+function.
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR pmcd (1),
+.BR pminfo (1),
+.BR pmstat (1),
+.BR getopt (3),
+.BR getopt_long (3),
+.BR pmNewContext (3),
+.BR pmconfig (3),
+.BR pmprintf (3),
+.BR pmflush (3)
+and
+.BR PMAPI (3).
diff --git a/man/man3/pmgetpmnslocation.3 b/man/man3/pmgetpmnslocation.3
new file mode 100644
index 0000000..0c1bd78
--- /dev/null
+++ b/man/man3/pmgetpmnslocation.3
@@ -0,0 +1,69 @@
+'\"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 PMGETPMNSLOCATION 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmGetPMNSLocation\f1 \- determine the location of the currently used PMNS 
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmGetPMNSLocation(void);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+If an application needs to know where the Performance Metrics Name Space
+(PMNS) is coming from then
+.B pmGetPMNSLocation
+will return whether it is from an archive, \f3PMNS_ARCHIVE\f1,
+or from a local PMNS file, \f3PMNS_LOCAL\f1, or from a remote pmcd,
+\f3PMNS_REMOTE\f1.
+.P
+This information may be useful in determining an appropriate error message
+depending on the PMNS' location.
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetConfig (3),
+.BR pmLoadASCIINameSpace (3),
+.BR pmLoadNameSpace (3),
+.BR pmTrimNameSpace (3),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR pmns (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOPMNS\f1
+If is not possible to determine where the location of the PMNS is.
+This could be due to problems with the current context or being
+unable to load a local PMNS.
diff --git a/man/man3/pmiaddinstance.3 b/man/man3/pmiaddinstance.3
new file mode 100644
index 0000000..4d4f026
--- /dev/null
+++ b/man/man3/pmiaddinstance.3
@@ -0,0 +1,84 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 PMIADDINSTANCE 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmiAddInstance\f1 \- add an element to an instance domain in a LOGIMPORT context
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/import.h>
+.sp
+int pmiAddInstance(pmInDom \fIindom\fP, const char *\fIinstance\fP, int \fIinst\fP);
+.sp
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.sp
+pmiAddInstance($\fIindom\fP, $\fIinstance\fP, $\fIinst\fP);
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+.B pmiAddInstance
+adds a new element to the instance domain identified by
+.IR indom .
+.PP
+.I indom
+would normally be constructed using the
+.B pmInDom_build
+macro, e.g. pmInDom_build(PMI_DOMAIN,0) for the first instance domain
+in the Performance Metrics Domain PMI_DOMAIN
+(which is the default for all meta data created by the LOGIMPORT library).
+.PP
+The new instance must have both an external name (\c
+.IR instance )
+and an internal instance identifier (\c
+.IR inst )
+that is unique across all instances in the
+.I indom
+instance domain.
+There is a special ``uniqueness rule'' for
+.I instance
+that is imposed by
+.BR pmLookupInDom (3),
+namely that the external instance name must be unique in the leading
+non-space characters, e.g. the instance names ``foo'' and ``foo bar''
+are considered the same by this rule and not allowed in the same
+instance domain, but ``foo'' and ``foobar'' would be allowed.
+.PP
+Once defined, the external instance name can be used in calls to
+.BR pmiGetHandle (3)
+and/or
+.BR pmiPutValue (3)
+with the name of a metric defined over the same instance domain.
+.SH DIAGNOSTICS
+.B pmiAddInstance
+returns zero on success else a negative value that can be turned into an
+error message by calling
+.BR pmiErrStr (3).
+.SH SEE ALSO
+.BR LOGIMPORT (3),
+.BR pmiAddMetric (3),
+.BR pmiErrStr (3),
+.BR pmiGetHandle (3),
+.BR pmiPutValue (3)
+and
+.BR pmLookupInDom (3).
diff --git a/man/man3/pmiaddmetric.3 b/man/man3/pmiaddmetric.3
new file mode 100644
index 0000000..ac0b39d
--- /dev/null
+++ b/man/man3/pmiaddmetric.3
@@ -0,0 +1,133 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 PMIADDMETRIC 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmiAddMetric\f1 \- add a new metric definition to a LOGIMPORT context
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/import.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmiAddMetric(const char *\fIname\fP, pmID \fIpmid\fP, int\ \fItype\fP, pmInDom\ \fIindom\fP, int\ \fIsem\fP, pmUnits\ \fIunits\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.sp
+pmiAddMetric($\fIname\fP, $\fIpmid\fP, $\fItype\fP, $\fIindom\fP, $\fIsem\fP, $\fIunits\fP);
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+.B pmiAddMetric
+is used to define a new metric.  The metric's
+.I name
+must follow the naming conventions described in
+.BR PCPIntro (1)
+and should be unique for each LOGIMPORT context.
+.PP
+The other arguments are in effect the fields of a
+.B pmDesc
+structure.
+Refer to
+.BR pmLookupDesc (3)
+for a complete description of the values and semantics of the
+components of this
+structure, and hence the valid argument values for
+.BR pmiAddMetrics .
+.PP
+The internal identifier for the metric may be given using the
+.I pmid
+argument and must be unique for each LOGIMPORT context.
+The value for
+.I pmid
+which would typically be constructed using the
+.B pmid_build
+macro, e.g. pmid_build(PMI_DOMAIN, 0, 3) for the fourth metric in
+first ``cluster'' of metrics in the Performance Metrics Domain PMI_DOMAIN
+(which is the default for all meta data created by the LOGIMPORT library).
+Alternatively,
+.I pmid
+may be
+.B PM_IN_NULL
+and
+.B pmiAddMetric
+will assign a unique
+.I pmid
+(although this means the
+.I pmid
+remains opaque and the application must use
+.BR pmiPutValue (3)
+or
+.BR pmiPutValueHandle (3)
+and cannot use
+.BR pmiPutResult (3)
+to add data values to the PCP archive).
+.PP
+.I type
+defines the data type of the metric and must be one of the
+.B PM_TYPE_...
+values
+defined in
+.BR <pcp/import.h> .
+.PP
+The instance domain for the metric is defined by
+.I indom
+and may be
+.B PM_INDOM_NULL
+for a metric with a singular value, else the value for
+.I indom
+would normally be constructed using the
+.B pmInDom_build
+macro, e.g. pmInDom_build(LOGIMPORT,0) for the first instance domain
+in the Performance Metrics Domain LOGIMPORT
+(which is the default for all meta data created by the LOGIMPORT library).
+Multiple metrics can share the same instance domain if they have
+values for a similar (or more usually, identical) set of instances.
+.PP
+The semantics of the metric (counter, instantaneous value, etc.) is
+specified by the
+.I sem
+argument which would normally be the result of a call to the
+convenience constructor method
+.BR pmiUnits (3).
+.SH DIAGNOSTICS
+.B pmiAddMetric
+returns zero on success else a negative value that can be turned into an
+error message by calling
+.BR pmiErrStr (3).
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR LOGIMPORT (3),
+.BR pmiErrStr (3),
+.BR pmiPutResult (3),
+.BR pmiPutValue (3),
+.BR pmiPutValueHandle (3),
+.BR pmiUnits (3)
+and
+.BR pmLookupDesc (3).
diff --git a/man/man3/pmidstr.3 b/man/man3/pmidstr.3
new file mode 100644
index 0000000..1e49fa6
--- /dev/null
+++ b/man/man3/pmidstr.3
@@ -0,0 +1,107 @@
+'\"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 PMIDSTR 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmIDStr\f1,
+\f3pmIDStr_r\f1 \- convert a performance metric identifier into a string
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+const char *pmIDStr(pmID \fIpmid\fP);
+.br
+char *pmIDStr_r(pmID \fIpmid\fP, char *\fIbuf\fP, int \fIbuflen\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+For use in error and diagnostic messages,
+.B pmIDStr
+returns a `human readable' version of
+the specified Performance Metric Identifier (PMID).
+The
+.B pmIDStr_r
+function does the same, but stores the result in a user-supplied buffer
+.I buf
+of length
+.IR buflen ,
+which should have room for at least 20 bytes.
+.PP
+Internally, a PMID is
+encoded as follows;
+.PP
+.ft CW
+.nf
+.in +0.5i
+typedef struct {
+    int             pad:2;
+    unsigned int    domain:8;
+    unsigned int    cluster:12;
+    unsigned int    item:10;
+} __pmID_int;
+.in
+.fi
+.ft 1
+.PP
+.B pmIDStr
+returns a string with each of the
+.CW domain ,
+.CW cluster
+and
+.CW item
+subfields appearing as decimal numbers, separated by periods.
+.PP
+The string value result from
+.B pmIDStr
+is held in a single static buffer, so the returned value is
+only valid until the next call to
+.BR pmIDStr .
+.SH NOTES
+.B pmIDStr
+returns a pointer to a static buffer and hence is not thread-safe.
+Multi-threaded applications should use
+.B pmIDStr_r
+instead.
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetConfig (3),
+.BR pmInDomStr (3),
+.BR pmLookupDesc (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
diff --git a/man/man3/pmiend.3 b/man/man3/pmiend.3
new file mode 100644
index 0000000..0c5d179
--- /dev/null
+++ b/man/man3/pmiend.3
@@ -0,0 +1,59 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 PMIEND 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmiEnd\f1 \- finish up a LOGIMPORT archive
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/import.h>
+.sp
+int pmiEnd(void);
+.sp
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.sp
+pmiEnd();
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+.B pmiEnd
+closes the current context, forcing the trailer records
+to be written to the PCP archive files, and then these files are
+closed.
+.PP
+In normal operations, an application would include a call
+to
+.B pmiEnd
+at the end of processing for each context created with a call
+to
+.BR pmiStart (3).
+.SH DIAGNOSTICS
+.B pmiEnd
+returns zero on success else a negative value that can be turned into an
+error message by calling
+.BR pmiErrStr (3).
+.SH SEE ALSO
+.BR LOGIMPORT (3)
+and
+.BR pmiStart (3).
diff --git a/man/man3/pmierrstr.3 b/man/man3/pmierrstr.3
new file mode 100644
index 0000000..f41351c
--- /dev/null
+++ b/man/man3/pmierrstr.3
@@ -0,0 +1,78 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2012 Red Hat.
+.\" Copyright (c) 2010 Ken McDonell.  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 PMIERRSTR 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmiErrStr\f1 \- convert a LOGIMPORT error code into a string
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/import.h>
+.sp
+const char *pmiErrStr(int \fIcode\fP);
+.br
+char *pmiErrStr_r(int \fIcode\fP, char \fIbuf\fP, int \fIbuflen\fP);
+.sp
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.sp
+pmiErrStr($\fIcode\fP);
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+.B pmiErrStr
+translates error codes returned from the other routines
+in the Log Import library into printable error messages.
+.PP
+.I code
+would normally have a negative value.
+As a special case, if
+.I code
+is \-1 then the error code returned from the last routine
+called in the LOGIMPORT library for this context will be
+used.
+.PP
+The
+.B pmiErrStr_r
+function does the same, but stores the result in a user-supplied buffer
+.I buf
+of length
+.IR buflen ,
+which should have room for at least
+.B PMI_MAXERRMSGLEN
+bytes.
+.PP
+The set of possible error codes and messages is all those defined
+by
+.BR pmErrStr (3)
+and
+.BR PCPIntro (3),
+plus the additonal ones defined in
+.B <pcp/import.h>
+with error code names of the form
+.BR PMI_ERR_....
+.SH DIAGNOSTICS
+None.
+.SH SEE ALSO
+.BR LOGIMPORT (3),
+.BR PCPIntro (3)
+and
+.BR pmErrStr (3).
diff --git a/man/man3/pmigethandle.3 b/man/man3/pmigethandle.3
new file mode 100644
index 0000000..b7c6cd2
--- /dev/null
+++ b/man/man3/pmigethandle.3
@@ -0,0 +1,81 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 PMIGETHANDLE3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmiGetHandle\f1 \- define a handle for a metric-instance pair
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/import.h>
+.sp
+int pmiGetHandle(const char *\fIname\fP, const char *\fIinstance\fP);
+.sp
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.sp
+$\fIhandle\fP = pmiGetHandle($\fIname\fP, $\fIinstance\fP);
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+.B pmiGetHandle
+creates a handle for a given
+metric and instance.  The handle is returned as the value from the
+.B pmiGetHandle
+call and can be used in subsequent calls to
+.BR pmiPutValueHandle (3).
+.PP
+The metric's
+.I name
+should match one defined earlier in a call to
+.BR pmiAddMetric (3).
+.PP
+For singular metrics (those defined with an instance domain of
+.BR PM_INDOM_NULL ),
+the
+.I instance
+should be NULL or an empty string, otherwise
+.I instance
+should match the name of an instance defined earlier in a call
+to
+.BR pmiAddInstance (3)
+for the metric's instance domain.
+.PP
+When combined with
+.BR pmiPutValueHandle (3),
+the use of handles provide a performance improvement over the
+alternative lookup for a metric name and an instance name for
+each data value that is required for
+.BR pmiPutValue (3).
+.SH DIAGNOSTICS
+On failure
+.B pmiGetHandle
+returns a negative value that can be turned into an
+error message by calling
+.BR pmiErrStr (3).
+.SH SEE ALSO
+.BR LOGIMPORT (3),
+.BR pmiAddInstance (3),
+.BR pmiAddMetric (3),
+.BR pmiErrStr (3)
+and
+.BR pmiPutValueHandle (3).
diff --git a/man/man3/pmindomstr.3 b/man/man3/pmindomstr.3
new file mode 100644
index 0000000..b0c8135
--- /dev/null
+++ b/man/man3/pmindomstr.3
@@ -0,0 +1,113 @@
+'\"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 PMINDOMSTR 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmInDomStr\f1,
+\f3pmInDomStr_r\f1 \- convert a performance metric instance domain identifier into a string
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+const char *pmInDomStr(pmInDom \fIindom\fP);
+.br
+char *pmInDomStr_r(pmInDom \fIindom\fP, char *\fIbuf\fP, int \fIbuflen\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+For use in error and diagnostic messages,
+.B pmInDomStr
+return a 'human readable' version of
+the specified instance domain identifier.
+The
+.B pmInDomStr_r
+function does the same, but stores the result in a user-supplied buffer
+.I buf
+of length
+.IR buflen ,
+which should have room for at least 20 bytes.
+.PP
+The value for the instance domain
+.I indom
+is typically extracted from a
+.CW pmDesc
+structure, following a call to
+.BR pmLookupDesc (3)
+for a particular performance metric.
+.PP
+Internally, an instance domain identifier is
+encoded as follows;
+.PP
+.ft CW
+.nf
+.in +0.5i
+typedef struct {
+    int             pad:2;
+    unsigned int    domain:8;        /* the administrative PMD */
+    unsigned int    serial:22;       /* unique within PMD */
+} __pmInDom_int;
+.in
+.fi
+.ft 1
+.PP
+.B pmInDomStr
+returns a string with each of the
+.CW domain
+and
+.CW serial
+subfields appearing as decimal numbers, separated by periods.
+.PP
+The string value returned by
+.B pmInDomStr
+is held in a single static buffer, so the returned value is
+only valid until the next call to
+.BR pmInDomStr .
+.SH NOTES
+.B pmInDomStr
+returns a pointer to a static buffer and hence is not thread-safe.
+Multi-threaded applications should use
+.B pmInDomStr_r
+instead.
+.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).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetConfig (3),
+.BR pmIDStr (3),
+.BR pmLookupDesc (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
diff --git a/man/man3/pmiputresult.3 b/man/man3/pmiputresult.3
new file mode 100644
index 0000000..a73155c
--- /dev/null
+++ b/man/man3/pmiputresult.3
@@ -0,0 +1,82 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 PMIPUTRESULT 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmiPutResult\f1 \- add a data record to a LOGIMPORT archive
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/import.h>
+.sp
+int pmiPutResult(const pmResult *\fIresult\fP);
+.sp
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+.B pmiPutResult
+provides an interface for developers familiar with the internal
+PCP data structures to create output archives directly.
+.PP
+By building the
+.B pmResult
+data structure directly, then calling
+.B pmiPutResult
+the developer avoids calls to
+.BR pmiPutValue (3)
+and/or
+.BR pmiPutValueHandle (3)
+followed by a call to
+.BR pmiWrite (3)
+for each record written to the archive.
+.PP
+Any metrics and instances appearing in the
+.I result
+must have been defined by prior calls to
+.BR pmiAddMetric (3)
+and
+.BR pmiAddInstance (3).
+.PP
+.B pmiPutResult
+will arrange for any new metadata (metrics and/or instance domain changes)
+covered by
+.I result
+to be also written to the PCP archive.
+.PP
+Because of the complexity of the
+.B pmResult
+data structure, this routine is not available in the Perl
+interface to the LOGIMPORT services.
+.SH DIAGNOSTICS
+.B pmiPutResult
+returns zero on success else a negative value that can be turned into an
+error message by calling
+.BR pmiErrStr (3).
+.SH SEE ALSO
+.BR LOGIMPORT (3),
+.BR PMAPI (3),
+.BR pmiAddInstance (3),
+.BR pmiAddMetric (3),
+.BR pmiErrStr (3),
+.BR pmiPutValue (3),
+.BR pmiPutValueHandle (3),
+.BR pmiSetTimezone (3)
+and
+.BR pmiWrite (3).
diff --git a/man/man3/pmiputvalue.3 b/man/man3/pmiputvalue.3
new file mode 100644
index 0000000..4ab41f6
--- /dev/null
+++ b/man/man3/pmiputvalue.3
@@ -0,0 +1,95 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 PMIPUTVALUE 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmiPutValue\f1 \- add a value for a metric-instance pair
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/import.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmiPutValue(const char *\fIname\fP, const char *\fIinstance\fP, const\ char\ *\fIvalue\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.sp
+pmiPutValue($\fIname\fP, $\fIinstance\fP, $\fIvalue\fP);
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+.B pmiPutValue
+adds a single value to the current output record for a given
+metric and instance.
+.PP
+The metric's
+.I name
+should match one defined earlier in a call to
+.BR pmiAddMetric (3).
+.PP
+For singular metrics (those defined with an instance domain of
+.BR PM_INDOM_NULL ),
+the
+.I instance
+should be NULL or an empty string, otherwise
+.I instance
+should match the name of an instance defined earlier in a call
+to
+.BR pmiAddInstance (3)
+for the metric's instance domain.
+.PP
+The
+.I value
+should be in a format consistent with the metric's type as
+defined in the call to
+.BR pmiAddMetric (3).
+.PP
+No data will be written until
+.BR pmiWrite (3)
+is called, so multiple calls to
+.B pmiPutValue
+or
+.BR pmiPutValueHandle (3)
+are typically used to accumulate data values for several
+metric-instance pairs before calling
+.BR pmiWrite (3).
+.SH DIAGNOSTICS
+.B pmiPutValue
+returns zero on success else a negative value that can be turned into an
+error message by calling
+.BR pmiErrStr (3).
+.SH SEE ALSO
+.BR LOGIMPORT (3),
+.BR pmiAddInstance (3),
+.BR pmiAddMetric (3),
+.BR pmiErrStr (3),
+.BR pmiPutResult (3),
+.BR pmiPutValueHandle (3)
+and
+.BR pmiWrite (3).
diff --git a/man/man3/pmiputvaluehandle.3 b/man/man3/pmiputvaluehandle.3
new file mode 100644
index 0000000..d9924a5
--- /dev/null
+++ b/man/man3/pmiputvaluehandle.3
@@ -0,0 +1,74 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 PMIPUTVALUEHANDLE 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmiPutValueHandle\f1 \- add a value for a metric-instance pair via a handle
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/import.h>
+.sp
+int pmiPutValueHandle(int \fIhandle\fP, const char *\fIvalue\fP);
+.sp
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.sp
+pmiPutValueHandle($\fIhandle\fP, $\fIvalue\fP);
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+.B pmiPutValueHandle
+adds a single value to the current output record for a given
+metric and instance, using the
+.I handle
+defined by an earlier call to
+.BR pmiGetHandle (3).
+.PP
+The
+.I value
+should be in a format consistent with the metric's type as
+defined in the call to
+.BR pmiAddMetric (3).
+.PP
+No data will be written until
+.BR pmiWrite (3)
+is called, so multiple calls to
+.B pmiPutValueHandle
+or
+.BR pmiPutValue (3)
+are typically used to accumulate data values for several
+metric-instance pairs before calling
+.BR pmiWrite (3).
+.SH DIAGNOSTICS
+.B pmiPutValueHandle
+returns zero on success else a negative value that can be turned into an
+error message by calling
+.BR pmiErrStr (3).
+.SH SEE ALSO
+.BR LOGIMPORT (3),
+.BR pmiErrStr (3),
+.BR pmiGetHandle (3),
+.BR pmiPutResult (3),
+.BR pmiPutValue (3)
+and
+.BR pmiWrite (3).
diff --git a/man/man3/pmisethostname.3 b/man/man3/pmisethostname.3
new file mode 100644
index 0000000..bfd4ba1
--- /dev/null
+++ b/man/man3/pmisethostname.3
@@ -0,0 +1,57 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 PMISETHOSTNAME 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmiSetHostname\f1 \- set the source host name for a LOGIMPORT archive
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/import.h>
+.sp
+int pmiSetHostname(const char *\fIvalue\fP);
+.sp
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.sp
+pmiSetHostname($\fIvalue\fP);
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+.B pmiSetHostname
+sets the source hostname in the current context to be
+.IR value .
+.PP
+In the absence of a call to
+.B pmiSetHostname
+the source hostname defaults to the hostname of the localhost.
+.SH DIAGNOSTICS
+.B pmiSetHostname
+returns zero on success else a negative value that can be turned into an
+error message by calling
+.BR pmiErrStr (3).
+.SH SEE ALSO
+.BR LOGIMPORT (3),
+.BR pmiErrStr (3),
+.BR pmiSetTimezone (3)
+and
+.BR pmiStart (3).
diff --git a/man/man3/pmisettimezone.3 b/man/man3/pmisettimezone.3
new file mode 100644
index 0000000..a4186aa
--- /dev/null
+++ b/man/man3/pmisettimezone.3
@@ -0,0 +1,57 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 PMISETTIMEZONE 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmiSetTimezone\f1 \- set the source timezone for a LOGIMPORT archive
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/import.h>
+.sp
+int pmiSetTimezone(const char *\fIvalue\fP);
+.sp
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.sp
+pmiSetTimezone($\fIvalue\fP);
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+.B pmiSetTimezone
+sets the source timezone in the current context to be
+.IR value .
+.PP
+In the absence of a call to
+.B pmiSetTimezone
+the source timezone defaults to the timezone of the localhost.
+.SH DIAGNOSTICS
+.B pmiSetTimezone
+returns zero on success else a negative value that can be turned into an
+error message by calling
+.BR pmiErrStr (3).
+.SH SEE ALSO
+.BR LOGIMPORT (3),
+.BR pmiErrStr (3),
+.BR pmiSetHostname (3)
+and
+.BR pmiStart (3).
diff --git a/man/man3/pmistart.3 b/man/man3/pmistart.3
new file mode 100644
index 0000000..fcb66fb
--- /dev/null
+++ b/man/man3/pmistart.3
@@ -0,0 +1,139 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 PMISTART 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmiStart\f1 \- establish a new LOGIMPORT context
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/import.h>
+.sp
+int pmiStart(const char *\fIarchive\fP, int \fIinherit\fP);
+.sp
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.sp
+pmiStart($\fIarchive\fP, $\fIinherit\fP);
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+.B pmiStart
+creates a new context.  Each context maintains the following
+state and metadata:
+.IP \(bu 3n
+The base name (\c
+.IR archive )
+for the physical  files
+that constitute the output PCP archive.
+.IP \(bu 3n
+The source hostname for the data that will be written to the
+PCP archive.  Defaults to the hostname of the localhost, but can be set using
+.BR pmiSetHostname (3).
+.IP \(bu 3n
+The source timezone for the 
+PCP archive.  Defaults to the timezone of the localhost, but can be set using
+.BR pmiSetTimezone (3).
+.IP \(bu 3n
+Metrics and instance domains, as defined by
+.BR pmiAddMetric (3).
+.IP \(bu 3n
+Instances for each instance domain, as defined by
+.BR pmiAddInstance (3).
+.IP \(bu 3n
+Handles as defined by
+.BR pmiGetHandle (3).
+Each handle is a metric-instance pair, and each metric-instance pair
+may have an associated value in each record written to the output
+PCP archive.
+.IP \(bu 3n
+An optional set of data values for one or more metric-instance pairs
+(ready for the next record to be written
+to the output PCP archive) as defined
+by calls to
+.BR pmPutValue (3)
+or
+.BR pmPutValuehandle (3).
+.PP
+If
+.I inherit
+is true, then the new context will inherit any and all
+metadata (metrics, instance domains, instances and handles) from the current
+context, otherwise the new context is created with no metadata.
+The basename for the output PCP archive, the source hostname, the
+source timezone and any data values from the current context are
+.B not
+inherited.
+If this is the first call to
+.B pmiStart
+the metadata will be empty
+independent of the value of
+.IR inherit .
+.PP
+Since no physical files for the output PCP archive
+will be created until the first call to
+.BR pmiWrite (3)
+or
+.BR pmiPutRecord(3),
+.I archive
+could be NULL to create a
+convenience context that is populated with metadata to be
+inherited by subsequent contexts.
+.PP
+The return value is a context identifier that
+could be used in a subsequent call to
+.BR pmUseContext (3)
+and the
+new context becomes the current context which
+persists for all subsequent calls up to either another
+.B pmiStart
+call or a call to
+.BR pmiUseContext (3)
+or a call to
+.BR pmiEnd (3).
+.SH DIAGNOSTICS
+It is an error if the physical files
+\fIarchive\fR.\fB0\fR and/or
+\fIarchive\fR.\fBindex\fR and/or
+\fIarchive\fR.\fBmeta\fR already exist, but this is not discovered
+until the first attempt is made to output some data by calling
+.BR pmiWrite (3)
+or
+.BR pmiPutRecord(3),
+so
+.B pmiStart
+always returns a positive context identifier.
+.SH SEE ALSO
+.BR LOGIMPORT (3),
+.BR pmiAddInstance (3),
+.BR pmiAddMetric (3),
+.BR pmiEnd (3),
+.BR pmiErrStr (3),
+.BR pmiGetHandle (3),
+.BR pmiPutResult (3),
+.BR pmiPutValue (3),
+.BR pmiPutValueHandle (3),
+.BR pmiSetHostname (3),
+.BR pmiSetTimezone (3),
+.BR pmiUseContext (3)
+and
+.BR pmiWrite (3).
diff --git a/man/man3/pmiunits.3 b/man/man3/pmiunits.3
new file mode 100644
index 0000000..b58fbea
--- /dev/null
+++ b/man/man3/pmiunits.3
@@ -0,0 +1,92 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2012 Red Hat.
+.\" Copyright (c) 2010 Ken McDonell.  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 PMIUNITS 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmiUnits\f1,
+\f3pmiID\f1,
+\f3pmiInDom\f1 \- construct core metric data structures
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/import.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+pmID
+pmiID(int \fIdomain\fP, int \fIcluster\fP, int \fIitem\fP);
+.ti -8n
+pmInDom
+pmiInDom(int \fIdomain\fP, int \fIserial\fP);
+.ti -8n
+pmUnits
+pmiUnits(int \fIdimSpace\fP, int \fIdimTime\fP, int \fIdimCount\fP, int\ \fIscaleSpace\fP, int\ \fIscaleTime\fP, int\ \fIscaleCount\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+$pmid = pmiID($\fIdomain\fP, $\fIcluster\fP, $\fIitem\fP);
+.ti -8n
+$indom = pmiInDom($\fIdomain\fP, $\fIserial\fP);
+.ti -8n
+$units = pmiUnits($\fIdimSpace\fP, $\fIdimTime\fP, $\fIdimCount\fP, $\fIscaleSpace\fP, $\fIscaleTime\fP, $\fIscaleCount\fP);
+.sp
+.in
+.hy
+.ad
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+these routines provide 
+convenience methods (especially for script use) for constructing
+.BR pmID ,
+.B pmInDom
+and
+.B pmUnits
+structures respectively, to be used in subsequent calls to
+.BR pmiAddMetric (3)
+and
+.BR pmiAddInstance (3).
+.PP
+Refer to
+.BR pmLookupDesc (3)
+for a complete description of the values and semantics of the
+components of a
+.B pmUnits
+structure, and hence the valid argument values for
+.BR pmiUnits .
+.SH DIAGNOSTICS
+None.
+.SH SEE ALSO
+.BR LOGIMPORT (3),
+.BR pmiAddMetric (3),
+.BR pmiAddInstance (3)
+and
+.BR pmLookupDesc (3).
diff --git a/man/man3/pmiusecontext.3 b/man/man3/pmiusecontext.3
new file mode 100644
index 0000000..b85c233
--- /dev/null
+++ b/man/man3/pmiusecontext.3
@@ -0,0 +1,62 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 PMIUSECONTEXT 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmiUseContext\f1 \- change LOGIMPORT context
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/import.h>
+.sp
+int pmiUseContext(int \fIcontext\fP);
+.sp
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.sp
+pmiUseContext($\fIcontext\fP);
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+.B pmiUseContext
+may be used by applications wishing to generate more than
+one PCP archive concurrently.
+.PP
+The
+.I context
+argument is a value returned from a previous call to
+.BR pmStart (3)
+and on successful return from
+.BR pmiUseContext ,
+the current context will have been changed to the one identified
+by
+.IR context .
+.SH DIAGNOSTICS
+.B pmiUseContext
+returns zero on success else a negative value that can be turned into an
+error message by calling
+.BR pmiErrStr (3).
+.SH SEE ALSO
+.BR LOGIMPORT (3),
+.BR pmiErrStr (3)
+and
+.BR pmiStart (3).
diff --git a/man/man3/pmiwrite.3 b/man/man3/pmiwrite.3
new file mode 100644
index 0000000..dac6ded
--- /dev/null
+++ b/man/man3/pmiwrite.3
@@ -0,0 +1,71 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2010 Ken McDonell.  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 PMIWRITE 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmiWrite\f1 \- flush data to a LOGIMPORT archive
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/import.h>
+.sp
+int pmiWrite(int \fIsec\fP, int \fIusec\fP);
+.sp
+cc ... \-lpcp_import \-lpcp
+.ft 1
+.SH "Perl SYNOPSIS"
+.ft 3
+use PCP::LogImport;
+.sp
+pmiWrite($\fIsec\fP, $\fIusec\fP);
+.ft 1
+.SH DESCRIPTION
+As part of the Performance Co-Pilot Log Import API (see
+.BR LOGIMPORT (3)),
+.B pmiWrite
+forces accumulated data values out to the PCP archive.
+.PP
+The data values and associated metadata have previously been
+built up using calls to
+.BR pmiAddMetric (3),
+.BR pmiAddInstance (3),
+.BR pmiPutValue (3)
+and
+.BR pmiPutValueHandle (3).
+.PP
+The current set of data values and any new metadata is written to the archive with
+a timestamp of
+.I sec
+and
+.I usec
+in the source timezone of the archive, see
+.BR pmiSetTimezone (3).
+.SH DIAGNOSTICS
+.B pmiWrite
+returns zero on success else a negative value that can be turned into an
+error message by calling
+.BR pmiErrStr (3).
+.SH SEE ALSO
+.BR LOGIMPORT (3),
+.BR pmiAddInstance (3),
+.BR pmiAddMetric (3),
+.BR pmiErrStr (3),
+.BR pmiPutValue (3),
+.BR pmiPutValueHandle (3)
+and
+.BR pmiSetTimezone (3).
diff --git a/man/man3/pmloadasciinamespace.3 b/man/man3/pmloadasciinamespace.3
new file mode 100644
index 0000000..a2778ed
--- /dev/null
+++ b/man/man3/pmloadasciinamespace.3
@@ -0,0 +1,117 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMLOADASCIINAMESPACE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmLoadASCIINameSpace\f1 \- establish a local PMNS for an application
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmLoadASCIINameSpace(const char *\fIfilename\fP, int \fIdupok\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+If the application wants to force using a local Performance Metrics
+Name Space (PMNS) instead
+of a distributed PMNS then it must load the PMNS using
+.B pmLoadASCIINameSpace
+or
+.BR pmLoadNameSpace (3).
+If the application wants to use a distributed PMNS, then it should NOT
+make a call to load the PMNS explicitly.
+.PP
+.B pmLoadASCIINameSpace
+is a variant of
+.BR pmLoadNameSpace (3)
+in which the
+.I dupok
+argument may be used to control the handling of multiple names
+in the PMNS that may be associated with a single Performance Metric
+Identifier (PMID).  A value of 0 disallows duplicates, any other value allows
+duplicates.
+.PP
+The
+.I filename
+argument designates the PMNS of interest.
+For applications not requiring a tailored PMNS,
+the special value
+.B PM_NS_DEFAULT
+may be 
+used for
+.IR filename ,
+to force the default local PMNS to be loaded.
+.PP
+The default local 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 local PMNS.
+.PP
+.B pmLoadASCIINameSpace
+returns zero on success.
+.SH FILES
+.IP \f2$PCP_VAR_DIR/pmns/root\f1 2.5i
+the default local PMNS, when the environment variable
+.B PMNS_DEFAULT
+is unset
+.RE
+.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).
+Values for these variables may be obtained programmatically
+using the
+.IR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetConfig (3),
+.BR pmLoadNameSpace (3),
+.BR pmTrimNameSpace (3),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR pmns (5).
+.SH DIAGNOSTICS
+Syntax and other errors in the parsing of the PMNS are reported
+on
+.I stderr
+with a message of the form ``Error Parsing ASCII PMNS: ...''.
+.PP
+.B PM_ERR_DUPPMNS
+.IP
+It is an error to try to load more than one PMNS, or to call
+either
+.B pmLoadASCIINameSpace
+and/or
+.BR pmLoadNameSpace (3)
+more than once.
+.PP
+.B PM_ERR_PMNS
+.IP
+Syntax error in an ASCII format PMNS.
diff --git a/man/man3/pmloadderivedconfig.3 b/man/man3/pmloadderivedconfig.3
new file mode 100644
index 0000000..062be54
--- /dev/null
+++ b/man/man3/pmloadderivedconfig.3
@@ -0,0 +1,68 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2009 Ken McDonell.  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 PMLOADDERIVEDCONFIG 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmLoadDerivedConfig\f1 \- load derived metric definitions from a file
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmLoadDerivedConfig(char *\fIfname\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.PP
+Each line of the file
+.I fname
+is either a comment line (with a ``#'' in the first position of the line)
+or the declaration of a derived performance metric, specified as:
+.IP * 2n
+the name of the derived metric, using the same ``dot notation'' syntax
+that is used for PCP performance metrics, see
+.BR PCPIntro (1)
+and
+.BR pmns (5).
+.IP * 2n
+an equals sign (``='')
+.IP * 2n
+a valid expression for a derived metric, as described in
+.BR pmRegisterDerived (3).
+.PP
+White space is ignored in the lines.
+.PP
+For each line containing a derived metric definition,
+.BR pmRegisterDerived (3)
+is called to register the new derived metric.
+.PP
+The result from
+.B pmLoadDerivedConfig
+will be the number of derived metrics loaded from
+.I fname
+else a value less than zero in the case of an error.
+.SH EXAMPLE
+.nf
+# sample derived metric definitions
+bad_in_pkts = network.interface.in.errors + network.interface.in.drops
+# note the following would need to be on a single line ...
+disk.dev.read_pct = 100 * delta(disk.dev.read) /
+            (delta(disk.dev.read) + delta(disk.dev.write))
+.fi
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR PMAPI (3)
+and
+.BR pmRegisterDerived (3).
diff --git a/man/man3/pmloadnamespace.3 b/man/man3/pmloadnamespace.3
new file mode 100644
index 0000000..3a3f853
--- /dev/null
+++ b/man/man3/pmloadnamespace.3
@@ -0,0 +1,119 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMLOADNAMESPACE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmLoadNameSpace\f1 \- load a local PMNS for an application
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmLoadNameSpace(const char *\fIfilename\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+If the application wants to force using a local Performance Metrics 
+Name Space (PMNS) instead of a distributed PMNS then it 
+must load the PMNS using
+.B pmLoadNameSpace
+or
+.BR pmLoadASCIINameSpace (3).
+If the application is to use a distributed PMNS, then it should NOT
+make a call to load the PMNS explicitly.
+.PP
+The
+.I filename
+argument designates the PMNS of interest.
+For applications not requiring a tailored PMNS,
+the special value
+.B PM_NS_DEFAULT
+may be 
+used for
+.IR filename ,
+to force the default local PMNS to be loaded.
+.PP
+The default local 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 local PMNS.
+.PP
+Externally a PMNS is stored in an ASCII format as
+described in
+.BR pmns (5).
+.PP
+By default,
+multiple names in the PMNS are not allowed to be
+associated with a single Performance
+Metrics Identifier (PMID).
+.BR pmLoadASCIINameSpace (3)
+provides an alternative interface with user-defined control
+over the processing of duplicate PMIDs in the PMNS.
+.PP
+.B pmLoadNameSpace
+returns zero on success.
+.SH FILES
+.IP \f2$PCP_VAR_DIR/pmns/root\f1 2.5i
+the default local PMNS, when the environment variable
+.B PMNS_DEFAULT
+is unset
+.RE
+.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).
+Values for these variables may be obtained programmatically
+using the
+.IR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetConfig (3),
+.BR pmLoadASCIINameSpace (3),
+.BR pmTrimNameSpace (3),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR pmns (5).
+.SH DIAGNOSTICS
+Syntax and other errors in the parsing of the PMNS are reported
+on
+.I stderr
+with a message of the form ``Error Parsing ASCII PMNS: ...''.
+.PP
+.B PM_ERR_DUPPMNS
+.IP
+It is an error to try and load more than one PMNS, or to call
+either
+.B pmLoadNameSpace
+and/or
+.BR pmLoadASCIINameSpace (3)
+more than once.
+.PP
+.B PM_ERR_PMNS
+.IP
+Syntax error in the PMNS file.
diff --git a/man/man3/pmlocalpmda.3 b/man/man3/pmlocalpmda.3
new file mode 100644
index 0000000..2fc3085
--- /dev/null
+++ b/man/man3/pmlocalpmda.3
@@ -0,0 +1,155 @@
+'\"macro stdmacro
+.TH PMLOCALPMDA 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3__pmLocalPMDA\f1 \- change the table of DSO PMDAs for PM_CONTEXT_LOCAL contexts
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int __pmLocalPMDA(int \fIop\fP, int \fIdomain\fP, const char *\fIname\fP, const\ char\ *\fIinit\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+PCP contexts of type
+.B PM_CONTEXT_LOCAL
+are used by clients that wish to fetch metrics directly from one or more PMDAs on
+the local host without involving
+.BR pmcd (1).
+A PMDA that is to be used in this way must have been built as a
+Dynamic Shared Object (DSO).
+.P
+Historically the table of PMDAs available for use with
+.B PM_CONTEXT_LOCAL
+was hardcoded to the following:
+.IP * 2n
+The PMDA (or PMDAs) that export the operating system performance data
+and data about process activity.
+.PD 0
+.IP *
+The
+.B mmv
+PMDA.
+.IP *
+The
+.B sample
+PMDA provided
+.B $PCP_LITE_SAMPLE
+or
+.B $PMDA_LOCAL_SAMPLE
+is set in the environment \- used mostly for QA and testing.
+.PD
+.PP
+The initial table of PMDAs available for use with
+.B PM_CONTEXT_LOCAL
+is now generated dynamically from all those PMDAs that have been
+installed as DSOs on the local host.
+The one exception is the ``pmcd''
+PMDA which only operates correctly in the address space of a running
+.BR pmcd (1)
+process and so is not available to an application using a
+.B PM_CONTEXT_LOCAL
+context.
+.PP
+.B __pmLocalPMDA
+provides a number of services to amend the table of PMDAs
+available for use with
+.BR PM_CONTEXT_LOCAL .
+.P
+The
+.I op
+argument specifies the what should be done and takes one of the following
+values and actions:
+.IP PM_LOCAL_ADD 16n
+Append an entry to the table for the PMDA with a Performance Metrics Domain
+(PMD) of
+.IR domain ,
+the path to the DSO PMDA is given by
+.I path
+and the PMDA's initialization routine is
+.IR init .
+.IP PM_LOCAL_DEL
+Removes all entries in the table where the
+.I domain
+matches, or the
+.I path
+matches.  Setting the arguments
+.I domain
+to \-1 or
+.I path
+to
+.B NULL
+to force matching on the
+.I other
+argument.
+The
+.I init
+argument is ignored.
+.IP PM_LOCAL_CLEAR
+Remove all entries from the table.  All the other arguments are ignored
+in this case.
+.P
+The
+.IR domain ,
+.I name
+and
+.I init
+arguments have similar syntax and semantics to the associated fields
+in the
+.BR pmcd (1)
+configuration file.
+The one difference is the
+.I path
+argument which is used by
+.B __pmLocalPMDA
+to find a likely looking DSO by searching in this order:
+.B $PCP_PMDAS_DIR\c
+/\c
+.IR path ,
+.IR path ,
+.B $PCP_PMDAS_DIR\c
+/\c
+.I path\c
+\&.\c
+.I dso-suffix
+and finally
+.I path\c
+\&.\c
+.I dso-suffix
+(\c
+.I dso-suffix
+is the local platform specific default file name suffix for a DSO, e.g.
+.B so
+for Linux,
+.B dylib
+for Mac OS X,
+.B dll
+for Windows,
+etc.).
+.SH "RETURN VALUE"
+In most cases,
+.B __pmLocalPMDA
+returns 0
+to indicate success.
+If
+.I op
+is invalid, then the return value is
+.B PM_ERR_CONV
+else if there is no matching table entry found for a
+.B PM_LOCAL_DEL
+operation, PM_ERR_INDOM is returned.
+.SH SEE ALSO
+.BR pmcd (1),
+.BR PMAPI (3),
+.BR pmNewContext (3)
+and
+.BR __pmSpecLocalPMDA (3).
diff --git a/man/man3/pmlocaltime.3 b/man/man3/pmlocaltime.3
new file mode 100644
index 0000000..3239592
--- /dev/null
+++ b/man/man3/pmlocaltime.3
@@ -0,0 +1,82 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMLOCALTIME 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmLocaltime\f1 \- convert the date and time for a reporting timezone
+.SH "C SYNOPSIS"
+.ft 3
+#include <time.h>
+.br
+#include <pcp/pmapi.h>
+.sp
+struct tm *pmLocaltime(const time_t *\fIclock\fP, struct tm *\fIresult\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmLocaltime
+is very similar to
+.BR localtime (3),
+except the timezone used is the current ``reporting timezone'' (rather than the
+default
+.B TZ
+environment variable scheme), and the result is returned into a
+caller-declared buffer (rather than a private buffer).
+.PP
+Like
+.BR localtime (3)
+the time to be converted is passed via
+.IR clock ,
+and 
+the
+.I result 
+contains the components broken out in the elements of the
+.I tm
+struct.
+.PP
+.B pmLocaltime
+returns
+.I result
+as the value of the function.
+.PP
+The default current reporting timezone is as defined by the
+.B TZ
+environment variable, so
+.B pmLocaltime
+and
+.BR localtime (3)
+will initially produce a similar encoding of the date and time.
+.PP
+Use
+.BR pmNewZone (3),
+.BR pmNewContextZone (3)
+or
+.BR pmUseZone (3)
+to establish a new current reporting timezone that will affect
+.B pmLocaltime
+but not
+.BR localtime (3).
+.SH SEE ALSO
+.BR localtime (3),
+.BR PMAPI (3),
+.BR pmCtime (3),
+.BR pmGetConfig (3),
+.BR pmNewContextZone (3),
+.BR pmNewZone (3),
+.BR pmUseZone (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
diff --git a/man/man3/pmlookupdesc.3 b/man/man3/pmlookupdesc.3
new file mode 100644
index 0000000..926ea07
--- /dev/null
+++ b/man/man3/pmlookupdesc.3
@@ -0,0 +1,239 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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.
+.\" 
+.\"
+.\" add in the -me strings for super and subscripts
+.ie n \{\
+.       ds [ \u\x'-0.25v'
+.       ds ] \d
+.       ds { \d\x'0.25v'
+.       ds } \u
+.\}
+.el \{\
+.       ds [ \v'-0.4m'\x'-0.2m'\s-3
+.       ds ] \s0\v'0.4m'
+.       ds { \v'0.4m'\x'0.2m'\s-3
+.       ds } \s0\v'-0.4m'
+.\}
+.TH PMLOOKUPDESC 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmLookupDesc\f1 \- obtain a description for a performance metric
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmLookupDesc(pmID \fIpmid\fP, pmDesc *\fIdesc\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Given a Performance Metrics Identifier (PMID) as
+.IR pmid ,
+fill in the given
+.CW pmDesc
+structure, pointed to by the parameter
+.IR desc ,
+from the current
+Performance Metrics Application Programming Interface (PMAPI)
+context.
+.PP
+The
+.CW pmDesc
+structure provides all of the information required to describe and
+manipulate a
+performance metric via the 
+PMAPI, and has the following declaration.
+.PP
+.ft CW
+.nf
+.in +0.5i
+/* Performance Metric Descriptor */
+typedef struct {
+    pmID    pmid;   /* unique identifier */
+    int     type;   /* base data type (see below) */
+    pmInDom indom;  /* instance domain */
+    int     sem;    /* semantics of value (see below) *
+    pmUnits units;  /* dimension and units (see below) */
+} pmDesc;
+
+/* pmDesc.type -- data type of metric values */
+#define PM_TYPE_NOSUPPORT        \-1    /* not impl. in this version */
+#define PM_TYPE_32               0    /* 32-bit signed integer */
+#define PM_TYPE_U32              1    /* 32-bit unsigned integer */
+#define PM_TYPE_64               2    /* 64-bit signed integer */
+#define PM_TYPE_U64              3    /* 64-bit unsigned integer */
+#define PM_TYPE_FLOAT            4    /* 32-bit floating point */
+#define PM_TYPE_DOUBLE           5    /* 64-bit floating point */
+#define PM_TYPE_STRING           6    /* array of char */
+#define PM_TYPE_AGGREGATE        7    /* arbitrary binary data */
+#define PM_TYPE_AGGREGATE_STATIC 8    /* static pointer to aggregate */
+#define PM_TYPE_EVENT            9    /* packed pmEventArray */
+#define PM_TYPE_UNKNOWN          255  /* used in pmValueBlock, not pmDesc */
+
+
+/* pmDesc.sem -- semantics/interpretation of metric values */
+#define PM_SEM_COUNTER  1  /* cumulative ctr (monotonic incr) */
+#define PM_SEM_INSTANT  3  /* instant. value continuous domain */
+#define PM_SEM_DISCRETE 4  /* instant. value discrete domain */
+.in
+.fi
+.ft 1
+.PP
+The
+.CW type
+field in the 
+.CW pmDesc
+describes various encodings (or formats) for a metric's value.
+.PP
+If a value is
+counted in the underlying base instrumentation with less than 32 bits of
+integer precision, it is the responsibility of the Performance Metrics
+Domain Agent (PMDA) to promote the value to a 32-bit integer before it is
+exported into the Performance Metrics Collection Subsystem (PMCS);
+i.e. applications above the PMAPI never have to deal with 8-bit and 16-bit
+counters.
+.PP
+If the value of a performance metric is of type
+.BR PM_TYPE_AGGREGATE ,
+.BR PM_TYPE_AGGREGATE_STATIC,
+.B PM_TYPE_EVENT
+or
+.BR PM_TYPE_STRING ,
+the interpretation of the value is unknown to the PMCS.
+In these cases, the
+application using the value, and the PMDA providing the value must have some
+common understanding about how the value is structured and interpreted.
+.PP
+Each
+value for a performance metric is assumed to be drawn from a set of values that
+can be described in terms of their dimensionality and scale by a compact
+encoding as follows.
+The dimensionality is defined by a power, or index, in
+each of 3 orthogonal dimensions, namely Space, Time and Count
+(or Events, which are dimensionless).
+For example I/O throughput might be represented as
+.ti 1i
+.CW "\0\0\0\0\0\0\0\0\0\0-1"
+.ti 1i
+.CW "Space.Time"
+.br
+while the
+running total of system calls is
+.CW "Count" ,
+memory allocation is
+.CW Space
+and average
+service time is
+.ti 1i
+.CW "\0\0\0\0\0\0\0\0\0\0-1"
+.ti 1i
+.CW "Time.Count"
+.br
+In each dimension there are a number
+of common scale values that may be used to better encode ranges that might
+otherwise exhaust the precision of a 32-bit value.
+This information is encoded
+in the
+.CW pmUnits
+structure which is embedded in the
+.CW pmDesc
+structure.
+.PP
+.ft CW
+.nf
+.in +0.5i
+/*
+ * Encoding for the units (dimensions Time and Space) and scale
+ * for Performance Metric Values
+ *
+ * For example, a pmUnits struct of
+ *      { 1, \-1, 0, PM_SPACE_MBYTE, PM_TIME_SEC, 0 }
+ * represents Mbytes/sec, while 
+ *      { 0, 1, \-1, 0, PM_TIME_HOUR, 6 }
+ * represents hours/million-events
+ */
+typedef struct {
+    int dimSpace:4;    /* space dimension */
+    int dimTime:4;     /* time dimension */
+    int dimCount:4;    /* event dimension */
+    int scaleSpace:4;  /* one of PM_SPACE_* below */
+    int scaleTime:4;   /* one of PM_TIME_* below */
+    int scaleCount:4;  /* one of PM_COUNT_* below */
+} pmUnits;             /* dimensional units and scale of value */
+
+/* pmUnits.scaleSpace */
+#define PM_SPACE_BYTE   0       /* bytes */
+#define PM_SPACE_KBYTE  1       /* Kilobytes (1024) */
+#define PM_SPACE_MBYTE  2       /* Megabytes (1024^2) */
+#define PM_SPACE_GBYTE  3       /* Gigabytes (1024^3) */
+#define PM_SPACE_TBYTE  4       /* Terabytes (1024^4) */
+/* pmUnits.scaleTime */
+#define PM_TIME_NSEC    0       /* nanoseconds */
+#define PM_TIME_USEC    1       /* microseconds */
+#define PM_TIME_MSEC    2       /* milliseconds */
+#define PM_TIME_SEC     3       /* seconds */
+#define PM_TIME_MIN     4       /* minutes */
+#define PM_TIME_HOUR    5       /* hours */
+/*
+ * pmUnits.scaleCount (e.g. count events, syscalls, interrupts,
+ * etc.) these are simply powers of 10, and not enumerated here,
+ * e.g. 6 for 10^6, or \-3 for 10^\-3
+ */
+#define PM_COUNT_ONE    0       /* 1 */
+.in
+.fi
+.ft 1
+.PP
+Special routines (e.g. \c
+.BR pmExtractValue (3),
+.BR pmConvScale (3))
+are provided to manipulate values in
+conjunction with the
+.CW pmUnits
+structure that defines the dimension and scale of the values for a particular
+performance metric.
+.PP
+Below the PMAPI, the information required to complete the 
+.CW pmDesc
+structure, is fetched from the PMDAs, and in this way the format
+and scale of performance metrics may change dynamically, as
+the PMDAs and their underlying
+instrumentation evolve with time.
+In particular, when some metrics suddenly
+become 64-bits long, or change their units from Mbytes to Gbytes,
+well-written applications
+using the services provided by the PMAPI will continue
+to function correctly.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmAtomStr (3),
+.BR pmConvScale (3),
+.BR pmExtractValue (3),
+.BR pmGetConfig (3),
+.BR pmTypesStr (3),
+.BR pmUnitsStr (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_PMID\f1
+The requested PMID is not known to the PMCS
+.IP \f3PM_ERR_NOAGENT\f1
+The PMDA responsible for providing the metric is currently not available
diff --git a/man/man3/pmlookupindom.3 b/man/man3/pmlookupindom.3
new file mode 100644
index 0000000..97a2137
--- /dev/null
+++ b/man/man3/pmlookupindom.3
@@ -0,0 +1,77 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMLOOKUPINDOM 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmLookupInDom\f1 \- translate an instance name into an instance identifier
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmLookupInDom(pmInDom \fIindom\fP, const char *\fIname\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+For the instance domain
+.IR indom ,
+in the current
+Performance Metrics Application Programming Interface (PMAPI)
+context,
+locate the instance with the external identification given by
+.IR name ,
+and return the internal instance identifier. 
+.PP
+Only the leading
+non-space characters of
+.I name
+will be used to identify the instance.
+.PP
+The value for the instance domain
+.I indom
+is typically extracted from a
+.CW pmDesc
+structure, following a call to
+.BR pmLookupDesc (3)
+for a particular performance metric.
+.PP
+.B pmLookupInDom
+will return a positive instance identifier on success.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetConfig (3),
+.BR pmGetInDom (3),
+.BR pmLookupDesc (3),
+.BR pmLookupInDomArchive (3),
+.BR pmNameInDom (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_INDOM\f1
+.I indom
+is not a valid instance domain identifier
+.IP \f3PM_ERR_INST\f1
+The external instance
+.I name
+is not known for the instance domain
+.I indom
+in the current PMAPI context
diff --git a/man/man3/pmlookupindomarchive.3 b/man/man3/pmlookupindomarchive.3
new file mode 100644
index 0000000..fa349dc
--- /dev/null
+++ b/man/man3/pmlookupindomarchive.3
@@ -0,0 +1,83 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMLOOKUPINDOMARCHIVE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmLookupInDomArchive\f1 \- translate an instance name into an instance identifier
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmLookupInDomArchive(pmInDom \fIindom\fP, const char *\fIname\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Provided the current
+Performance Metrics Application Programming Interface (PMAPI)
+context is associated with an archive log,
+.B pmLookupInDomArchive
+will scan the union of all the instance domain metadata
+for the instance domain
+.IR indom ,
+locate the first instance with the external identification given by
+.IR name ,
+and return the internal instance identifier. 
+.PP
+This routine is a specialized version of the more general PMAPI
+routine
+.BR pmLookupInDom .
+.PP
+Only the leading
+non-space characters of
+.I name
+will be used to identify the instance.
+.PP
+The value for the instance domain
+.I indom
+is typically extracted from a
+.CW pmDesc
+structure, following a call to
+.BR pmLookupDesc (3)
+for a particular performance metric.
+.PP
+.B pmLookupInDomArchive
+will return a positive instance identifier on success.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetConfig (3),
+.BR pmGetInDomArchive (3),
+.BR pmLookupDesc (3),
+.BR pmLookupInDom (3),
+.BR pmNameInDomArchive (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOTARCHIVE\f1
+the current PMAPI context is not associated with an archive log
+.IP \f3PM_ERR_INDOM_LOG\f1
+.I indom
+is not a defined instance domain identifier for the archive log
+.IP \f3PM_ERR_INST_LOG\f1
+the external instance
+.I name
+is not known for the instance domain
+.I indom
+in the archive log
diff --git a/man/man3/pmlookupindomtext.3 b/man/man3/pmlookupindomtext.3
new file mode 100644
index 0000000..d674e19
--- /dev/null
+++ b/man/man3/pmlookupindomtext.3
@@ -0,0 +1,83 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMLOOKUPINDOMTEXT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmLookupInDomText\f1 \- return text describing a performance metrics instance domain
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmLookupInDomText(pmInDom \fIindom\fP, int \fIlevel\fP, char **\fIbuffer\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Provided the source of metrics from
+the current
+Performance Metrics Application Programming Interface (PMAPI)
+context is a host,
+retrieve descriptive text about the performance
+metrics instance domain identified by
+.IR indom .
+.PP
+The value for the instance domain
+.I indom
+is typically extracted from a
+.CW pmDesc
+structure, following a call to
+.BR pmLookupDesc (3)
+for a particular performance metric.
+.PP
+The argument
+.I level
+should be 
+.BR PM_TEXT_ONELINE
+for a one-line summary, else
+.BR PM_TEXT_HELP
+for a more verbose description, suited to a help dialog. 
+.PP
+The space pointed to by
+.I buffer
+will have been allocated in
+.B pmLookupInDomText
+with
+.BR malloc (3C),
+and it is the responsibility of the caller to
+.BR free (3C)
+the space when it is no longer required.
+.PP
+.B pmLookupInDomText
+returns zero on success.
+.SH SEE ALSO
+.BR chkhelp (1),
+.BR newhelp (1),
+.BR PMAPI (3),
+.BR pmGetConfig (3),
+.BR pmLookupDesc (3),
+.BR pmLookupText (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOTHOST\f1
+if the current PMAPI context is an archive log
+(help and one-line text is not maintained in the archive logs)
diff --git a/man/man3/pmlookupipc.3 b/man/man3/pmlookupipc.3
new file mode 100644
index 0000000..b967470
--- /dev/null
+++ b/man/man3/pmlookupipc.3
@@ -0,0 +1,98 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMLOOKUPIPC 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3__pmAddIPC\f1,
+\f3__pmLookupIPC\f1,
+\f3__pmFdLookupIPC\f1,
+\f3__pmOverrideLastFd\f1,
+\f3__pmPrintIPC\f1,
+\f3__pmResetIPC\f1 \- IPC version infrastructure support
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+int __pmAddIPC(int \fIfd\fP, __pmIPC \fIipc\fP);
+.br
+int __pmLookupIPC(__pmIPC **\fIipcp\fP);
+.br
+int __pmFdLookupIPC(int \fIfd\fP, __pmIPC **\fIipcp\fP);
+.br
+void __pmOverrideLastFd(int \fIfd\fP);
+.br
+void __pmPrintIPC(void);
+.br
+void __pmResetIPC(int \fIfd\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+IPC channels throughout the distributed PCP framework are affected by the
+PCP 2.0 (and later) PDU changes.  These functions are the interface to the libpcp IPC
+connection management global data.  This data consists of a hash table of
+__pmIPC structures (indexed by file descriptor) and a cached, most-recently-used
+file descriptor.
+.PP
+Newly created IPC channels must be registered with the hash table using
+\f3__pmAddIPC\f1, such that the PDU sending and decoding routines can
+determine whether they need to perform any PDU version translations or not,
+for backward compatibility with previous the PCP 1.x IPC protocol.
+.PP
+.B __pmLookupIPC
+and
+.B __pmFdLookupIPC
+both provide handles to the __pmIPC structure associated with the given file
+descriptor, as previously established by a call to
+.BR __pmAddIPC .
+The difference between the two is that one allows an explicit file descriptor
+lookup, and the other uses the cached, most-recently-used file descriptor.
+So
+.B __pmLookupIPC
+actually calls
+.B __pmFdLookupIPC
+using this cached file descriptor as the argument.  The justification for having
+both is that in some places it is not possible to use
+.B __pmFdLookupIPC
+(which is preferred), since at that particular level of the PMAPI a file
+descriptor is not available (see the __pmDecodeError code for an example).
+.PP
+The
+.B __pmOverrideLastFd
+is an escape mechanism for use in those situations where the last PDU 
+fetch did not go through the usual channels (ie. __pmGetPDU), so as to ensure
+that the cached file descriptor is the correct file descriptor for the PDU
+which is currently being processed.  This will typically be used for archive
+PDU processing or where version information is not available for a given file
+descriptor (eg. immediately prior to a PDU version exchange).
+.PP
+.B __pmPrintIPC
+is a useful debugging routine for displaying a table mapping all currently
+registered file descriptors to their associated PDU version numbers.  Unused
+entries in this table should display the value zero in the version column.
+.PP
+.B __pmResetIPC
+resets the version information associated with the given file descriptor to some
+known (invalid) number.  Subsequent lookups on this file descriptor will return
+an UNKNOWN_VERSION embedded within the __pmIPC structure.
+.SH SEE ALSO
+.BR PMAPI (3)
+.SH DIAGNOSTICS
+A negative return value from \f3__pmLookupIPC\f1 indicates that the requested
+file descriptor is not registered in the hash table.
+This typically indicates closure of an IPC channel, so PM_ERR_IPC is returned
+if this is the case.
diff --git a/man/man3/pmlookupname.3 b/man/man3/pmlookupname.3
new file mode 100644
index 0000000..342c21e
--- /dev/null
+++ b/man/man3/pmlookupname.3
@@ -0,0 +1,93 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMLOOKUPNAME 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmLookupName\f1 \- translate performance metric names into PMIDs
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmLookupName(int \fInumpmid\fP, char **\fInamelist\fP, pmID *\fIpmidlist\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.PP
+Given a list in
+.I namelist
+containing
+.I numpmid
+full pathnames for performance metrics from a Performance Metrics Name
+Space (PMNS),
+.B pmLookupName
+returns the list of associated
+Performance Metric Identifiers (PMIDs) via 
+.IR pmidlist .
+.PP
+The result from
+.B pmLookupName
+will be the number of names translated in the absence of errors, else 
+an error code less than zero.
+When errors are encountered, the corresponding value in
+.I pmidlist 
+will be PM_ID_NULL.
+.PP
+Note that the error protocol guarantees there is a 1:1 relationship
+between the elements of
+.I namelist
+and
+.IR pmidlist ,
+hence both lists contain exactly
+.I numpmid
+elements.
+For this reason, the caller is expected to have pre-allocated a suitably
+sized array for
+.IR pmidlist .
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetChildren (3),
+.BR pmGetChildrenStatus (3),
+.BR pmGetConfig (3),
+.BR pmLoadNameSpace (3),
+.BR pmNameID (3),
+.BR pmNewContext (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_TOOSMALL\f1
+.I numpmid
+must be at least 1
+.IP \f3PM_ERR_NOPMNS\f1
+Failed to access a PMNS for operation.
+Note that if the application hasn't a priori called 
+.BR pmLoadNameSpace (3)
+and wants to use the distributed PMNS, then a call to
+.B pmLookupName
+must be made after the creation of a context (see 
+.BR pmNewContext (3)).
+.IP \f3PM_ERR_NAME\f1
+One or more of the elements of
+.I namelist
+does not correspond to a valid metric name in the PMNS.
+.IP \f3PM_ERR_NONLEAF\f1
+A name referred to a node in the PMNS but it was
+not a leaf node.
+.IP \f3PM_ERR_*\f1
+Other diagnostics are for protocol failures when
+accessing the distributed PMNS.
diff --git a/man/man3/pmlookuptext.3 b/man/man3/pmlookuptext.3
new file mode 100644
index 0000000..2115cfc
--- /dev/null
+++ b/man/man3/pmlookuptext.3
@@ -0,0 +1,71 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMLOOKUPTEXT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmLookupText\f1 \- return text describing a performance metric
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmLookupText(pmID \fIpmid\fP, int \fIlevel\fP, char **\fIbuffer\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+Provided the source of metrics from
+the current
+Performance Metrics Application Programming Interface (PMAPI)
+context is a host,
+retrieve descriptive text about the performance
+metric identified by
+.IR pmid .
+.PP
+The argument
+.I level
+should be 
+.BR PM_TEXT_ONELINE
+for a one-line summary, else
+.BR PM_TEXT_HELP
+for a more verbose description, suited to a help dialog. 
+.PP
+The space pointed to by
+.I buffer
+will have been allocated in
+.B pmLookupText
+with
+.BR malloc (3C),
+and it is the responsibility of the caller to
+.BR free (3C)
+the space when it is no longer required.
+.PP
+.B pmLookupText
+returns zero on success.
+.SH SEE ALSO
+.BR chkhelp (1),
+.BR newhelp (1),
+.BR PMAPI (3),
+.BR pmGetConfig (3),
+.BR pmLookupDesc (3),
+.BR pmLookupInDomText (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOTHOST\f1
+if the current PMAPI context is an archive log
+(help and one-line text is not maintained in the archive logs)
diff --git a/man/man3/pmmktime.3 b/man/man3/pmmktime.3
new file mode 100644
index 0000000..e9e6855
--- /dev/null
+++ b/man/man3/pmmktime.3
@@ -0,0 +1,74 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMMKTIME 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3__pmMktime\f1 \- convert a \fBtm\fR structure to a calendar time
+.SH "C SYNOPSIS"
+.ft 3
+#include <time.h>
+.br
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+time_t *__pmMktime(struct tm *\fItimeptr\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B __pmMktime
+is very similar to
+.BR mktime (3),
+except the timezone used is the current ``reporting timezone'' (rather than the
+default
+.B TZ
+environment variable scheme).
+.PP
+Like
+.BR mktime (3)
+the time to be converted is passed via
+.IR timeptr ,
+and 
+the function result 
+contains the calendar time (the number of seconds since 00:00:00 UTC,
+January 1, 1970).
+.PP
+The default current reporting timezone is as defined by the
+.B TZ
+environment variable, so
+.B __pmMktime
+and
+.BR mktime (3)
+will initially produce similar conversions.
+.PP
+Use
+.BR pmNewZone (3),
+.BR pmNewContextZone (3)
+or
+.BR pmUseZone (3)
+to establish a new current reporting timezone that will effect
+.B __pmMktime
+but not
+.BR mktime (3).
+.SH SEE ALSO
+.BR mktime (3),
+.BR PMAPI (3),
+.BR pmCtime (3),
+.BR pmLocaltime (3),
+.BR pmNewContextZone (3),
+.BR pmNewZone (3)
+and
+.BR pmUseZone (3).
diff --git a/man/man3/pmnameall.3 b/man/man3/pmnameall.3
new file mode 100644
index 0000000..aaeb0a3
--- /dev/null
+++ b/man/man3/pmnameall.3
@@ -0,0 +1,98 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMNAMEALL 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmNameAll\f1 \- translate a PMID to a set of performance metric names
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmNameAll(pmID \fIpmid\fP, char ***\fInameset\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Given a
+Performance Metric ID (PMID) via 
+.IR pmid ,
+.B pmNameAll
+will
+determine all the corresponding metric names, if any, in the 
+Performance Metrics Name Space (PMNS), and return these via
+.IR nameset .
+.PP
+The resulting list of pointers
+.I nameset
+.B and
+the values
+(the relative names) that the pointers reference will have been
+allocated by
+.B pmNameAll
+with a single call to
+.BR malloc (3C),
+and it is the
+responsibility of the
+.B pmNameAll
+caller to
+.CW free(nameset)
+to release the space
+when it is no longer required.
+.PP
+In the absence of errors,
+.B pmNameAll
+returns the number of names in
+.IR nameset .
+.PP
+For many examples of a PMNS, there will be a 1:1 mapping between
+a name and a PMID, and under these circumstances,
+.BR pmNameID (3)
+provides a slightly simpler interface in the absence of duplicate
+names for a particular PMID.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetChildren (3),
+.BR pmGetChildrenStatus (3),
+.BR pmGetConfig (3),
+.BR pmLoadASCIINameSpace (3),
+.BR pmLoadNameSpace (3),
+.BR pmLookupName (3),
+.BR pmNameID (3),
+.BR pmNewContext (3),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR pmns (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOPMNS\f1
+Failed to access a PMNS for operation.
+Note that if the application hasn't a priori called 
+.BR pmLoadNameSpace (3)
+and wants to use the distributed PMNS, then a call to
+.B pmNameAll
+must be made after the creation of a context (see 
+.BR pmNewContext (3)).
+.IP \f3PM_ERR_PMID\f1
+.I pmid
+does not correspond to a defined PMID in the PMNS.
+.IP \f3PM_ERR_*\f1
+Other diagnostics are for protocol failures when
+accessing the distributed PMNS.
diff --git a/man/man3/pmnameid.3 b/man/man3/pmnameid.3
new file mode 100644
index 0000000..e74cac3
--- /dev/null
+++ b/man/man3/pmnameid.3
@@ -0,0 +1,87 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMNAMEID 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmNameID\f1 \- translate a PMID to a performance metric name
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmNameID(pmID \fIpmid\fP, char **\fIname\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+Given a
+Performance Metric ID (PMID) via 
+.IR pmid ,
+.B pmNameID
+will
+determine the corresponding metric name, if any, in the 
+Performance Metrics Name Space (PMNS), and return this via
+.IR name .
+.PP
+If the PMNS contains multiple names associated with the requested
+PMID, one of these will be returned via
+.IR name ,
+but there is no way to determine which of the duplicate names
+this will be.  See
+.BR pmNameAll (3)
+if all of the corresponding names are required.
+.PP
+.I name
+is a null-byte terminated string, allocated by
+.B pmNameID
+using
+.BR malloc (3C)
+and it is the caller's responsibility to call
+.BR free (3C)
+to release the storage when the value is no longer required.
+.PP
+In the absence of errors,
+.B pmNameID
+returns zero.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetChildren (3),
+.BR pmGetChildrenStatus (3),
+.BR pmGetConfig (3),
+.BR pmLoadASCIINameSpace (3),
+.BR pmLoadNameSpace (3),
+.BR pmLookupName (3),
+.BR pmNameAll (3),
+.BR pmNewContext (3),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR pmns (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOPMNS\f1
+Failed to access a PMNS for operation.
+Note that if the application hasn't a priori called 
+.BR pmLoadNameSpace (3)
+and wants to use the distributed PMNS, then a call to
+.B pmNameId
+must be made after the creation of a context (see 
+.BR pmNewContext (3)).
+.IP \f3PM_ERR_PMID\f1
+.I pmid
+does not correspond to a defined PMID in the PMNS.
+.IP \f3PM_ERR_*\f1
+Other diagnostics are for protocol failures when
+accessing the distributed PMNS.
diff --git a/man/man3/pmnameindom.3 b/man/man3/pmnameindom.3
new file mode 100644
index 0000000..2e22134
--- /dev/null
+++ b/man/man3/pmnameindom.3
@@ -0,0 +1,83 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMNAMEINDOM 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmNameInDom\f1 \- translate an instance identifier into an instance name
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmNameInDom(pmInDom \fIindom\fP, int \fIinst\fP, char **\fIname\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+For the instance domain
+.IR indom ,
+in the current
+Performance Metrics Application Programming Interface (PMAPI)
+context,
+locate the instance with the internal instance identifier given
+by 
+.IR inst ,
+and return the full external instance identification via
+.IR name .
+.PP
+The value for the instance domain
+.I indom
+is typically extracted from a
+.CW pmDesc
+structure, following a call to
+.BR pmLookupDesc (3)
+for a particular performance metric.
+.PP
+The space for the value of
+.I name
+will have been allocated in
+.B pmNameInDom
+with
+.BR malloc (3C),
+and it is the responsibility of the caller to
+.BR free (3C)
+the space when it is no longer required.
+.PP
+.B pmNameInDom
+returns zero on success.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetConfig (3),
+.BR pmGetInDom (3),
+.BR pmLookupInDom (3),
+.BR pmNameInDomArchive (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_INDOM\f1
+.I indom
+is not a valid instance domain identifier
+.IP \f3PM_ERR_INST\f1
+The instance identifier
+.I inst
+is not known for the instance domain
+.I indom
+in the current PMAPI context
diff --git a/man/man3/pmnameindomarchive.3 b/man/man3/pmnameindomarchive.3
new file mode 100644
index 0000000..a9ff37e
--- /dev/null
+++ b/man/man3/pmnameindomarchive.3
@@ -0,0 +1,89 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMNAMEINDOMARCHIVE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmNameInDomArchive\f1 \- translate an instance identifier into an instance name
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmNameInDomArchive(pmInDom \fIindom\fP, int \fIinst\fP, char **\fIname\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Provided that the current
+Performance Metrics Application Programming Interface (PMAPI)
+context is associated with an archive log,
+.B pmNameInDomArchive
+will scan the union of all the instance domain metadata
+for the instance domain
+.IR indom ,
+locate the first instance with the internal instance identifier given
+by 
+.IR inst ,
+and return the full external instance identification via
+.IR name .
+.PP
+This routine is a specialized version of the more general PMAPI
+routine
+.BR pmNameInDom .
+.PP
+The value for the instance domain
+.I indom
+is typically extracted from a
+.CW pmDesc
+structure, following a call to
+.BR pmLookupDesc (3)
+for a particular performance metric.
+.PP
+The space for the value of
+.I name
+will have been allocated in
+.B pmNameInDomArchive
+with
+.BR malloc (3C),
+and it is the responsibility of the caller to
+.BR free (3C)
+the space when it is no longer required.
+.PP
+.B pmNameInDomArchive
+returns zero on success.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetConfig (3),
+.BR pmGetInDomArchive (3),
+.BR pmLookupInDomArchive (3),
+.BR pmNameInDom (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOTARCHIVE\f1
+the current PMAPI context is not associated with an archive log
+.IP \f3PM_ERR_INDOM_LOG\f1
+.I indom
+is not a defined instance domain identifier for the archive log
+.IP \f3PM_ERR_INST_LOG\f1
+the instance identifier
+.I inst
+is not known for the instance domain
+.I indom
+in the archive log
diff --git a/man/man3/pmnewcontext.3 b/man/man3/pmnewcontext.3
new file mode 100644
index 0000000..2286c69
--- /dev/null
+++ b/man/man3/pmnewcontext.3
@@ -0,0 +1,282 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMNEWCONTEXT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmNewContext\f1 \- establish a new PMAPI context
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmNewContext(int \fItype\fP, const char *\fIname\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+An application using the
+Performance Metrics Application Programming Interface (PMAPI)
+may manipulate several concurrent contexts,
+each associated with a source of performance metrics, e.g. \c
+.BR pmcd (1)
+on some host, or an archive log of performance metrics as created by
+.BR pmlogger (1),
+or a standalone connection on the local host that does not involve
+.BR pmcd (1).
+.PP
+.BR pmNewContext
+may be used to establish a new context.
+The source of the metrics is identified by
+.IR name ,
+and may be either a host name (\c
+.I type
+is
+.BR PM_CONTEXT_HOST ),
+or the base name common to all of the physical files of an archive log (\c
+.I type
+is
+.BR PM_CONTEXT_ARCHIVE ).
+.PP
+For a
+.I type
+of
+.BR PM_CONTEXT_HOST ,
+in addition to identifying a host
+the
+.I name
+may also be used to encode additional optional information in the form of
+a
+.BR pmcd (1)
+port number, a
+.BR pmproxy (1)
+hostname and a proxy port number. For example the
+.I name
+\&"app23:14321,4321@firewall.example.com:11111"
+specifies
+a connection on port
+.I 14321
+(or port
+.I 4321
+if
+.I 14321
+is unavailable)
+to
+.BR pmcd (1)
+on the host
+.I app23
+via port
+.I 11111
+to
+.BR pmproxy (1)
+on the host
+.IR firewall.example.com .
+.PP
+For a
+.I type
+of
+.BR PM_CONTEXT_ARCHIVE ,
+.I name
+may also be the name of any of the physical files of an
+archive, e.g.
+.IB myarchive .meta
+(the metadata file) or
+.IB myarchive .index
+(the temporal index) or
+.IB myarchive .0
+(the first data volume of the archive)
+or
+.IB myarchive .0.bz2
+or
+.IB myarchive .0.bz
+(the first data volume compressed with
+.BR bzip2 (1))
+or
+.IB myarchive .0.gz
+or
+.IB myarchive .0.Z
+or
+.IB myarchive .0.z
+(the first data volume compressed with
+.BR gzip (1)),
+.IB myarchive .1
+or
+.IB myarchive .3.bz2
+or
+.IB myarchive .42.gz
+etc.
+.PP
+In the case where
+.I type
+is
+.BR PM_CONTEXT_LOCAL ,
+.I name
+is ignored, and the context uses a standalone connection to the
+PMDA methods used by
+.BR pmcd (1).
+When this type of context is used, the range of accessible performance
+metrics is constrained to those from the operating system, and optionally
+the ``proc'', ``sample'' and ``ib'' PMDAs.
+.PP
+In the case where \f2type\fP is \f3PM_CONTEXT_HOST\fP, additional flags can
+be added to the \f2type\fP to indicate if the connection to \f3pmcd\fP(1)
+should be encrypted (\f3PM_CTXFLAG_SECURE\fP), deferred (\f3PM_CTXFLAG_SHALLOW\fP)
+and if the file descriptor used to communicate with \f3pmcd\fP(1), should not be
+shared across contexts (\f3PM_CTXFLAG_EXCLUSIVE\fP).  These final two context
+flags are now deprecated and ignored.
+.PP
+The initial instance
+profile is set up to select all instances in all instance domains. 
+In the case of an archive,
+the initial collection time is also set to zero,
+so that an initial
+.BR pmFetch (3)
+will result in the earliest set of metrics 
+being returned from the archive. 
+.PP
+Once established, the association between a context and a source of metrics
+is fixed for the life of the context, however routines are provided to
+independently manipulate both the instance profile (see
+.BR pmAddProfile (3)
+and
+.BR pmDelProfile (3))
+and the collection time for archives (see
+.BR pmSetMode (3)).
+.PP
+.B pmNewContext
+returns a handle that may be used with subsequent calls to
+.BR pmUseContext (3).
+.PP
+The new context remains the current PMAPI context for all
+subsequent calls across the PMAPI,
+until another call to
+.BR pmNewContext (3)
+is made, or the context is explicitly changed with a call to
+.BR pmDupContext (3)
+or
+.BR pmUseContext (3),
+or destroyed using
+.BR pmDestroyContext (3).
+.PP
+When attempting to connect to a remote
+.BR pmcd (1)
+on a machine that is booting,
+.B pmNewContext
+could potentially block for a long time until the remote machine
+finishes its initialization.
+.B pmNewContext
+will abort and return an error if the connection has not been established after
+some specified interval has elapsed.  The default interval is 5
+seconds.  This may be modified by setting
+.B PMCD_CONNECT_TIMEOUT
+in the environment to a real number of seconds for the
+desired timeout.
+This is most useful in cases where the remote host is at
+the end of a slow network, requiring longer latencies to
+establish the connection correctly.
+.SH ENVIRONMENT
+.TP
+.B PMCD_CONNECT_TIMEOUT
+Timeout period (in seconds) for
+.BR pmcd (1)
+connection attempts.
+.TP
+.B PMCD_PORT
+TCP/IP port(s) for connecting to
+.BR pmcd (1),
+historically was 4321 and more recently the officially registered port
+44321; in the current release,
+.B pmcd
+listens on both these ports as a transitional arrangement.  If used,
+should be set to a comma-separated list of numerical port numbers.
+.TP
+.B PMDA_PATH
+When searching for PMDAs to be loaded when
+.I type
+is
+.BR PM_CONTEXT_LOCAL ,
+the
+.B PMDA_PATH
+environment variable may be used to define a search path of
+directories to be used to locate the PMDA executables.
+The default search path is
+.BR $PCP_SHARE_DIR/lib:/usr/pcp/lib .
+.SH CAVEATS
+When using a
+.I type
+of
+.BR PM_CONTEXT_LOCAL ,
+the operating system PMDA may export data structures directly
+from the kernel, which means that the
+.B pmNewContext
+caller should be an
+executable program compiled for the same object code format
+as the booted kernel.
+.P
+In addition, applications using a
+.B PM_CONTEXT_LOCAL
+context
+must be single-threaded because the various DSO PMDAs may not be
+thread-safe.  This restriction is enforced at the
+.BR PMAPI (3),
+where routines may return the error code
+.B PM_ERR_THREAD
+if the library detects calls from more than one thread.
+.P
+Applications that use
+.BR gethostbyname (3N)
+should exercise caution because the static fields in
+.I "struct hostent"
+may not be preserved across some
+.BR PMAPI (3)
+calls.
+In particular,
+.BR pmNewContext (3)
+and
+.BR pmReconnectContext (3)
+both may call
+.BR gethostbyname (3N)
+internally.
+.SH SEE ALSO
+.BR pmcd (1),
+.BR pmproxy (1),
+.BR pmAddProfile (3),
+.BR PMAPI (3),
+.BR pmDelProfile (3),
+.BR pmDestroyContext (3),
+.BR pmDupContext (3),
+.BR pmGetConfig (3),
+.BR pmReconnectContext (3),
+.BR pmSetMode (3),
+.BR pmUseContext (3),
+.BR pmWhichContext (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+.P
+.B PM_ERR_PERMISSION
+.IP
+No permission to perform requested operation
+.P
+.B PM_ERR_CONNLIMIT
+.IP
+PMCD connection limit for this host exceeded
+.P
+.B PM_ERR_NOCONTEXT
+.IP
+Requested context type was not 
+.BR PM_CONTEXT_LOCAL , 
+.B PM_CONTEXT_HOST 
+or 
+.BR PM_CONTEXT_ARCHIVE .
diff --git a/man/man3/pmnewcontextzone.3 b/man/man3/pmnewcontextzone.3
new file mode 100644
index 0000000..f7e05f9
--- /dev/null
+++ b/man/man3/pmnewcontextzone.3
@@ -0,0 +1,80 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMNEWCONTEXTZONE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmNewContextZone\f1 \- establish a reporting timezone based on a PMAPI context
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmNewContextZone(void);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+The current reporting timezone affects the timezone used by
+.BR pmCtime (3)
+and
+.BR pmLocaltime (3).
+.PP
+If the current PMAPI context is an archive,
+.B pmNewContextZone
+uses the timezone from the archive label record to
+set the current reporting timezone.
+.PP
+If the current PMAPI context
+corresponds to a host source of metrics,
+.B pmNewContextZone
+executes a
+.BR pmFetch (3)
+to retrieve the value for the metric
+.CW pmcd.timezone
+and uses that to set the current reporting timezone.
+.PP
+In both cases,
+.B pmNewContextZone
+returns a value to identify the current reporting timezone
+that may be
+used in a subsequent call to
+.BR pmUseZone (3)
+to restore this reporting timezone.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmCtime (3),
+.BR pmFetch (3),
+.BR pmGetConfig (3),
+.BR pmLocaltime (3),
+.BR pmNewContext (3),
+.BR pmNewZone (3),
+.BR pmUseZone (3),
+.BR pmWhichZone (3),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR environ (5).
+.SH DIAGNOSTICS
+.TP
+.B PM_ERR_NOCONTEXT
+the current PMAPI context is not valid
+.TP
+other
+a return value less than zero indicates a fatal error from a system call,
+most likely
+.BR malloc (3C)
diff --git a/man/man3/pmnewzone.3 b/man/man3/pmnewzone.3
new file mode 100644
index 0000000..3f460c0
--- /dev/null
+++ b/man/man3/pmnewzone.3
@@ -0,0 +1,60 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000 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 PMNEWZONE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmNewZone\f1 \- establish a reporting timezone
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmNewZone(const char *\fItz\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+The current reporting timezone affects the timezone used by
+.BR pmCtime (3)
+and
+.BR pmLocaltime (3).
+.PP
+The argument
+.I tz
+defines a timezone string, in the format described for the
+.B TZ
+environment variable, see
+.BR environ (5).
+.PP
+.B pmNewZone
+sets the current reporting timezone, and returns a value that may be
+used in a subsequent call to
+.BR pmUseZone (3)
+to restore this reporting timezone.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmCtime (3),
+.BR pmGetConfig (3),
+.BR pmLocaltime (3),
+.BR pmNewContextZone (3),
+.BR pmUseZone (3),
+.BR pmWhichZone (3),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR environ (5).
+.SH DIAGNOSTICS
+A return value less than zero indicates a fatal error from a system call,
+most likely
+.BR malloc (3C).
diff --git a/man/man3/pmnumberstr.3 b/man/man3/pmnumberstr.3
new file mode 100644
index 0000000..d347461
--- /dev/null
+++ b/man/man3/pmnumberstr.3
@@ -0,0 +1,84 @@
+'\"! 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 PMNUMBERSTR 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmNumberStr\f1,
+\f3pmNumberStr_r\f1 \- fixed width output format for numbers
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+const char *pmNumberStr(double \fIvalue\fP);
+.br
+char *pmNumberStr_r(double \fIvalue\fP, char *\fIbuf\fP, int \fIbuflen\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmNumberStr
+returns the address of a 8-byte buffer that holds a
+null-byte terminated representation of
+.I value
+suitable for output with fixed width fields.
+The
+.B pmNumberStr_r
+function does the same, but stores the result in a user-supplied buffer
+.I buf
+of length
+.IR buflen ,
+which should have room for at least 8 bytes.
+.PP
+The value is scaled using multipliers in powers of ``one thousand''
+(the decimal ``kilo'') and has a bias that provides greater precision for
+positive numbers as opposed to negative numbers.
+.PP
+The format depends on the sign and magnitude of
+.I value
+as follows (\c
+\f(COd\f1
+represents a decimal digit):
+.TS
+box,center;
+c | c
+lf(CW) | lf(CO).
+\f2value\f1 range	format
+_
+        > 999995000000000	 \f(CBinf?\fP
+999995000000000 \- 999995000000	ddd.dd\f(CBT\fP
+   999995000000 \- 999995000	ddd.dd\f(CBG\fP
+      999995000 \- 999995	ddd.dd\f(CBM\fP
+         999995 \- 999.995	ddd.dd\f(CBK\fP
+        999.995 \- 0.005	ddd.dd
+          0.005 \- \-0.005	\f(CB  0.00\fP
+         \-0.005 \- \-99.95	\-dd.dd
+        \-99.995 \- \-99995	\-dd.dd\f(CBK\fP
+         \-99995 \- \-99995000	\-dd.dd\f(CBM\fP
+      \-99995000 \- \-99995000000	\-dd.dd\f(CBG\fP
+   \-99995000000 \- \-99995000000000	\-dd.dd\f(CBT\fP
+       < \-99995000000000	\f(CB\-inf?\fP
+.TE
+.PP
+At the boundary points of the ranges, the chosen format will retain the
+maximum number of significant digits.
+.SH NOTES
+.B pmNumberStr
+returns a pointer to a static buffer and hence is not thread-safe.
+Multi-threaded applications should use
+.B pmNumberStr_r
+instead.
+.SH SEE ALSO
+.BR printf (3)
diff --git a/man/man3/pmopenlog.3 b/man/man3/pmopenlog.3
new file mode 100644
index 0000000..dd0baff
--- /dev/null
+++ b/man/man3/pmopenlog.3
@@ -0,0 +1,80 @@
+'\"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 PMOPENLOG 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3__pmOpenLog\f1 \- create a log file for diagnostics and debug output
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+FILE *__pmOpenLog(const char *\fIprogname\fP, const char *\fIlogname\fP, FILE\ *\fIoldstream\fP, int\ *\fIstatus\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B __pmOpenLog
+reassigns the standard I/O stream
+.I oldstream
+to be associated with the file
+.IR logname .
+If it already exists,
+.I logname
+will be removed and recreated if possible (to ensure correct ownership
+and permissions from the caller to
+.BR __pmOpenLog ).
+.PP
+On return, the function value is the new standard I/O stream.  In the
+event of an error, this will be
+.I oldstream
+unchanged and
+.I status
+will be 0.
+.PP
+For success,
+.I status
+is 1, a standard preamble is written to
+.I logname
+.ti +0.5i
+.ft B
+Log for \fIprogname\fB on \fIhostname\fB started \fIdate and time\fB
+.ft R
+.br
+and an
+.BR atexit (3)
+handler is installed to write the postscript message to
+.I logname
+.ti +0.5i
+.ft B
+Log finished \fIdate and time\fB
+.ft R
+.br
+when the processes exits.
+.PP
+.I progname
+is only used to annotate messages.
+.SH SEE ALSO
+.BR atexit (3)
+and
+.BR freopen (3).
diff --git a/man/man3/pmparsectime.3 b/man/man3/pmparsectime.3
new file mode 100644
index 0000000..6ec29d5
--- /dev/null
+++ b/man/man3/pmparsectime.3
@@ -0,0 +1,71 @@
+'\"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 PMPARSECTIME 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3__pmParseCtime\f1 \- convert \fBctime\fR(3) string to \fBtm\fR structure
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+int __pmParseCtime(const char *\fIstring\fP, struct tm *\fIrslt\fP, char **\fIerrmsg\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B __pmParseCtime
+reverses the
+.BR asctime (3C)
+function.  It accepts a
+.B string
+specifying a time, and fills in the given
+.B tm
+structure.
+.PP
+Either a fully specified
+.BR asctime (3C)
+string like "Mon Mar  4 13:07:47 1996" or a partially specified time
+like '1996", "Mar 1996", "Mar 4 1996", "Mar", "13:07:47", "13:07",
+"Mar 4 13:07:47",... is accepted.  In addition, the seconds component
+may be a floating point number, for example "13:07:47.5".  The 12 hour
+clock is also supported, so "13:07" and "1:07 pm" are equivalent.
+.PP
+.B __pmParseCtime
+returns 0 if successful.  It returns \-1 and a dynamically allocated
+error message string in
+.BR errmsg ,
+if the given
+.B string
+does not parse.  Be sure to
+.BR free (3C)
+the error message string.
+.PP
+The
+.B tm
+structure returned in
+.B rslt
+should only be used as an argument to the
+.B __pmConvertTime
+function, as it contains encoded information that will only be
+correctly interpreted by
+.BR __pmConvertTime .
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmParseInterval (3),
+.BR __pmConvertTime (3)
+and
+.BR __pmParseTime (3).
diff --git a/man/man3/pmparsedebug.3 b/man/man3/pmparsedebug.3
new file mode 100644
index 0000000..54faac5
--- /dev/null
+++ b/man/man3/pmparsedebug.3
@@ -0,0 +1,68 @@
+'\"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 PMPARSEDEBUG 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3__pmParseDebug\f1 \- convert a list of debug flags into an integer
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+int __pmParseDebug(const char *\fIspec\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B __pmParseDebug
+parses
+.I spec
+assuming it to be a comma separated list of PCP debug flags.
+.PP
+Each flag may be specified as an integer or the
+trailing portion of the symbolic name of the corresponding flag as reported
+by
+.BR pmdbg (1).
+Symbolic names are stripped of the ``DBG_TRACE_'' prefix and may appear
+in either case.
+.PP
+As a special case, the values ``\-1'' and ``ALL'' are treated as synonyms
+for turning on all bits except the sign bit in the result, i.e. \c
+.B INT_MAX
+from
+.IR <limits.h> .
+.PP
+For example the debug flag
+.B DBG_TRACE_FETCH
+is defined in
+.I /usr/include/pcp/impl.h
+and may be specified in
+.I spec
+as
+.BR 2 ,
+.B FETCH
+or
+.BR fetch .
+.SH SEE ALSO
+.BR pmdbg (1)
+.SH DIAGNOSTICS
+If successful,
+.B __pmParseDebug
+returns the value computed by the bit-wise ``or'' of each flag in the
+.IR spec ,
+suitable for assigning to the global debug trace control variable
+.BR pmDebug .
+Otherwise the return value is less than 0 to indicate a parsing error.
diff --git a/man/man3/pmparsehostattrsspec.3 b/man/man3/pmparsehostattrsspec.3
new file mode 100644
index 0000000..60d87cb
--- /dev/null
+++ b/man/man3/pmparsehostattrsspec.3
@@ -0,0 +1,248 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2013 Red Hat.
+.\" 
+.\" 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 PMPARSEHOSTATTRSSPEC 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3__pmParseHostAttrsSpec\f1,
+\f3__pmUnparseHostAttrsSpec\f1,
+\f3__pmFreeHostAttrsSpec\f1,
+\f3__pmFreeAttrsSpec\f1 \- host and attributes specification parser
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int __pmParseHostAttrsSpec(const char *\fIstring\fP, pmHostSpec **\fIhostsp\fP, int\ *\fIcount\fP, __pmHashCtl\ *\fIattrs\fP, char\ **\fIerrmsg\fP);
+.br
+.ti -8n
+int __pmUnparseHostAttrsSpec(pmHostSpec *\fIhostsp\fP, int\ *\fIcount\fP, __pmHashCtl\ *\fIattrs\fP, char\ *\fIstring\fP, size_t \fIsize\fP);
+.br
+.ti -8n
+void __pmFreeHostAttrsSpec(pmHostSpec *\fIhosts\fP, int \fIcount\fP, __pmHashCtl\ *\fIattrs\fP);
+.br
+.ti -8n
+void __pmFreeAttrsSpec(__pmHashCtl\ *\fIattrs\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B __pmParseHostAttrsSpec
+accepts a
+.B string
+specifying the location of a PCP performance metric collector daemon,
+and any attributes that should be associated with the connection to that
+daemon.
+.PP
+The syntax allows the optional specification of a protocol (native PCP
+protocol, encrypted PCP protocol or unix domain socket protocol).
+.PP
+If the specified protocol is native PCP protocol, or encrypted PCP protocol,
+an initial
+.BR pmcd (1)
+hostname with optional port numbers and optional proxy host,
+and optional attributes which are to be associated with the connection may be specified.
+Some examples follow:
+.PP
+.in +0.5i
+.nf
+.ft CW
+pcp://nas1.servers.com:44321@firewalls.r.us?compress
+pcps://nas1.servers.com?user=otto&pass=blotto&compress
+.ft R
+.fi
+.in
+.PP
+If the specified protocol is a unix domain socket protocol, the path
+to the socket in the local file system may be specified along with
+optional attributes which are to be associated with the connection.
+For example:
+.PP
+.in +0.5i
+.nf
+.ft CW
+unix://$PCP_RUN_DIR/pmcd.socket:?compress
+local://my/local/pmcd.socket:?user=otto&pass=blotto&compress
+.ft R
+.fi
+.in
+.PP
+If the optional protocol component is not specified, then the default
+setting will be used - which is the native PCP binary protocol.
+However, this can still be overwritten via the environment as described
+in
+.BR PCPIntro (1).
+If the protocol prefix is specified, it must be one of either "pcp://"
+(clear), "pcps://" (secure, encrypted), "unix://" (authenticated local)
+or "local://" ("unix://" then "pcp://").
+.PP
+The path specified for the "unix://" and "local://" protocols will always be
+interpreted as an absolute path name. For example, the following are all
+interpreted identically as
+.IR $PCP_RUN_DIR/pmcd.socket .
+.PP
+.in +0.5i
+.nf
+.ft CW
+unix://$PCP_RUN_DIR/pmcd.socket
+unix:/$PCP_RUN_DIR/pmcd.socket
+unix:$PCP_RUN_DIR/pmcd.socket
+.ft R
+.fi
+.in
+.PP
+Refer to
+.BR __pmParseHostSpec (3)
+for further details of the host and proxy host components.
+.PP
+If any optional connection attributes are to be specified, these are
+separated from the hostname component via the '?' character.
+Each attribute is separated by the '&' character, and each can be
+either a simple attribute flag (such as "compress") or a name=value
+pair (such as "username=fred").
+.PP
+.B __pmParseHostAttrsSpec
+takes a null-terminated host-and-attributes specification
+.B string
+and returns an array of 
+.B pmHostSpec
+structures, where the array has
+.B count
+entries, and an
+.B attrs
+hash table containing any attributes (including the
+optional protocol, if it was specified).
+.PP
+Full details of the
+.B pmHostSpec
+structures are provided in
+.BR __pmParseHostSpec (3).
+.PP
+The
+.B __pmHashCtl
+structure that is filled out on return via
+.BR attributes ,
+represents each individual attribute in the specification
+.B string
+with any associated value.
+It should be considered an opaque structure and should be zeroed
+beforehand.
+.PP
+The returned hash table control structure can be iterated using
+one of the supplied iteration mechanisms \-
+.B __pmHashWalkCB
+(a callback-based mechanism)
+or
+.B __pmHashWalk
+(a simple procedural mechanism).
+These provide access to the individual hash nodes, as
+.B __pmHashNode
+entries, which provide access to decoded attributes and their
+(optional) values.
+.PP
+.nf
+.ft CW
+    typedef struct __pmHashNode {
+        __pmHashNode    *next;    /* next node in hash bucket (internal) */
+        unsigned int    key;      /* key identifying particular attribute */
+        void            *data;    /* attributes value (optional, string) */
+    } __pmHashNode;
+.fi
+.PP
+There are a set number of valid attributes, however these may be
+extended in future releases as new connection parameters become
+needed.
+These can be identified via the PCP_ATTR_* macros in the PCP header
+files.
+.PP
+.B __pmUnparseHostSpec
+performs the inverse operation, creating a
+.B string
+representation from
+.B hosts
+and
+.B attributes
+structures.
+The size of the supplied
+.B string
+buffer must be provided by the caller using the
+.B size
+parameter.
+.SH "RETURN VALUE"
+If the given
+.B string
+is successfully parsed
+.B __pmParseHostAttrsSpec
+returns zero.
+In this case the dynamic storage allocated by
+.B __pmParseHostAttrsSpec
+can be released by calling
+.B __pmFreeHostAttrsSpec
+using the addresses returned from
+.B __pmParseHostAttrsSpec
+.P
+Alternatively, the
+.B hosts
+and
+.B attributes
+memory can be freed separately, using
+.BR __pmFreeHostSpec (3)
+and
+.BR __pmFreeAttrsSpec .
+.P
+.B __pmParseHostAttrsSpec
+returns
+.B PM_ERR_GENERIC
+and a dynamically allocated error message string in
+.BR errmsg ,
+if the given
+.B string
+does not parse, and the user-supplied
+.B errmsg
+pointer is non-null.
+Be sure to
+.BR free (3C)
+the error message string in this situation.
+.PP
+In the case of an error, both
+.B hosts
+and
+.B attributes
+are undefined.
+In the case of success,
+.B errmsg
+is undefined.
+.PP
+On success
+.B __pmUnparseHostAttrsSpec
+returns a positive value indicating the number of characters written
+into the supplied buffer.
+However, if the supplied buffer was too small, a negative status code of
+.B \-E2BIG
+will be returned.
+.SH SEE ALSO
+.BR pmcd (1),
+.BR pmproxy (1),
+.BR pmchart (1),
+.BR __pmParseHostSpec (3),
+.BR PMAPI (3)
+and
+.BR pmNewContext (3).
diff --git a/man/man3/pmparsehostspec.3 b/man/man3/pmparsehostspec.3
new file mode 100644
index 0000000..f2351fd
--- /dev/null
+++ b/man/man3/pmparsehostspec.3
@@ -0,0 +1,168 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2013 Red Hat.
+.\" Copyright (c) 2007 Aconex, 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 PMPARSEHOSTSPEC 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3__pmParseHostSpec\f1,
+\f3__pmUnparseHostSpec\f1,
+\f3__pmFreeHostSpec\f1 \- uniform host specification parser
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int __pmParseHostSpec(const char *\fIstring\fP, pmHostSpec **\fIhostsp\fP, int\ *\fIcount\fP, char\ **\fIerrmsg\fP);
+.br
+.ti -8n
+int __pmUnparseHostSpec(pmHostSpec *\fIhosts\fP, int \fIcount\fP, char *\fIstring\fP, size_t \fIsize\fP);
+.br
+.ti -8n
+void __pmFreeHostSpec(pmHostSpec *\fIhosts\fP, int \fIcount\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B __pmParseHostSpec
+accepts a
+.B string
+specifying the location of a PCP performance metric collector daemon.
+The syntax of the various formats of this
+.B string
+is described in
+.BR PCPIntro (1)
+where several examples are also presented.
+.PP
+The syntax allows the initial
+.BR pmcd (1)
+hostname to be optionally followed by a list of port numbers,
+which will be tried in order when connecting to
+.B pmcd
+on that host.
+The portlist is separated from the hostname using a colon, and
+each port in the list is comma-separated.
+.PP
+In addition, one or more optional
+.BR pmproxy (1)
+hosts can be specified (currently, only one proxy host is supported
+by the PCP protocols).
+These are separated from each other and from the
+.B pmcd
+component using the @ character.
+These may also be followed by an optional port list, using the
+same comma-separated syntax as before.
+.PP
+.B __pmParseHostSpec
+takes a null-terminated host specification
+.B string
+and returns an array of 
+.B pmHostSpec
+structures, where the array has
+.B count
+entries.
+.PP
+These
+.B pmHostSpec
+structures that are returned via
+.B hostsp
+represent each individual host in the specification
+.B string
+and has the following
+declaration:
+.PP
+.nf
+.ft CW
+    typedef struct {
+        char    *name;       /* hostname (always valid) */
+        int     *ports;      /* array of host port numbers */
+        int     nports;      /* number of ports in host port array */
+    } pmHostSpec;
+.fi
+.PP
+.B __pmUnparseHostSpec
+performs the inverse operation, creating a
+.B string
+representation from a number of
+.B hosts
+structures.
+Where the
+.B count
+of structures indicated by
+.B hosts
+is greater than one, the proxy syntax is used to indicate a chain of
+proxied hosts.
+The size of the supplied
+.B string
+buffer must be provided by the caller using the
+.B size
+parameter.
+.SH "RETURN VALUE"
+If the given
+.B string
+is successfully parsed
+.B __pmParseHostSpec
+returns zero.
+In this case the dynamic storage allocated by
+.B __pmParseHostSpec
+can be released by calling
+.B __pmFreeHostSpec
+using the address returned from
+.B __pmParseHostSpec
+via
+.BR hosts .
+.P
+.B __pmParseHostSpec
+returns
+.B PM_ERR_GENERIC
+and a dynamically allocated error message string in
+.BR errmsg ,
+if the given
+.B string
+does not parse, and the user-supplied
+.B errmsg
+pointer is non-null.
+Be sure to
+.BR free (3C)
+the error message string in this situation.
+.PP
+In the case of an error,
+.B hosts
+is undefined.
+In the case of success,
+.B errmsg
+is undefined.
+.PP
+On success
+.B __pmUnparseHostSpec
+returns a positive value indicating the number of characters written
+into the supplied buffer.
+However, if the supplied buffer was too small, a negative status code of
+.B \-E2BIG
+is returned.
+.SH SEE ALSO
+.BR pmcd (1),
+.BR pmproxy (1),
+.BR pmchart (1),
+.BR __pmParseHostAttrsSpec (3),
+.BR PMAPI (3)
+and
+.BR pmNewContext (3).
diff --git a/man/man3/pmparseinterval.3 b/man/man3/pmparseinterval.3
new file mode 100644
index 0000000..cdf5009
--- /dev/null
+++ b/man/man3/pmparseinterval.3
@@ -0,0 +1,90 @@
+'\"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 PMPARSEINTERVAL 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmParseInterval\f1 \- convert interval string to \fBtimeval\fR structure
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmParseInterval(const char *\fIstring\fP, struct timeval *\fIrslt\fP, char\ **\fIerrmsg\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+.SH DESCRIPTION
+.B pmParseInterval
+parses the argument
+.I string
+specifying an interval of time and fills in the
+.B tv_sec
+and
+.B tv_usec
+components of the
+.I rslt
+structure to represent that interval.
+.PP
+The input
+.I string
+is most commonly the argument following a
+.BR \-t
+command line option to a PCP application, and
+the syntax is fully described in
+.BR PCPIntro (1).
+.PP
+.B pmParseInterval
+returns 0 and
+.I errmsg
+is undefined if the parsing is successful.
+.PP
+If the given
+.I string
+does not conform to the required syntax
+.B pmParseInterval
+returns \-1 and a dynamically allocated
+error message string in
+.IR errmsg .
+The error message
+is terminated with a newline and
+includes the text of the input
+.I string
+along with an indicator of the position at which the error was detected,
+e.g.
+.br
+.in +1i
+.CW "\&4minutes 30mumble"
+.br
+.CW "\&           ^ -- unexpected value"
+.in -1i
+.PP
+In the case of an error, the caller is responsible for calling
+.BR free (3C)
+to release the space allocated for
+.IR errmsg .
+.SH SEE ALSO
+.BR PMAPI (3)
+and
+.BR pmParseTimeWindow (3).
diff --git a/man/man3/pmparsemetricspec.3 b/man/man3/pmparsemetricspec.3
new file mode 100644
index 0000000..bec37fb
--- /dev/null
+++ b/man/man3/pmparsemetricspec.3
@@ -0,0 +1,115 @@
+'\"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 PMPARSEMETRICSPEC 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmParseMetricSpec\f1,
+\f3pmFreeMetricSpec\f1 \- uniform metric specification parser
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmParseMetricSpec(const char *\fIstring\fP, int \fIisarch\fP, char\ *\fIsource\fP, pmMetricSpec\ **\fIrsltp\fP, char\ **\fIerrmsg\fP);
+.br
+.ti -8n
+void pmFreeMetricSpec(pmMetricSpec *\fIrslt\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmParseMetricSpec
+accepts a
+.B string
+specifying the name of a PCP performance metric, and optionally
+the source (either a hostname or a PCP archive log filename)
+and instances for that metric.
+The syntax is described in
+.BR PCPIntro (1).
+.PP
+If neither \fBhost\fR nor \fBarchive\fR component
+of the metric specification is provided, the \fBisarch\fR
+and \fBsource\fR arguments are used to fill in the returned
+.B pmMetricSpec
+structure.
+.PP
+The
+.B pmMetricSpec
+structure that is returned via
+.B rsltp
+represents the parsed
+.B string
+and has the following
+declaration:
+.PP
+.nf
+.ft CW
+    typedef struct {
+        int     isarch;      /* source type: 0 -> live host, 1 -> archive, 2 -> local context */
+        char    *source;     /* name of source host or archive */
+        char    *metric;     /* name of metric */
+        int     ninst;       /* number of instances, 0 -> all */
+        char    *inst[1];    /* array of instance names */
+    } pmMetricSpec;
+.fi
+.PP
+.B pmParseMetricSpec
+returns 0 if the given
+.B string
+was successfully parsed.  In this case all the storage allocated by
+.B pmParseMetricSpec
+can be released by a single call to
+.BR free (3C)
+using the address returned from
+.B pmMetricSpec
+via
+.BR rsltp .
+The convenience macro
+.B pmFreeMetricSpec
+is a thinly disguised wrapper for
+.BR free (3C).
+.PP
+.B pmParseMetricSpec
+returns
+.B PM_ERR_GENERIC
+and a dynamically allocated error message string in
+.BR errmsg ,
+if the given
+.B string
+does not parse.  Be sure to
+.BR free (3C)
+the error message string in this situation.
+.PP
+In the case of an error,
+.B rsltp
+is undefined.
+In the case of success,
+.B errmsg
+is undefined.
+If
+.B "rsltp->ninst"
+is 0, then
+.B "rsltp->inst[0]"
+is undefined.
+.SH SEE ALSO
+.BR PMAPI (3)
+and
+.BR pmLookupName (3).
diff --git a/man/man3/pmparsetime.3 b/man/man3/pmparsetime.3
new file mode 100644
index 0000000..50bb598
--- /dev/null
+++ b/man/man3/pmparsetime.3
@@ -0,0 +1,94 @@
+'\"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 PMPARSETIME 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3__pmParseTime\f1 \- parse time point specification
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int __pmParseTime(const char *\fIstring\fP, struct timeval *\fIlogStart\fP, struct\ timeval\ *\fIlogEnd\fP, struct\ timeval\ *\fIrslt\fP, char\ **\fIerrMsg\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B __pmParseTime
+is designed to encapsulate the interpretation of a time point specification in
+command line switches for use by the PCP client tools. 
+.P
+This function expects to be called with the time point specification as
+.BR string .
+If the tool is running against PCP archive(s), you also
+need to supply the start time of the first (only) archive as
+.BR logStart ,
+and the end of the last (only) archive as
+.BR logEnd .
+See
+.BR pmGetArchiveLabel (3)
+and
+.BR pmGetArchiveEnd (3)
+for how to obtain values for these parameters.
+If the tool is running against a live feed of performance data,
+.B logStart
+should be the current time (but could be aligned on the next second
+for example), while
+.B logEnd
+should have its tv_sec component set to INT_MAX.
+.P
+The
+.B rslt
+structure must be allocated before calling
+.BR __pmParseTime .
+.P
+You also need to set the current PCP reporting time zone to correctly
+reflect the \-z and \-Z command line parameters before calling
+.BR __pmParseTime .
+See
+.BR pmUseZone (3)
+and friends for information on how this is done.
+.P
+If the conversion is successful,
+.B __pmParseTime
+returns 0, and fills in
+.B rslt
+with the time value defined by the input
+parameters.  If the argument strings could not be parsed, it returns \-1
+and a dynamically allocated error message string in
+.BR errMsg .
+Be sure to
+.BR free (3C)
+this error message string.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetArchiveEnd (3),
+.BR pmGetArchiveLabel (3),
+.BR pmNewContextZone (3),
+.BR pmNewZone (3),
+.BR pmParseInterval (3),
+.BR pmParseTimeWindow (3),
+.BR pmUseZone (3),
+.BR __pmConvertTime (3)
+and
+.BR __pmParseCtime (3).
diff --git a/man/man3/pmparsetimewindow.3 b/man/man3/pmparsetimewindow.3
new file mode 100644
index 0000000..3b8579e
--- /dev/null
+++ b/man/man3/pmparsetimewindow.3
@@ -0,0 +1,170 @@
+'\"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 PMPARSETIMEWINDOW 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmParseTimeWindow\f1 \- parse time window command line arguments
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+int pmParseTimeWindow(const char *\fIswStart\fP, const\ char\ *\fIswEnd\fP, const\ char\ *\fIswAlign\fP, const\ char\ *\fIswOffset\fP, const\ struct\ timeval\ *\fIlogStart\fP, const\ struct\ timeval\ *\fIlogEnd\fP, struct\ timeval\ *\fIrsltStart\fP, struct\ timeval\ *\fIrsltEnd\fP, struct\ timeval\ *\fIrsltOffset\fP, char\ **\fIerrMsg\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.B pmParseTimeWindow
+is designed to encapsulate the interpretation of the 
+.BR \-S ,
+.BR \-T ,
+.B \-A
+and
+.B \-O
+command line options used by Performance Co-Pilot (PCP) applications
+to define a time window of interest.
+The time window is defined by a start time and an end time that constrains
+the time interval during which the PCP application will retrieve and
+display performance metrics.  In the absence of the
+.B \-O
+and
+.B \-A
+options to specify an initial sample time origin
+and time alignment (see below), the PCP application
+will retrieve the first sample at the start of the time window.
+.P
+The syntax and meaning of the various argument formats for these options
+is described in
+.BR PCPIntro (1).
+.SH USAGE
+.B pmParseTimeWindow
+expects to be called with the argument of the
+.B \-S
+option as
+.BR swStart ,
+the argument of the
+.B \-T
+option as
+.BR swEnd ,
+the argument of the
+.B \-A
+option as
+.BR swAlign ,
+and the argument of the
+.B \-O
+option as
+.BR swOffset .
+Any or all of these parameters may be NULL
+to indicate that the corresponding command line option was not
+present.
+.P
+If the application is using a PCP archive log as the source
+of performance metrics, you also
+need to supply the time of the first archive log entry as
+.BR logStart ,
+and the time of the last archive log entry as
+.BR logEnd .
+See
+.BR pmGetArchiveLabel (3)
+and
+.BR pmGetArchiveEnd (3)
+for how to obtain values for these times.
+.P
+If the application is manipulating multiple concurrent archive
+logs, then the caller must resolve how the default time window
+is to be defined (the union of the time intervals in all archive
+logs is a likely interpretation).
+.P
+If the application is using a live feed of performance data,
+.B logStart
+should be the current time (but could be aligned on the next second
+for example), while
+.B logEnd
+should have its
+.I tv_sec
+component set to
+.BR INT_MAX .
+.P
+The
+.BR rsltStart ,
+.B rsltEnd
+and
+.B rsltOffset
+structures must be allocated before calling
+.BR pmParseTimeWindow .
+.P
+You also need to set the current PCP reporting time zone to correctly
+reflect the
+.B \-z
+and
+.B \-Z
+command line parameters before calling
+.BR pmParseTimeWindow .
+See
+.BR pmUseZone (3)
+and friends for information on how this is done.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmGetArchiveEnd (3),
+.BR pmGetArchiveLabel (3),
+.BR pmNewContextZone (3),
+.BR pmNewZone (3),
+.BR pmParseInterval (3)
+and
+.BR pmUseZone (3).
+.SH DIAGNOSTICS
+If the conversion is successful,
+.B pmParseTimeWindow
+returns 1 and fills in
+.BR rsltStart ,
+.B rsltEnd
+and
+.B rsltOffset
+with the start, end, and offset times for the time window defined by the input
+parameters.  
+The
+.B errMsg
+parameter is not changed when
+.BR pmParseTimeWindow
+returns 1.
+.P
+If the conversion is successful, but the requested alignment could not be
+performed (e.g. the PCP archive log is too short) the alignment is
+ignored,
+.BR rsltStart ,
+.B rsltEnd
+and
+.B rsltOffset
+are filled in and
+.BR pmParseTimeWindow
+returns 0.
+In this case,
+.B errMsg
+will point to a warning message in an internal static buffer.
+This buffer should not be freed.
+.P
+If the argument strings could not be parsed,
+.B pmParseTimeWindow
+returns \-1.
+In this case,
+.BR errMsg
+will point to an error message
+in a static internal buffer.
diff --git a/man/man3/pmprintf.3 b/man/man3/pmprintf.3
new file mode 100644
index 0000000..6e707f4
--- /dev/null
+++ b/man/man3/pmprintf.3
@@ -0,0 +1,104 @@
+'\"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 PMPRINTF 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmprintf\f1,
+\f3pmflush\f1 \- print formatted output in a window or to standard error
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmprintf(const char *\fIfmt\fP, ... /*\fIargs\fP*/);
+.br
+int pmflush(void);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+The combination of
+.B pmprintf
+and
+.B pmflush
+produces output in either an
+.BR xconfirm (1)
+window, on the standard error stream, or to a file in a manner similar to
+.BR fprintf (3).
+The \f2fmt\f1 argument is used to control the conversion, formatting, and
+printing of the variable length \f2args\f1 list.
+The output technique is controlled via an environment variable.
+.PP
+.B pmprintf
+appends the formatted message string to an internal buffer shared by the
+two routines, without actually producing any output.
+.PP
+.B pmflush
+causes the internal buffer to be either displayed in a window, printed
+on standard error, or flushed to a file and the internal buffer to be cleared.
+.PP
+.SH ENVIRONMENT
+The environment variable
+.BR PCP_STDERR
+controls the output technique used by \f3pmflush\f1:
+.RS +4n
+.PP
+If
+.B PCP_STDERR
+is unset, the text is written onto the
+.I stderr
+stream of the caller.
+.PP
+If 
+.B PCP_STDERR
+is set to the literal reserved word
+.B DISPLAY
+then the text will be displayed as a GUI dialog using
+.BR xconfirm (1).
+.PP
+If 
+.B PCP_STDERR
+is set to any other value then \f3pmflush\f1
+interprets the value as a file name and 
+appends the text to that file.  The file is created if it doesn't already
+exist, and in this case if the file creation fails, then
+.I stderr
+is used instead).
+.RE
+.SH FILES
+.B pmprintf
+uses the
+.BR mkstemp (3)
+function to create a temporary file.
+This temporary file is deleted when
+.B pmflush
+is called.
+.SH DIAGNOSTICS
+On successful completion, \f3pmprintf\f1 returns the number of characters
+transmitted, while
+.B pmflush
+returns a value of zero on successful completion.
+.PP
+For either routine, a negative value is returned if an error was encountered,
+and this can be passed to
+.BR pmErrStr (3)
+to obtain the associated error message.
+.PP
+.SH SEE ALSO
+.BR pmdbg (1),
+.BR fprintf (3),
+.BR mkstemp (3),
+.BR pmErrStr (3)
+and
+.BR PMAPI (3).
diff --git a/man/man3/pmprintvalue.3 b/man/man3/pmprintvalue.3
new file mode 100644
index 0000000..cf21db7
--- /dev/null
+++ b/man/man3/pmprintvalue.3
@@ -0,0 +1,92 @@
+'\"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 PMPRINTVALUE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmPrintValue\f1 \- print a performance metric value
+.SH "C SYNOPSIS"
+.ft 3
+#include <stdio.h>
+.br
+#include <pcp/pmapi.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+void pmPrintValue(FILE *\fIf\fP, int \fIvalfmt\fP, int \fItype\fP, const\ pmValue\ *\fIval\fP, int\ \fIminwidth\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+The value of a single performance metric (as identified by
+.IR val )
+is printed on the standard I/O stream identified by
+.IR f .
+.PP
+The value of the performance metric is interpreted according to the format of
+.I val
+as 
+defined by
+.I valfmt
+(from a
+.CW pmValueSet
+within a
+.CW pmResult
+structure; see
+.BR pmFetch (3))
+and the generic description of the metrics type
+passed in via
+.IR type .
+.PP
+The value for
+.I type
+is typically extracted from a
+.CW pmDesc
+structure, following a call to
+.BR pmLookupDesc (3)
+for a particular performance metric.
+.PP
+The output will be optionally padded to be at least
+.I minwidth
+characters wide.
+.PP
+.B pmPrintValue
+is most useful for displaying values of performance metrics from
+.BR pmFetch (3)
+(which returns a set of
+.I valfmt
+and
+.I val
+pairs for each requested metric), based upon the
+metrics type as returned from
+.BR pmLookupDesc (3).
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmAtomStr (3),
+.BR pmConvScale (3),
+.BR pmExtractValue (3),
+.BR pmFetch (3),
+.BR pmLookupDesc (3),
+.BR pmTypeStr (3)
+and
+.BR pmUnitsStr (3).
diff --git a/man/man3/pmreconnectcontext.3 b/man/man3/pmreconnectcontext.3
new file mode 100644
index 0000000..0b70948
--- /dev/null
+++ b/man/man3/pmreconnectcontext.3
@@ -0,0 +1,131 @@
+'\"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 PMRECONNECTCONTEXT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmReconnectContext\f1 \- reconnect to a PMAPI context
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmReconnectContext(int \fIhandle\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+As a consequence of network, host or
+Performance Metrics Collector Daemon (PMCD) failures, an applications
+connection to a PMCD may be established and then subsequently lost.
+.PP
+The routine
+.B pmReconnectContext
+allows an application to request that the context identified by 
+.I handle
+should be re-established, provided the associated PMCD is accessible.
+.PP
+To avoid flooding the system with reconnect requests,
+.B pmReconnectContext
+will only attempt a reconnection after a suitable delay from the previous
+unsuccessful attempt to reconnect this context. This imposed restriction on
+the reconnect re-try time interval uses an exponential back-off so that the 
+initial delay is 5 seconds after the first unsuccessful attempt, then 10
+seconds, then 20 seconds, then 40 seconds and then 80 seconds thereafter.
+.PP
+The environment variable
+.B PMCD_RECONNECT_TIMEOUT
+may be used to redefine the back-off intervals, see
+.BR PMAPI (3).
+.PP
+If the reconnection succeeds,
+.B pmReconnectContext
+returns
+.IR handle .
+.PP
+If
+.I handle
+identifies a context associated with an archive source of metrics,
+.B pmReconnectContext
+does nothing and returns
+.IR handle .
+.PP
+Calling
+.B pmReconnectContext
+with a handle identifying a currently connected context will cause the
+connection to be broken before any reconnection is attempted.
+.PP
+Note that even in the case of a successful reconnection,
+.B pmReconnectContext
+does not change the current
+Performance Metrics Application Programming Interface (PMAPI)
+context.
+.PP
+When attempting to connect to a remote
+.BR pmcd (1)
+on a machine that is booting,
+.B pmReconnectContext
+could potentially block for a long time until the remote machine
+finishes its initialization.
+.B pmReconnectContext
+will abort and return an error if the connection has not been established after
+some specified interval has elapsed.  The default interval is 5
+seconds.  This may be modified by setting
+.B PMCD_CONNECT_TIMEOUT
+in the environment to a real number of seconds for the
+desired timeout.
+This is most useful in cases where the remote host is at
+the end of a slow network, requiring longer latencies to
+establish the connection correctly.
+.SH ENVIRONMENT
+.TP
+.B PMCD_CONNECT_TIMEOUT
+Timeout period (in seconds) for
+.BR pmcd (1)
+connection attempts.
+.TP
+.B PMCD_RECONNECT_TIMEOUT
+Redefines the back-off intervals - refer to
+.BR PMAPI (3).
+.SH SEE ALSO
+.BR pmcd (1),
+.BR PMAPI (3),
+.BR pmNewContext (3)
+and
+.BR pmUseContext (3).
+.SH DIAGNOSTICS
+.P
+.B PM_ERR_NOCONTEXT
+.IP
+.I handle
+does not identify a valid PMAPI context
+.P
+.B \-ETIMEDOUT
+.IP
+The re-try time has not elapsed, or the reconnection is attempted and fails.
+.SH CAVEAT
+.P
+Applications that use
+.BR gethostbyname (3)
+should exercise caution because the static fields in
+.I "struct hostent"
+may not be preserved across some
+.BR PMAPI (3)
+calls.
+In particular,
+.BR pmNewContext (3)
+and
+.BR pmReconnectContext (3)
+both may call
+.BR gethostbyname (3)
+internally.
diff --git a/man/man3/pmregisterderived.3 b/man/man3/pmregisterderived.3
new file mode 100644
index 0000000..f500754
--- /dev/null
+++ b/man/man3/pmregisterderived.3
@@ -0,0 +1,421 @@
+'\"! tbl | mmdoc
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2009 Ken McDonell.  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 PMREGISTERDERIVED 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmRegisterDerived\f1 \- register a derived metric name and definition
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+char *pmRegisterDerived(char *\fIname\fP, char *\fIexpr\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.PP
+Derived metrics provide a way of extending the Performance Metrics
+Name Space (PMNS) with new metrics defined at the PCP client-side using
+arithmetic expressions over the existing performance metrics.
+.PP
+Typical uses would be to aggregate a number of similar metrics to provide
+a higher-level summary metric or to support the ``delta V over delta V''
+class of metrics that are not possible in the base data semantics of PCP.
+An example of the latter class would be the average I/O size, defined
+as
+.br
+.ce
+.ft CW
+delta(disk.dev.total_bytes) / delta(disk.dev.total)
+.ft R
+where both of the
+.ft CW
+disk.dev
+.ft R
+metrics are counters, and what is required
+is to to sample both metrics, compute the difference between the current
+and previous values and then calculate the ratio of these differences.
+.PP
+The arguments to
+.B pmRegisterDerived
+are the
+.I name
+of the new derived metric and
+.I expr
+is an arithmetic expression defining how the values of
+.I name
+should be computed.
+.PP
+.I name
+should follow the syntactic rules for the names of performance metrics,
+namely one or more components separated with a dot (``.''), and each
+component must begin with an alphabetic followed by zero or more characters
+drawn from the alphabetics, numerics and underscore (``_'').
+For more details, refer to
+.BR PCPIntro (1)
+and
+.BR pmns (5).
+.PP
+.I name
+must be unique across all derived metrics and should
+.B not
+match the
+name of any regular metric in the PMNS.  It is acceptable for
+.I name
+to share some part of its prefix with an existing subtree of the PMNS,
+e.g. the average I/O size metric above could be named
+.ft CW
+disk.dev.avgsz
+.ft R
+which would place it amongst the other
+.ft CW
+disk.dev
+.ft R
+metrics in the PMNS.
+Alternatively, derived metrics could populate their own subtree
+of the PMNS,
+e.g. the average I/O size metric above could be named
+.ft CW
+my.summary.disk.avgsz\c
+.ft R
+\&.
+.PP
+The expression
+.I expr
+follows these syntactic rules:
+.IP * 2n
+Terminal elements are either names of existing metrics or integer constants.
+Recursive definitions are not allowed, so only the names of regular
+metrics (not other derived metrics) may be used. Integer constants are
+constrained to the precision of 32-bit unsigned integers.
+.IP * 2n
+The usual binary arithmetic operators are supported, namely \- addition (``+''),
+subtraction (``-''), multiplication (``*'') and division (``/'') with
+the normal precedence rules where multiplication and division have
+higher precedence than addition and subtraction, so
+.ft CW
+a+b*c
+.ft R
+is evaluated as
+.ft CW
+a+(b*c)\c
+.ft R
+.
+.IP * 2n
+Parenthesis may be used for grouping.
+.IP * 2n
+The following unary functions operate on a single performance metric
+and return one or more values.
+For all functions (except
+.ft CW
+count()\c
+.ft R
+), the type of the operand metric must be arithmetic 
+(integer of various sizes and signedness, float or
+double).
+.TS
+box,center;
+cf(R) | cf(R)w(5i)
+lf(CW) | lf(R).
+Function	Value
+_
+avg(x)	T{
+.fi
+A singular instance being the average value across all instances for the metric x.
+T}
+_
+count(x)	T{
+.fi
+A singular instance being the count of the number of instances for the metric x.
+T}
+_
+delta(x)	T{
+.fi
+Returns the difference in values for the metric x between
+one call to
+.BR pmFetch (3)
+and the next. There is one value in the result
+for each instance that appears in both the current and the previous
+sample.
+T}
+_
+rate(x)	T{
+.fi
+Returns the difference in values for the metric x between
+one call to
+.BR pmFetch (3)
+and the next divided by the elapsed time between the calls to
+.BR pmFetch (3).
+The semantics of the derived metric are based on the semantics of the
+operand (x) with the dimension in the
+.B time
+domain decreased by one and scaling if required in the time utilization case
+where the operand is in units of time, and the derived metric is unitless.
+This mimics the rate conversion applied to counter metrics by tools
+such as
+.BR pmval (1),
+.BR pmie (1)
+and
+.BR pmchart (1).
+There is one value in the result
+for each instance that appears in both the current and the previous
+sample.
+T}
+_
+max(x)	T{
+.fi
+A singular instance being the maximum value across all instances for the metric x.
+T}
+_
+min(x)	T{
+.fi
+A singular instance being the minimum value across all instances for the metric x.
+T}
+_
+sum(x)	T{
+.fi
+A singular instance being the sum of the values across all instances for the metric x.
+T}
+.TE
+.IP * 2n
+White space is ignored.
+.PP
+Syntactic checking is performed at the time
+.B pmRegisterDerived
+is called, but semantic checking is deferred until each new context
+is created with
+.BR pmNewContext (3)
+or re-established with
+.BR pmReconnectContext (3),
+at which time the PMNS and metadata is available to
+allow semantic checking and the metadata of the derived metrics
+to be established.
+.SH "SEMANTIC CHECKS AND RULES"
+.PP
+There are a number of conversions required to determine the
+metadata for a derived metric and to ensure the semantics of
+the expressions are sound.
+.PP
+In a binary expression, if the semantics of both operands is not
+a counter (i.e. PM_SEM_INSTANT or PM_SEM_DISCRETE) then the result
+will have semantics PM_SEM_INSTANT unless both operands are
+PM_SEM_DISCRETE in which case the result is also PM_SEM_DISCRETE.
+.PP
+The mapping of the pmUnits of the metadata uses the following rules:
+.IP * 2n
+If both operands have a dimension of COUNT and the scales are not
+the same, use the larger scale and convert the values of the operand
+with the smaller scale.
+.IP * 2n
+If both operands have a dimension of TIME and the scales are not
+the same, use the larger scale and convert the values of the operand
+with the smaller scale.
+.IP * 2n
+If both operands have a dimension of SPACE and the scales are not
+the same, use the larger scale and convert the values of the operand
+with the smaller scale.
+.IP * 2n
+For addition and subtraction all dimensions for each of the operands
+and result are identical.
+.IP * 2n
+For multiplication, the dimensions of the result are the sum of the
+dimensions of the operands.
+.IP * 2n
+For division, the dimensions of the result are the difference of the
+dimensions of the operands.
+.PP
+Scale conversion involves division if the dimension is positive else
+multiplication if the dimension is negative. If scale conversion is
+applied to either of the operands, the result is promoted to type
+PM_TYPE_DOUBLE.
+.PP
+Putting all of this together in an example, consider the derived
+metric defined as follows:
+.br
+.ad c
+.ft CW
+x = network.interface.speed - delta(network.interface.in.bytes) / delta(sample.milliseconds)
+.ft R
+.br
+.ad l
+The type, dimension and scale settings would propagate up the expression
+tree as follows.
+.TS
+box,center;
+cf(R) | cf(R) | cf(R) | cf(R)
+lf(CW) | lf(CW) | lf(R) | lf(R).
+Expression	Type	T{
+.fi
+Dimension & Scale
+T}	T{
+.fi
+Scale Factor(s)
+T}
+_
+sample.milliseconds	DOUBLE	millisec
+delta(...)	DOUBLE	millisec
+network...bytes	U64	byte
+delta(...)	U64	byte
+delta(...) / delta(...)	DOUBLE	byte/millisec	T{
+.fi
+/1048576 and *1000
+T}
+network...speed	FLOAT	Mbyte/sec
+x	DOUBLE	Mbyte/sec
+.TE
+.PP
+Because semantic checking cannot be done at the time
+.B pmRegisterDerived
+is called, errors found during semantic checking are reported
+using
+.BR pmprintf (3).
+These include:
+.TP
+Error: derived metric <name1>: operand: <name2>: <reason>
+There was a problem calling
+.BR pmLookupName (3)
+to identify the operand metric <name2> used in the definition
+of the derived metric <name1>.
+.TP
+Error: derived metric <name1>: operand (<name2> [<pmid2>]): <reason>
+There was a problem calling
+.BR pmLookupDesc (3)
+to identify the operand metric <name2> with PMID <pmid2>
+used in the definition of the derived metric <name1>.
+.TP
+Semantic error: derived metric <name>: <operand> <op> <operand>: Illegal operator for counters
+If both operands have the semantics of counter, only addition or subtraction
+make sense, so multiplication and division are not allowed.
+.TP
+Semantic error: derived metric <name>: <operand> <op> <operand>: Illegal operator for counter and non-counter
+Only multiplication or division are allowed if the left operand has the
+semantics of a counter and the right operand is
+.B not
+a counter.
+.TP
+Semantic error: derived metric <name>: <operand> <op> <operand>: Illegal operator for non-counter and counter
+Only multiplication is allowed if the right operand has the
+semantics of a counter and the left operand is
+.B not
+a counter.
+.TP
+Semantic error: derived metric <name>: <operand> <op> <operand>: Non-arithmetic type for <left-or-right> operand
+The binary arithmetic operators are only allowed with operands with an
+arithmetic type (integer of various sizes and signedness, float or
+double).
+.TP
+Semantic error: derived metric <name>: <function>(<operand>): Non-arithmetic operand for function
+The unary functions are only defined if the operand has arithmetic type.
+.TP
+Semantic error: derived metric <name>: Incorrect time dimension for operand
+Rate conversion using the
+.BR rate ()
+function is only possible for operand metrics with a Time dimension of 0 or 1
+(see
+.BR pmLookupDesc (3)).
+If the operand metric's Time dimension is 0, then
+the derived metrics has a value "per second" (Time dimension of -1). 
+If the operand metric's Time dimension is 1, then
+the derived metrics has a value of time utilization (Time dimension of 0).
+.SH "EXPRESSION EVALUATION"
+For the binary arithmetic operators,
+if either operand must be scaled (e.g. convert bytes to Kbytes) then the
+result is promoted to PM_TYPE_DOUBLE.
+Otherwise the type of the result is determined
+by the types of the operands, as per the following table which is evaluated
+from top to bottom until a match is found.
+.TS
+box,center;
+cf(R) | cf(R) | cf(R)
+lf(R) | lf(R) | lf(R).
+Operand Types	Operator	Result Type
+_
+either is PM_TYPE_DOUBLE	any	PM_TYPE_DOUBLE
+_
+any	division	PM_TYPE_DOUBLE
+_
+either is PM_TYPE_FLOAT	any	PM_TYPE_FLOAT
+_
+either is PM_TYPE_U64	any	PM_TYPE_U64
+_
+either is PM_TYPE_64	any	PM_TYPE_64
+_
+either is PM_TYPE_U32	any	PM_TYPE_U32
+_
+T{
+.fi
+otherwise (both are PM_TYPE_32)
+T}	any	PM_TYPE_32
+.TE
+.SH CAVEATS
+.PP
+Unary negation is not supported, so the following expressions would be
+syntactically incorrect,
+.ft CW
+\-3*abc
+.ft R
+and
+.ft CW
+\-this.number\c
+.ft R
+.
+.PP
+Derived metrics are not available when using
+.BR pmFetchArchive (3)
+as this routine does not use a target list of PMIDs that could be
+remapped (as is done for
+.BR pmFetch (3)).
+.PP
+.B pmRegisterDerived
+does not apply retrospectively to any open contexts, so the normal
+use would be to make all calls to
+.B pmRegisterDerived
+(possibly via
+.BR pmLoadDerivedConfig (3))
+and then call
+.BR pmNewContext (3).
+.PP
+There is no
+.B pmUnregisterDerived
+method, so once registered a derived metric persists for the life
+of the application.
+.SH DIAGNOSTICS
+.PP
+On success,
+.B pmRegisterDerived
+returns NULL.
+.PP
+If a syntactic error is found at the time of registration, the
+value returned by
+.B pmRegisterDerived
+is a pointer into
+.I expr
+indicating
+.B where
+the error was found.  To identify
+.B what
+the error was, the application should call
+.BR pmDerivedErrStr (3)
+to retrieve the corresponding parser error message.
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR PMAPI (3),
+.BR pmDerivedErrStr (3),
+.BR pmFetch (3),
+.BR pmLoadDerivedConfig (3),
+.BR pmNewContext (3)
+and
+.BR pmReconnectContext (3).
diff --git a/man/man3/pmsetmode.3 b/man/man3/pmsetmode.3
new file mode 100644
index 0000000..7b47281
--- /dev/null
+++ b/man/man3/pmsetmode.3
@@ -0,0 +1,258 @@
+'\"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 PMSETMODE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmSetMode\f1 \- set collection time parameters for the current PMAPI context
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmSetMode(int \fImode\fP, const struct timeval *\fIwhen\fP, int \fIdelta\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+.B pmSetMode
+is used to define the collection time and/or mode for accessing
+performance metrics and meta-data in the current
+Performance Metrics Application Programming Interface (PMAPI)
+context.
+This mode affects the semantics of subsequent calls to the following
+PMAPI routines: 
+.BR pmFetch (3),
+.BR pmFetchArchive (3),
+.BR pmLookupDesc (3),
+.BR pmGetInDom (3),
+.BR pmLookupInDom (3)
+and
+.BR pmNameInDom (3).
+.PP
+If
+.I mode
+is
+.B PM_MODE_LIVE
+then all information is returned from the active pool of performance metrics
+as of the time that the PMAPI call is made, and the other two parameters to
+.B pmSetMode
+are ignored.
+.B PM_MODE_LIVE
+is the default mode when a new PMAPI context of type
+.B PM_CONTEXT_HOST
+is created.
+.PP
+If the
+.I mode
+is not
+.BR PM_MODE_LIVE ,
+then the
+.I when
+parameter defines a time origin, and all requests for meta-data (metric
+descriptions and instance identifiers from the instance domains) will be
+processed to reflect the state of the meta-data as of the time origin, i.e. we
+use the last state of this information at, or before, the time origin.
+.PP
+If the
+.I mode
+is
+.B PM_MODE_INTERP
+then, in the case of
+.BR pmFetch (3),
+the underlying code will use an interpolation scheme to compute the values of
+the metrics from the values recorded for times in the proximity of the time
+origin.
+A
+.I mode
+of
+.B PM_MODE_INTERP
+may only be used with an archive context.
+.PP
+If the
+.I mode
+is
+.B PM_MODE_FORW
+then, in the case of
+.BR pmFetch (3),
+the collection of recorded metric values will be scanned in a forwards
+direction in time, until values for at least one of the requested metrics is
+located after the time origin, and then all requested metrics stored in the log
+or archive at that time will be returned with the corresponding timestamp.
+A
+.I mode
+of
+.B PM_MODE_FORW
+may only be used with an archive context.
+.PP
+If the
+.I mode
+is
+.B PM_MODE_BACK
+then, the situation is the same as for
+.BR PM_MODE_FORW ,
+except a
+.BR pmFetch (3)
+will be serviced by scanning the collection of recorded metrics in a backwards
+direction in time for metrics before the time origin.
+A
+.I mode
+of
+.B PM_MODE_BACK
+may only be used with an archive context.
+.PP
+If the
+.I mode
+is
+.B PM_MODE_FORW
+or
+.BR PM_MODE_BACK ,
+and no qualifying metrics can be found in the requested direction of searching
+before the end or start of the archive
+log is found, then
+.BR pmFetch (3)
+returns the special error indicator,
+.BR PM_ERR_EOL .
+.PP
+For
+.IR mode s
+other than
+.BR PM_MODE_LIVE ,
+after each successful 
+.BR pmFetch (3),
+the time origin is reset to the timestamp returned via the
+.CW pmResult
+structure from
+.BR pmFetch (3).
+.PP
+The
+.B pmSetMode
+parameter
+.I delta
+defines an additional number of time units that should be used to adjust the
+time origin (forwards or backwards), after the new time origin from the
+.CW pmResult
+has been determined.
+This automatic adjustment of the time origin only occurs when the
+.I mode
+is
+.BR PM_MODE_INTERP ,
+and the adjustment is applied, even if the
+.BR pmFetch (3)
+fails because the time origin is outside the range defined by
+the records in an archive log, i.e. returns
+.BR PM_ERR_EOL .
+The high-order bits of the
+.I mode
+parameter is also used to optionally set the units of time for the
+.I delta
+field. To specify the units of time use
+.B PM_XTB_SET 
+macro with one of the values
+.BR PM_TIME_NSEC ,
+.BR PM_TIME_MSEC ,
+.BR PM_TIME_SEC ,
+etc.
+as follows:
+.P
+.in +0.5i
+PM_MODE_INTERP | PM_XTB_SET(PM_TIME_XXXX)
+.P
+If no units are specified the default is to interpret
+.I delta
+as milliseconds. 
+.PP
+Using these
+.I mode
+options, an application can implement replay, playback, fast forward, reverse,
+etc. for performance metric values held in the archive log by alternating calls
+to
+.B pmSetMode
+and
+.BR pmFetch (3).
+.PP
+As a special case, if
+.I when
+is
+.B NULL
+then the
+.I mode
+and
+.I delta
+arguments are used as described above, but the current time in the archive
+is not altered.
+.PP
+For example, the following code fragment may be used to dump just those values
+recorded in an archive in correct temporal sequence, for a selected set of
+performance metrics; this uses the default collection time mechanisms.
+.PP
+.ft CW
+.nf
+.in +0.5i
+pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
+while (pmFetch(npmid, pmidlist, &result) != PM_ERR_EOL) {
+    /*
+     * process real metric values as of result->timestamp
+     */
+    \&. . .
+    pmFreeResult(result);
+}
+.in
+.fi
+.ft 1
+.PP
+Alternatively, to replay interpolated metrics from the log in reverse
+chronological order, at 10 second intervals (of recorded time), the following
+code fragment could be used.
+.PP
+.ft CW
+.nf
+.in +0.5i
+struct timeval mytime;
+
+mytime.tv_sec = 0x7fffffff;
+pmSetMode(PM_MODE_BACK, &mytime, 0);
+pmFetchArchive(&result);
+mytime = result->timestamp;
+pmFreeResult(result);
+pmSetMode(PM_MODE_INTERP | PM_XTB_SET(PM_TIME_SEC), &mytime, \-10);
+
+while (pmFetch(numpmid, pmidlist, &result) != PM_ERR_EOL) {
+    /*
+     * process interpolated metric values as of
+     * result->timestamp
+     */
+    \&. . .
+    pmFreeResult(result);
+}
+.in
+.fi
+.ft 1
+.SH "SEE ALSO"
+.BR PMAPI (3),
+.BR pmFetch (3),
+.BR pmFetchArchive (3),
+.BR pmGetInDom (3),
+.BR pmLookupDesc (3),
+.BR pmLookupInDom (3)
+and
+.BR pmNameInDom (3).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_MODE\f1
+The
+.I mode
+parameter is invalid
diff --git a/man/man3/pmsortinstances.3 b/man/man3/pmsortinstances.3
new file mode 100644
index 0000000..bec71fd
--- /dev/null
+++ b/man/man3/pmsortinstances.3
@@ -0,0 +1,49 @@
+'\"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 PMSORTINSTANCES 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmSortInstances\f1 \- sort performance metric values on instance identifier
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+void pmSortInstances(pmResult *\fIresult\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+.PP
+The routine
+.B pmSortInstances
+may be used to guarantee that for each performance metric in the
+.I result
+from
+.BR pmFetch (3),
+the instances are in ascending instance identifier sequence.
+.PP
+This is most useful when trying to compute rates from two consecutive
+.BR pmFetch (3)
+results.
+.SH SEE ALSO
+.BR PMAPI (3)
+and
+.BR pmFetch (3).
+.SH DIAGNOSTICS
+None.
diff --git a/man/man3/pmspeclocalpmda.3 b/man/man3/pmspeclocalpmda.3
new file mode 100644
index 0000000..e5f82bb
--- /dev/null
+++ b/man/man3/pmspeclocalpmda.3
@@ -0,0 +1,118 @@
+'\"macro stdmacro
+.TH PMSPECLOCALPMDA 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3__pmSpecLocalPMDA\f1 \- process command-line argument for the table of DSO PMDAs
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.sp
+char *__pmSpecLocalPMDA(const char *\fIspec\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+PCP contexts of type
+.B PM_CONTEXT_LOCAL
+are used by clients that wish to fetch metrics directly from one or more PMDAs on
+the local host without involving
+.BR pmcd (1).
+.PP
+.B __pmSpecLocalPMDA
+provides a convenience wrapper to be used by applications that wish
+to use a command line argument (usually with
+.BR -K )
+to control the DSO PMDAs that are available for a
+.B PM_CONTEXT_LOCAL
+context.
+.PP
+The
+.I spec
+argument specifies actions for one or more DSO PMDAs using up to four fields separated by commas
+(``,''), namely:
+.PD 0
+.TP 3n
+.IP \-
+an opcode with one of the values
+.B add
+(add a new entry),
+.B del
+(delete an existing entry) or
+.B clear
+(clear all entries from the table).
+.IP \-
+the PMDA's domain number
+.IP \-
+the path to the PMDA DSO (may
+be absolute or relative to the $PCP_VAR_DIR/pmdas directory and
+the DSO suffix is optional), and
+.IP \-
+the
+name of the PMDA's initialization routine.
+.PD
+.PP
+All fields are required to add a new entry.  To delete an entry the opcode
+is required plus either or both of the domain number and path fields.
+To clear all entries, only the opcode is required.
+.PP
+If
+.I spec
+is parsed successfully, then
+.BR __pmLocalPMDA (3)
+is called with the extracted arguments.
+.SH "RETURN VALUE"
+On success,
+.B __pmSpecLocalPMDA
+will return NULL.
+.PP
+On error or failure,
+.B __pmSpecLocalPMDA
+will return a pointer to a static error message.
+.SH EXAMPLES
+Some examples of valid
+.I spec
+strings:
+.TP
+.ft CW
+clear
+.ft
+Delete all entries from the DSO table.
+.TP
+.ft CW
+add,123,foo/foo_pmda,foo_init
+.ft
+Add the ``foo'' PMDA using domain 123.
+The PMDA's DSO is most likely in below the directory
+.B $PCP_PMDAS_DIR
+and named
+.I foo/foo_pmda.so
+(for ELF-style platforms)
+or
+.I foo/foo_pmda.dylib
+(for BSD-style platforms)
+or
+.I foo\\foo_pmda.dll
+(for Windows-style platforms).
+The initialization routine for the ``foo'' PMDA is
+.IR foo_init ().
+.TP
+.ft CW
+del,123
+Delete the entry for the DSO with domain 123.
+.TP
+.ft CW
+del,,foo/foo_pmda
+Delete the entry with a pathname to the DSO that matches
+.IR foo/foo_pmda .
+.TP
+.ft CW
+del,123,foo/foo_pmda
+Delete the entry for the DSO with either domain 123
+and/or a pathname to the DSO that matches
+.IR foo/foo_pmda .
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR __pmLocalPMDA (3)
+and
+.BR pmNewContext (3).
diff --git a/man/man3/pmstore.3 b/man/man3/pmstore.3
new file mode 100644
index 0000000..6370385
--- /dev/null
+++ b/man/man3/pmstore.3
@@ -0,0 +1,104 @@
+'\"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 PMSTORE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmStore\f1 \- modify values of performance metrics
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmStore(const pmResult *\fIresult\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+In some special cases it may be helpful to modify the current values of
+performance metrics,
+e.g. to reset a counter to zero, or to modify a ``metric'' which is a control
+variable for some agent collecting performance metrics.
+.PP
+The routine
+.B pmStore
+is a lightweight inverse of
+.BR pmFetch (3).
+.PP
+The caller must build the
+.CW pmResult 
+data structure (of course, this could have been returned from an earlier
+.BR pmFetch (3)
+call) and then call
+.BR pmStore .
+.PP
+It is an error to pass a request to
+.B pmStore
+in which the
+.CW numval
+field within any of the
+.B pmValueSet
+structure has a value less than one.
+.PP
+The current
+Performance Metrics Application Programming Interface (PMAPI)
+context must be one with a host as the source of metrics, and the
+current value of the nominated metrics will be changed, i.e.
+.B pmStore
+cannot be used to make retrospective changes to information in either
+the archive logs, or in the recent past for real-time sources of metrics.
+.PP
+The return code from
+.B pmStore
+is zero for success.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmFetch (3)
+and
+.BR pmSetMode (3).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_GENERIC\f1
+At least one of the modifications was rejected.
+No other status is available
+from below the PMAPI (this is the lightweight part of the functionality!).  In
+cases where the outcome of
+.B pmStore
+for individual metrics is important, the caller should make one call to
+.B pmStore
+for each metric. On the other hand, a bulk modification can be performed in a
+single
+.B pmStore
+call for situations in which the outcome is not critical.
+.IP \f3PM_ERR_NOTHOST\f1
+The current PMAPI context is an archive rather than a host, or it
+is a host that is not set to the current time, i.e. has been ``rewound''
+to the recent past using
+.BR pmSetMode (3).
+.IP \f3PM_ERR_TOOSMALL\f1
+The number of metrics specified in
+.I result
+is less than one.
+.IP \f3PM_ERR_VALUE\f1
+One or more of the
+.CW pmValueSet s
+in
+.I result
+has a
+.CW numval
+field with a value less than one.
diff --git a/man/man3/pmtime.3 b/man/man3/pmtime.3
new file mode 100644
index 0000000..900ea16
--- /dev/null
+++ b/man/man3/pmtime.3
@@ -0,0 +1,181 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2009 Aconex.  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 PMTIME 3 "Aconex" "Performance Co-Pilot"
+.SH NAME
+\f3pmtime\f1,
+\f3pmTimeConnect\f1,
+\f3pmTimeDisconnect\f1,
+\f3pmTimeRecv\f1,
+\f3pmTimeSendAck\f1,
+\f3pmTimeShowDialog\f1 \-
+time control functions for synchronizing the archive position and
+update interval between one or more applications
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmtime.h>
+.sp
+int pmTimeConnect(int \fIport\fP, pmTime *\fIstate\fP);
+.br
+int pmTimeDisconnect(int \fIfd\fP);
+.br
+int pmTimeSendAck(int \fIfd\fP, struct timeval *\fIfetchTime\fP);
+.br
+int pmTimeShowDialog(int \fIfd\fP, int \fIshow\fP);
+.br
+int pmTimeRecv(int \fIfd\fP, pmTime *\fIstate\fP);
+.sp
+cc ... \-lpcp_gui
+.ft 1
+.SH DESCRIPTION
+These functions form part of the Performance Metrics Applications
+Programming Interface (PMAPI) and are intended to provide a uniform
+mechanism for applications to both replay archive data and report
+live data in a time synchronized manner.
+.PP
+The
+.I pmTime
+structure has the following fields:
+.sp 0.5v
+.ft CW
+.nf
+.in +0.25i
+typedef struct {
+    unsigned int        magic;
+    unsigned int        length;
+    pm_tctl_command     command;
+    pm_tctl_source      source;
+    pm_tctl_state       state;
+    pm_tctl_mode        mode;
+    struct timeval      delta;
+    struct timeval      position;
+    struct timeval      start;     /* archive only */
+    struct timeval      end;       /* archive only */
+    char                data[0];   /* arbitrary length info (TZ) */
+} pmTime;
+.in -0.25i
+.fi
+.ft R
+.PP
+In the simplest case, the application should call
+.B pmTimeConnect
+to connect to the time control server,
+.BR pmtime (1),
+and then repeatedly call
+.B pmTimeRecv
+in the main loop of the application.
+On success,
+.B pmTimeConnect
+returns a non-negative file descriptor.
+In applications which have multiple threads of control, rather than
+simply blocking in
+.BR pmTimeRecv ,
+the file descriptor may be used in calls to
+.BR select (2).
+In graphical applications, the file descriptor may be used to interface
+with the event loop.
+.PP
+The
+.I port
+parameter to
+.B pmTimeConnect
+is the port number of the socket on which the time control server is
+(or will be) listening for new connections.  
+.PP
+The state parameter to
+.B pmTimeConnect
+is used to initialize a new time control server or to pass additional
+information to an existing time control server.
+The
+.I start
+and
+.I finish
+fields indicate the chronological bounds interesting to the application.
+The
+.I showdialog
+field indicates whether the time control server should initially show
+or hide the dialog.
+The
+.IR position ,
+.IR delta,
+and
+.I data
+fields indicate the initial archive position, update interval,
+time zone string and time zone label string.
+.PP
+.B pmTimeRecv
+blocks until the time control server sends a command message.
+It then updates the state parameter and returns one of the PM_TCTL
+command identifiers.
+.PP
+The PM_TCTL_SET command indicates the application should seek to the
+archive position (see
+.BR pmSetMode (3))
+returned in the position field of the state parameter.
+.PP
+The PM_TCTL_STEP command indicates the application should perform an
+update, i.e. advance (or rewind, if delta is negative) to the time
+indicated by position and then fetch new metric values, update the
+display or whatever.  In order for several application to remain
+synchronized, the time control server will wait until all applications
+have acknowledged that they have completed the step command.
+Applications should call pmTimeSendAck when the step command has been
+processed.  Note that PM_TCTL_STEP is the only command that requires an
+explicit acknowledgement.
+.PP
+The PM_TCTL_VCRMODE command is used by the time control server to
+indicate the current VCR mode.
+.PP
+The value is returned in the vcrmode field of the state parameter passed
+to
+.BR pmTimeRecv ,
+and remains valid until the next PM_TCTL_VCRMODE command is received.
+.PP
+The PM_TCTL_TZ command indicates the application should use a new time-
+zone, as indicated in the
+.I tz
+and
+.I tzlabel
+fields of the state parameter.
+.PP
+The PM_TCTL_BOUNDS command is sent to all applications when the time
+control server changes its chronological bounds.
+This may occur when a new application connects to the time control
+server or the user changes the bounds manually.
+Most applications will ignore this command.
+.PP
+The PM_TCTL_SHOWDIALOG command will be sent to all applications when the
+visibility of the time control server changes.
+This allows applications to alter the text in menus or buttons to
+reflect this change.
+Applications may change the visibility of the time control dialog using
+the
+.B pmTimeShowDialog
+function.
+The initial visibility is determined when
+the time control dialog is first created by an application calling
+.B pmTimeConnect
+with the showdialog field in the state parameter set to the desired value.
+.PP
+The
+.B pmTimeDisconnect
+function may be used to close the command socket to the time control server.
+This is useful when applications need to change the connection mode,
+e.g. to divorce the current time control server and connect to a new one.
+.SH SEE ALSO
+.BR pmtime (1),
+.BR PMAPI (3)
+and
+.BR pmSetMode (3).
diff --git a/man/man3/pmtraversepmns.3 b/man/man3/pmtraversepmns.3
new file mode 100644
index 0000000..21ee276
--- /dev/null
+++ b/man/man3/pmtraversepmns.3
@@ -0,0 +1,110 @@
+'\"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 PMTRAVERSEPMNS 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmTraversePMNS\f1,
+\f3pmTraversePMNS_r\f1 \- traverse the performance metrics name space
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmTraversePMNS(const char *\fIname\fP, void (*\fIdometric\fP)(const char *));
+int pmTraversePMNS_r(const char *\fIname\fP, void (*\fIdometric_r\fP)(const char *, void *), void *\fIclosure\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+.PP
+The routine
+.B pmTraversePMNS
+may be used to perform a depth-first traversal of the Performance
+Metrics Name Space (PMNS).
+.PP
+The traversal starts at the node identified by
+.I name
+\- if
+.I name
+is an empty string (i.e. \f3""\f1), the traversal starts at the
+root of the PMNS.
+Usually
+.I name
+would be the pathname of a non-leaf node in the PMNS.
+.PP
+For each leaf node (i.e. performance metric) found in the traversal,
+the user-supplied routine
+.I dometric
+is called with the full pathname of that metric in the PMNS as
+the single argument.
+This argument is null-byte terminated, and is
+constructed from a buffer that is managed internally to
+.BR pmTraversePMNS .
+Consequently the value is only valid during the call to
+.I dometric
+\- if the pathname needs to be retained, it should be copied using
+.BR strdup (3C)
+before returning from
+.IR dometric .
+.PP
+The
+.B pmTraversePMNS_r
+routine performs the same function, except the callback method
+.I func_r
+has an additional parameter that will be
+.I closure
+from the initial call to
+.BR pmTraversePMNS_r .
+The additional parameter to
+.B pmTraversePMNS_r
+and the callback method allows the caller to pass context
+through
+.B pmTraversePMNS_r
+and into the callback method
+.IR func_r ,
+making the service more useful for multi-threaded applications
+where thread-private data can be accessed in the callback method
+via the
+.I closure
+argument.
+.PP
+On success
+.B pmTraversePMNS
+returns the number of children of
+.IR name ,
+which may be zero.
+.SH SEE ALSO
+.BR PMAPI (3)
+and
+.BR pmGetChildren (3).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOPMNS\f1
+Failed to access a PMNS for operation.
+Note that if the application hasn't a priori called pmLoadNameSpace(3)
+and wants to use the distributed PMNS, then a call to
+.B pmTraversePMNS
+must be made inside a current context.
+.IP \f3PM_ERR_NAME\f1
+The initial pathname
+.I name
+is not valid in the current PMNS.
+.IP \f3PM_ERR_*\f1
+Other diagnostics are for protocol failures when
+accessing the distributed PMNS.
diff --git a/man/man3/pmtrimnamespace.3 b/man/man3/pmtrimnamespace.3
new file mode 100644
index 0000000..01a743d
--- /dev/null
+++ b/man/man3/pmtrimnamespace.3
@@ -0,0 +1,100 @@
+'\"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 PMTRIMNAMESPACE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmTrimNameSpace\f1 \- prune a performance metrics name space
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmTrimNameSpace(void);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+If the current
+Performance Metrics Application Programming Interface (PMAPI)
+context
+corresponds to a version 1 archive log of Performance Co-Pilot (PCP)
+performance metrics (as collected
+by
+.BR pmlogger (1)
+.BR -V1 ),
+then the currently loaded
+Performance Metrics Name Space (PMNS), is trimmed to exclude
+metrics for which no description can
+be found in the archive.
+The PMNS is further trimmed to remove empty subtrees that do not contain any
+performance metric.
+.PP
+Since PCP archives usually contain some subset
+of all metrics named in the default PMNS,
+.B pmTrimNameSpace
+effectively trims the application's PMNS to contain only the
+names of the metrics in the archive.
+.PP
+Since PCP 2.0, 
+.B pmTrimNameSpace 
+is only needed for dealing with version 1 archives.
+Version 2 archives actually store the "trimmed" PMNS. 
+.PP
+Prior to any trimming,
+the PMNS is restored to the state as of the completion of the last
+.BR pmLoadASCIINameSpace (3)
+or
+.BR pmLoadNameSpace (3),
+so the effects of consecutive calls to
+.B pmTrimNameSpace
+with archive contexts are
+.B not
+additive.
+.PP
+If the current PMAPI context
+corresponds to a host
+and a
+.BR pmLoadASCIINameSpace (3) 
+or
+.BR pmLoadNameSpace (3) 
+call was made,
+then the PMNS reverts to all names loaded into the PMNS
+at the completion of the last
+.BR pmLoadASCIINameSpace (3)
+or
+.BR pmLoadNameSpace (3),
+i.e. any trimming is undone.
+.PP
+On success,
+.B pmTrimNameSpace
+returns zero.
+.SH SEE ALSO
+.BR pmlogger (1),
+.BR PMAPI (3),
+.BR pmLoadASCIINameSpace (3),
+.BR pmLoadNameSpace (3),
+.BR pmNewContext (3)
+and
+.BR pmns (5).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOPMNS\f1
+you must have loaded a PMNS using
+.BR pmLoadASCIINameSpace (3)
+or
+.BR pmLoadNameSpace (3)
+before calling
+.B pmTrimNameSpace
+.IP \f3PM_ERR_NOCONTEXT\f1
+the current PMAPI context
+is invalid
diff --git a/man/man3/pmtypestr.3 b/man/man3/pmtypestr.3
new file mode 100644
index 0000000..4d86d4b
--- /dev/null
+++ b/man/man3/pmtypestr.3
@@ -0,0 +1,93 @@
+'\"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 PMTYPESTR 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmTypeStr\f1,
+\f3pmTypeStr_r\f1 \- convert a performance metric type into a string
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+const char *pmTypeStr(int \fItype\fP);
+.br
+char *pmTypeStr_r(int \fItype\fP, char *\fIbuf\fP, int \fIbuflen\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Given a performance metric
+.IR type ,
+.B pmTypeStr
+produces a terse ASCII equivalent, appropriate for use in error and diagnostic
+messages.
+The
+.B pmTypeStr_r
+function does the same, but stores the result in a user-supplied buffer
+.I buf
+of length
+.IR buflen ,
+which should have room for at least 20 bytes.
+.PP
+The value for
+.I type
+is typically extracted from a
+.CW pmDesc
+structure, following a call to
+.BR pmLookupDesc (3)
+for a particular performance metric.
+.PP
+Examples are
+.B 32
+(for
+.I type
+equals
+.BR PM_TYPE_32 ),
+.B U64
+(for
+.I type
+equals
+.BR PM_TYPE_U64 ),
+.B AGGREGATE
+(for
+.I type
+equals
+.BR PM_TYPE_AGGREGATE ),
+etc.
+.PP
+The string value result for
+.B pmTypeStr
+is held in a single static buffer, so the returned value is
+only valid until the next call to
+.BR pmTypeStr .
+.SH NOTES
+.B pmTypeStr
+returns a pointer to a static buffer and hence is not thread-safe.
+Multi-threaded applications should use
+.B pmTypeStr_r
+instead.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmAtomStr (3),
+.BR pmConvScale (3),
+.BR pmExtractValue (3),
+.BR pmLookupDesc (3),
+.BR pmPrintValue (3)
+and
+.BR pmUnitsStr (3).
diff --git a/man/man3/pmunitsstr.3 b/man/man3/pmunitsstr.3
new file mode 100644
index 0000000..9a38bd1
--- /dev/null
+++ b/man/man3/pmunitsstr.3
@@ -0,0 +1,91 @@
+'\"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 PMUNITSSTR 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmUnitsStr\f1,
+\f3pmUnitsStr_r \- convert a performance metric's units into a string
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+const char *pmUnitsStr(const pmUnits *\fIpu\fP);
+.br
+char *pmUnitsStr_r(const pmUnits *\fIpu\fP, char *\fIbuf\fP, int \fIbuflen\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+The encoding of a performance metric's dimensionality and scale uses
+a
+.CW pmUnits
+structure; see
+.BR pmLookupDesc (3).
+.PP
+As an aid to labeling graphs and tables, or for error messages,
+.B pmUnitsStr
+will take a dimension and scale specification as per
+.IR pu ,
+and return the
+corresponding text string.
+The
+.B pmUnitsStr_r
+function does the same, but stores the result in a user-supplied buffer
+.I buf
+of length
+.IR buflen ,
+which should have room for at least 60 bytes.
+.PP
+For example
+.CW "{1, -2, 0, PM_SPACE_MBYTE, PM_TIME_SEC, 0}" , 
+as the value of
+.I *pu
+gives the result string
+.CW "Mbyte / sec^2" .
+.PP
+The string value result from
+.B pmUnitsStr
+is held in a single static buffer, so the returned value is
+only valid until the next call to
+.BR pmUnitsStr .
+.PP
+If the ``count'' dimension is non-zero, and the ``count'' scale is not
+zero, then the text string will
+include a decimal scaling factor, eg.
+.CW "count x 10^6" .
+.PP
+As a special case, if all components of the dimension are zero, then the
+``count'' scale is used to produce the text.  If this scale is zero the
+result is an empty string, otherwise the result is of the form
+.CW "x1 0^2" .
+.SH NOTES
+.B pmUnitsStr
+returns a pointer to a static buffer and hence is not thread-safe.
+Multi-threaded applications should use
+.B pmUnitsStr_r
+instead.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmAtomStr (3),
+.BR pmConvScale (3),
+.BR pmExtractValue (3),
+.BR pmLookupDesc (3),
+.BR pmPrintValue (3)
+and
+.BR pmTypeStr (3).
diff --git a/man/man3/pmunloadnamespace.3 b/man/man3/pmunloadnamespace.3
new file mode 100644
index 0000000..96af920
--- /dev/null
+++ b/man/man3/pmunloadnamespace.3
@@ -0,0 +1,48 @@
+'\"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 PMUNLOADNAMESPACE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmUnloadNameSpace\f1 \- unload a local performance metrics name space for an application
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+void pmUnloadNameSpace(void);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+If one has previously loaded a local Name Space using
+.BR pmLoadNameSpace (3)
+or
+.BR pmLoadASCIINameSpace (3),
+then calling
+.BR pmUnloadNameSpace (3)
+will free up the memory associated with the Name Space and force all
+subsequent PMNS routine calls to use the distributed PMNS.
+If
+.BR pmUnloadNameSpace (3)
+is called before calling
+.BR pmLoadNameSpace (3)
+or
+.BR pmLoadASCIINameSpace (3),
+then it will effectively do nothing.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmLoadASCIINameSpace (3),
+.BR pmLoadNameSpace (3)
+and
+.BR pmns (5).
diff --git a/man/man3/pmunpackeventrecords.3 b/man/man3/pmunpackeventrecords.3
new file mode 100644
index 0000000..6f581ad
--- /dev/null
+++ b/man/man3/pmunpackeventrecords.3
@@ -0,0 +1,165 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2014 Red Hat.
+.\" Copyright (c) 2010 Ken McDonell.  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 PMUNPACKEVENTRECORDS 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmUnpackEventRecords\f1 \- unpack event records
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmUnpackEventRecords(pmValueSet *\fIvsp\fP, int \fIidx\fP, pmResult ***\fIrap\fP);
+.sp
+int pmUnpackHighResEventRecords(pmValueSet *\fIvsp\fP, int \fIidx\fP, pmHighResResult ***\fIhrap\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Event records are encoded as a packed array of records within a
+.I pmResult
+using a container metric with a value of type
+.B PM_TYPE_EVENT ,
+and a
+.I pmHighResResult
+when using a metric of type
+.BR PM_TYPE_HIGHRES_EVENT .
+.PP
+.B pmUnpackEventRecords
+and
+.B pmUnpackHighResEventRecords
+may be used to unpack event records from a metric value
+identified by
+.I vsp
+and
+.IR idx .
+If the metric has a singular value,
+.I idx
+should be 0, else the ordinal instance value identified by
+.I idx
+will be unpacked, i.e. vsp->vlist[idx].
+The unpacked records are turned into either
+.I pmResult
+or
+.I pmHighResResult
+structures, one per event record and one metric per event parameter, and
+.I rap
+is returned as a pointer to an array (NULL pointer terminated) of
+pointers to the result structures.
+.PP
+The only difference between the two result types is the timestamp scale;
+the
+.I pmHighResResult
+allows for nanosecond precision, whereas
+.I pmResult
+allows for microsecond resolution.
+.PP
+Some control information from the packed event records is unpacked
+into additional ``anonymous'' metrics as follows:
+.TP 4n
+1.
+If the event record has a non-zero flags value, then the corresponding
+.IR pmResult / pmHighResResult
+will have the flags value encoded with the additional metric
+.B event.flags
+that is inserted ahead of all other event parameters.
+.TP 4n
+2.
+If the event record flag is set to
+.BR PM_EVENT_FLAG_MISSED ,
+then the corresponding
+.IR pmResult / pmHighResResult
+will have one metric
+.B event.missed
+with a value that equals the number of event records ``missed'' because
+either the PMDA could not keep up, or the PMAPI client did not collect
+the event records fast enough.
+.PP
+.B pmUnpackEventRecords
+returns the number of
+.I pmResult
+structures as the return value, which is >= 0 for success.
+Similarly,
+.B pmUnpackHighResEventRecords
+returns the number of
+.I pmHighResResult
+structures as the return value, which is >= 0 for success.
+.PP
+.I rap
+and the associated
+.I pmResult
+structures may be freed using the convenience function
+.BR pmFreeEventResult (3).
+.PP
+Similarly, the
+.I hrap
+and the associated
+.I pmHighResResult
+structures may be freed using the convenience function
+.BR pmFreeHighResEventResult .
+.SH "RETURN VALUE"
+The following errors are possible:
+.TP 10n
+PM_ERR_CONV
+The values associated with
+.I vsp
+are not encoded using the format PM_VAL_DPTR or PM_VAL_SPTR, or
+the flags at the head of the event record has an unexpected value.
+.TP 10n
+PM_ERR_INST
+The value associated with
+.I vsp
+is not singular as expected.
+.TP 10n
+PM_ERR_TYPE
+.I vsp
+is not a value of type
+.BR PM_TYPE_EVENT .
+.TP 10n
+PM_ERR_TOOSMALL
+The value identified by
+.I vbp
+is not legal because the value length is less than the minimum size,
+or the number of event records encoded in the (value header)
+.IR pmEventArray / pmEventHighResArray
+structure is negative, or the number of missed event records in the
+array is negative.
+.TP 10n
+PM_ERR_TOOBIG
+Either
+.B vsp
+indicates more than one value is present (all the event records
+are expected to be packed in a single metric value), or
+when unpacking the event records, the processing continues past the end of
+the enclosing value.  Indicates corruption of the packed event record.
+.TP 10n
+PM_ERR_TYPE
+Event parameters must have one of the arithmetic types, else
+.BR PM_TYPE_AGGREGATE ,
+.B PM_TYPE_STRING
+or
+.BR PM_TYPE_AGGREGATE_STATIC .
+.TP 10n
+other values < 0
+refer to
+.BR pmErrStr (3).
+.SH SEE ALSO
+.BR PMAPI (3)
+and
+.BR pmFreeEventResult (3).
diff --git a/man/man3/pmusecontext.3 b/man/man3/pmusecontext.3
new file mode 100644
index 0000000..5571b02
--- /dev/null
+++ b/man/man3/pmusecontext.3
@@ -0,0 +1,65 @@
+'\"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 PMUSECONTEXT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmUseContext\f1 \- change current PMAPI context
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmUseContext(int \fIhandle\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+An application using the
+Performance Metrics Application Programming Interface (PMAPI)
+may manipulate several concurrent contexts,
+each associated with a source of performance metrics, e.g. \c
+.BR pmcd (1)
+on some host, or an archive log of performance metrics as created by
+.BR pmlogger (1).
+.PP
+Calling
+.B pmUseContext
+causes the
+current PMAPI context to be set to
+the context identified by
+.IR handle .
+The value of
+.I handle
+must be one returned from an earlier call to
+.BR pmNewContext (3)
+or
+.BR pmDupContext (3).
+.PP
+Below the PMAPI, all contexts used by an application are saved in their most
+recently modified state, so
+.B pmUseContext
+restores the context to the state it was in the last time the context was
+used, not the state of the context when it was established.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmDestroyContext (3),
+.BR pmDupContext (3),
+.BR pmNewContext (3)
+and
+.BR pmWhichContext (3).
+.SH DIAGNOSTICS
+.B PM_ERR_NOCONTEXT
+.IP
+.I handle
+does not identify a valid PMAPI context
diff --git a/man/man3/pmusezone.3 b/man/man3/pmusezone.3
new file mode 100644
index 0000000..c5ef0b9
--- /dev/null
+++ b/man/man3/pmusezone.3
@@ -0,0 +1,53 @@
+'\"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 PMUSEZONE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmUseZone\f1 \- re-establish a reporting timezone
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmUseZone(const int \fItz_handle\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+The current reporting timezone effects the timezone used by
+.BR pmCtime (3)
+and
+.BR pmLocaltime (3).
+.PP
+The argument
+.I tz_handle
+identifies a reporting timezone as previously established by
+a call to
+.BR pmNewZone (3)
+or
+.BR pmNewContextZone (3),
+and this becomes
+the current reporting timezone.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmCtime (3),
+.BR pmLocaltime (3),
+.BR pmNewContextZone (3),
+.BR pmNewZone (3)
+and
+.BR pmWhichZone (3).
+.SH DIAGNOSTICS
+A return value less than zero indicates the value of
+.I tz_handle
+is not legal.
diff --git a/man/man3/pmwebapi.3 b/man/man3/pmwebapi.3
new file mode 100644
index 0000000..e4ad6f4
--- /dev/null
+++ b/man/man3/pmwebapi.3
@@ -0,0 +1,252 @@
+'\" t macro stdmacro
+.\"
+.\" Copyright (c) 2013-2014 Red Hat, 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 PMWEBAPI 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3PMWEBAPI\f1 \- introduction to the Performance Metrics Web Application Programming Interface
+
+.de SAMPLE
+.br
+.RS
+.nf
+.nh
+..
+.de ESAMPLE
+.hy
+.fi
+.RE
+..
+
+.SH OVERVIEW
+
+The PMWEBAPI interface is a binding of a subset of the PMAPI to the
+web.  It uses HTTP as transport, REST as organizational style for
+request/parameter encoding (the GET and POST methods are
+interchangeable), and JSON as response encoding.  A context identifier
+is used as a persistent way to refer to PMAPI contexts across related
+web requests.  These context identifiers expire after a configurable
+period of disuse.  Errors generally result in HTTP-level error responses.
+An
+.nh
+.B Access-Control-Allow-Origin: *
+.hy
+header is added to all JSON responses.
+
+.SH CONTEXT CREATION: pmNewContext
+
+To create a new web context identifier, a web client invokes:
+.TP
+.B /pmapi/context?local=ANYTHING
+Creates a PM_CONTEXT_LOCAL PMAPI context.
+.TP
+.B /pmapi/context?hostname=STRING
+.TP
+.B /pmapi/context?hostspec=STRING
+Creates a PM_CONTEXT_HOST PMAPI context with the given host name and/or extended
+specification.  If the host specification contains a userid/password combination,
+then the corresponding pmapi context operations will require HTTP Basic authentication
+credentials with matching userid/password.
+.TP
+.B /pmapi/context?archivefile=ARCHIVE
+Creates a PM_CONTEXT_ARCHIVE PMAPI context with the given file name.
+.PP
+In addition, the web client may add the parameter
+.B &polltimeout=MMMM
+for a maximum interval (in seconds) between expected accesses to the
+given context.  This value is limited by pmwebd configuration, and is
+a courtesy to allow pmwebd to free up memory earlier in case of sudden
+web application shutdown.
+
+If successful, the response from these requests is a JSON document of the form:
+
+.SAMPLE
+{ "context" : NNNNN }
+.ESAMPLE
+
+The number (a 32-bit unsigned decimal) is then used in all later operations.
+
+.SH PMAPI OPERATIONS
+
+The general form of the requests is as follows:
+.B /pmapi/NNNNN/OPERATION
+where
+.TP
+.B /pmapi
+is the fixed prefix for all PMWEBAPI operations,
+.TP
+.B NNNNN
+is a PMWEBAPI context number returned from a context-creation call, or
+assigned permanently at pmwebd startup, and
+.TP
+.B OPERATION?PARAM1=VALUE2&PARAM2=VALUE2
+identifies the operation and its URL-encoded parameters.  Some
+parameters may be optional.
+
+.SS METRIC METADATA: pmLookupName, pmLookupDesc, pmTraversePMNS_r
+
+The general form of the requests is as follows:
+.TP
+.B /pmapi/NNNNN/_metric
+Traverse the entire PMNS.
+.TP
+.B /pmapi/NNNNN/_metric?prefix=NAME
+Traverse the subtree of PMNS with the prefix NAME.
+.PP
+The response is a JSON document that provides the metric metadata
+as an array.  For example:
+
+.SAMPLE
+{ "metrics": [ 
+    { "name":"foo.bar", "pmID":PPPP, "indom":DDDD,
+      "type":"32", "sem":"instant", "units":"MHz",
+      "text-oneline":"foo bar", "text-help":"blah blah blah" },
+    { "name":"foo.bar2", ... }
+    ...
+  ] }
+.ESAMPLE
+
+Most of the fields are self-explanatory.
+.TP
+PPPP
+the PMID
+.TP
+DDDD
+the instance domain
+.TP
+type
+from pmTypeStr
+.TP
+units
+from pmUnitsStr
+.TP
+sem
+an abbreviation of the metric semantic:
+.TS
+l l.
+PM_SEM_COUNTER  "counter"
+PM_SEM_INSTANT  "instant"
+PM_SEM_DISCRETE "discrete"
+.TE
+
+.SS METRIC VALUE: pmFetch
+
+The general form of the requests is as follows:
+.TP
+.B /pmapi/NNNNN/_fetch?names=NAME1,NAME2
+Fetch current values for given named metrics.
+.TP
+.B /pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2
+Fetch current values for given PMIDs.
+.PP
+The response is a JSON document that provides the values for
+all requested metrics, for all their instances.
+
+.SAMPLE
+{ "timestamp": { "s":SEC, "us":USEC },
+  "values": [
+        { "pmid":PPPP1, "name":"NAME1",
+          "instances:" [
+               { "instance":IIII1, "value":VALUE1 }
+               { "instance":IIII2, "value":VALUE2 }
+               ...
+          ] },
+        { "pmid":PPPP2, "name":"NAME2", ... }
+        ...
+  ] }
+.ESAMPLE
+
+Most of the fields are self-explanatory.  Numeric metric types
+are represented as JSON integer or floating-point values.  Strings
+are passed verbatim, except that non-ASCII values are replaced
+with a Unicode 0xFFFD REPLACEMENT CHARACTER code.  Event type metrics
+are not currently supported.
+
+.SS INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom
+
+The general form of the requests is as follows:
+.TP
+.B /pmapi/NNNN/_indom?indom=DDDD
+List instances of the given instance domain.
+.TP
+.B /pmapi/NNNN/_indom?name=NAME
+List instances of the instance domain belonging to the named metric.
+.PP
+In addition, either query may be suffixed with:
+.TP
+.B &instance=IIII,JJJJ
+Restrict listings to given instance code numbers.
+.TP
+.B &iname=INAME1,INAME2
+Restrict listings to given instance names.
+.PP
+
+The response is a JSON document that provides the metric metadata
+as an array.  For example:
+
+.SAMPLE
+{ "indom":DDDD,
+   "instances": [
+      { "instance":IIII, "name":"INAME" }
+      ...
+   ] }
+.ESAMPLE
+
+.SS INSTANCE PROFILE: pmAddProfile, pmDelProfile
+
+.TP
+.B /pmapi/NNNN/_profile_reset?
+These are not currently supported.
+.TP
+.B /pmapi/NNNN/_profile_reset?indom=DDDD
+These are not currently supported.
+.TP
+.B /pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ
+These are not currently supported.
+.TP
+.B /pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ
+These are not currently supported.
+.TP
+.B /pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ
+These are not currently supported.
+.TP
+.B /pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2
+These are not currently supported.
+
+.SS DERIVED METRICS: pmRegisterDerived
+
+.TP
+.B /pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION
+These are not currently supported.
+
+.SS CONTEXT COPY: pmDupContext
+
+.TP
+.B /pmapi/NNNNN/copy
+These are not currently supported.
+
+.SS CONTEXT CLOSE: pmDestroyContext
+
+.TP
+.B /pmapi/NNNNN/destroy
+This is not likely to be supported, as it is destructive and would offer
+a tempting target to brute-force attackers.  Instead, the pmwebd timeout
+is used to automatically free unused contexts. 
+
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR PCPIntro (3),
+.BR pmwebd (3),
+and
+.BR PMAPI (3)
diff --git a/man/man3/pmwhichcontext.3 b/man/man3/pmwhichcontext.3
new file mode 100644
index 0000000..36c229d
--- /dev/null
+++ b/man/man3/pmwhichcontext.3
@@ -0,0 +1,49 @@
+'\"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 PMWHICHCONTEXT 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmWhichContext\f1 \- identify the current PMAPI context
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmWhichContext(void);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+An application using the
+Performance Metrics Application Programming Interface (PMAPI)
+may manipulate several concurrent contexts,
+each associated with a source of performance metrics, e.g. \c
+.BR pmcd (1)
+on some host, or an archive log of performance metrics as created by
+.BR pmlogger (1).
+.PP
+.B pmWhichContext
+returns a handle for the current PMAPI context, that may
+be used in the associated PMAPI routines that require a handle
+to identify a PMAPI context.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmDestroyContext (3),
+.BR pmDupContext (3),
+.BR pmNewContext (3)
+and
+.BR pmUseContext (3).
+.SH DIAGNOSTICS
+.IP \f3PM_ERR_NOCONTEXT\f1
+no current context
diff --git a/man/man3/pmwhichzone.3 b/man/man3/pmwhichzone.3
new file mode 100644
index 0000000..01be747
--- /dev/null
+++ b/man/man3/pmwhichzone.3
@@ -0,0 +1,53 @@
+'\"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 PMWHICHZONE 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmWhichZone\f1 \- return current reporting timezone
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+int pmWhichZone(char **\fItz\fP);
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+The current reporting timezone effects the timezone used by
+.BR pmCtime (3)
+and
+.BR pmLocaltime (3).
+.PP
+.B pmWhichZone
+returns the handle of the current timezone,
+as previously established by
+a call to
+.BR pmNewZone (3)
+or
+.BR pmNewContextZone (3).
+If the call is successful (i.e. there exists a current reporting timezone)
+then a non-negative integer is returned and
+.I tz
+is set to point to a static buffer containing the timezone string itself.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmCtime (3),
+.BR pmLocaltime (3),
+.BR pmNewContextZone (3),
+.BR pmNewZone (3)
+and
+.BR pmUseZone (3).
+.SH DIAGNOSTICS
+A return value less than zero indicates there is no current reporting timezone.