1 files changed, 100 insertions, 0 deletions
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