Debian 3.9.10debian/3.9.10debian

1 files changed, 274 insertions, 0 deletions

diff --git a/man/man1/pmgenmap.1 b/man/man1/pmgenmap.1
new file mode 100644
index 0000000..7f3d0bb
--- /dev/null
+++ b/man/man1/pmgenmap.1
@@ -0,0 +1,274 @@
+'\"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 PMGENMAP 1 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmgenmap\f1 \- generate C code to simplify handling of performance metrics
+.\" literals use .B or \f3
+.\" arguments use .I or \f2
+.SH SYNOPSIS
+\f3pmgenmap\f1
+[\f2infile\f1]
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Given one or more lists of metric names in
+.I infile
+or on standard input,
+.B pmgenmap
+generates C declarations
+and
+.BR cpp (1)
+macros suitable for use across the
+Performance Metrics Programming Interface (PMAPI)
+on standard output.
+.PP
+The declarations produced by
+.B pmgenmap
+simplify the coding for client applications using the PMAPI.
+.PP
+The input should consist of one or more lists of metric names of the form
+.PP
+.ft CW
+.nf
+.in +0.5i
+listname {
+    metricname1 symbolname1
+    metricname2 symbolname2
+    ...
+}
+.in
+.fi
+.ft 1
+.PP
+which will generate C and
+.BR cpp (1)
+declarations of the form
+.PP
+.ft CW
+.nf
+.in +0.5i
+char *listname[] = {
+#define symbolname1 0
+    "metricname1",
+#define symbolname2 1
+    "metricname2",
+    ...
+};
+.in
+.fi
+.ft 1
+.PP
+The array declarations produced are suitable as parameters to
+.BR pmLookupName (3)
+and the
+.BR #define d
+constants may be used to index the
+.CW vset s
+in the
+.CW pmResult
+structure returned by a
+.BR pmFetch (3)
+call.
+.PP
+Obviously,
+.CW listname
+must conform to the C identifier naming rules, each
+.CW symbolname
+must conform to the
+.BR cpp (1)
+macro naming rules, and each
+.CW metricname
+is expected to be a valid performance metrics name (see
+.BR pmns (5)
+for more details).
+.PP
+The input may include
+.BR sh -style
+comment lines, i.e. with a `\f3#\f1' as the first non-blank character of a
+line, and these are translated on output to either single line or multi-line C
+comments in the K&R style.  For example, the input:
+
+.PP
+.ft CW
+.nf
+.in +0.5i
+# leading block of multi-line comments
+# initialization group
+foo {
+        a.b.c   ONE
+        d.e.f.g TWO
+        # embedded block of multi-lines
+        # comments and boring pad text
+        xx.yy.zz        THREE
+}
+
+# trailing single line comment
+.in
+.fi
+.ft 1
+.PP
+
+Produces the output:
+.PP
+.ft CW
+.nf
+.in +0.5i
+/*
+ * leading block of multi-line comments
+ * initialization group
+ */
+char *foo[] = {
+#define ONE 0
+        "a.b.c",
+#define TWO 1
+        "d.e.f.g",
+/*
+ * embedded block of multi-lines
+ * comments and boring pad text
+ */
+#define THREE 2
+        "xx.yy.zz",
+
+};
+
+
+/* trailing single line comment */
+.in
+.fi
+.ft 1
+.SH EXAMPLE
+For brevity we have removed the error handling code, and assumed the chosen
+metrics do not have multiple values.
+.PP
+The input file
+.PP
+.ft CW
+.nf
+.in +0.5i
+mystats {
+    kernel.percpu.cpu.idle     IDLE
+    kernel.percpu.cpu.sys      SYS
+    kernel.percpu.cpu.user     USER
+    hinv.ncpu                       NCPU
+}
+.in
+.fi
+.ft 1
+.PP
+produces the following C code, suitable for
+.BR #include -ing
+.PP
+.ft CW
+.nf
+.in +0.5i
+/*
+ * Performance Metrics Name Space Map
+ * Built by pmgenmap from the file
+ * mystats.metrics
+ * on Wed Dec 28 19:44:17 EST 1994
+ *
+ * Do not edit this file!
+ */
+
+char *mystats[] = {
+#define IDLE    0
+        "kernel.percpu.cpu.idle",
+#define SYS     1
+        "kernel.percpu.cpu.sys",
+#define USER    2
+        "kernel.percpu.cpu.user",
+#define NCPU    3
+        "hinv.ncpu",
+
+};
+.in
+.fi
+.ft 1
+.PP
+Using the code generated by
+.BR pmgenmap ,
+we are now able to easily obtain metrics from the Performance Metrics Collection
+Subsystem (PMCS) as follows:
+
+.PP
+.ft CW
+.nf
+.in +0.5i
+#define MAX_PMID 4
+
+    int         trip = 0;
+    int         numpmid = sizeof(mystats)/sizeof(mystats[0]);
+    double      duration;
+    pmResult    *resp;
+    pmResult    *prev;
+    pmID        pmidlist[MAX_PMID];
+
+    pmNewContext(PM_CONTEXT_HOST, "localhost");
+    pmLookupName(numpmid, mystats, pmidlist);
+    pmFetch(numpmid, pmidlist, &resp);
+
+    printf("%d CPUs: %d usr   %d sys   %d   idle\n", 
+           resp->vset[NCPU]->vlist[0].value.lval,
+           resp->vset[USER]->vlist[0].value.lval,
+           resp->vset[SYS]->vlist[0].value.lval,
+           resp->vset[IDLE]->vlist[0].value.lval);
+.in
+.fi
+.ft 1
+.PP
+Some calls to ensure portability have been removed from the code above for the
+sake of clarity \- the example above should not be used as a template for
+programming.  In particular, the raw values of the metrics were used when
+.BR pmLookupDesc (3)
+should have been called to determine the semantics of each metric.
+.PP
+More complete examples that demonstrate the use of
+.B pmgenmap
+which may be used as a basis for program development are included in the
+PCP demos, e.g.
+.IR $PCP_DEMOS_DIR/pmclient .
+.SH FILES
+.PD 0
+.TP 10
+.BI $PCP_VAR_DIR/pmns/ *
+default PMNS specification files
+.PD
+.SH "PCP ENVIRONMENT"
+Environment variables with the prefix
+.B PCP_
+are used to parameterize the file and directory names
+used by PCP.
+On each installation, the file
+.I /etc/pcp.conf
+contains the local values for these variables.
+The
+.B $PCP_CONF
+variable may be used to specify an alternative
+configuration file,
+as described in
+.BR pcp.conf (5).
+.SH SEE ALSO
+.BR cpp (1),
+.BR PMAPI (3),
+.BR pmFetch (3),
+.BR pmLookupName (3),
+.BR pmNewContext (3),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR pmns (5).