pmgenmap(1)

1PMGENMAP(1)                 General Commands Manual                PMGENMAP(1)
2
3
4

NAME

6       pmgenmap - generate C code to simplify handling of performance metrics
7

SYNOPSIS

9       pmgenmap [infile]
10

DESCRIPTION

12       Given one or more lists of metric names in infile or on standard input,
13       pmgenmap generates C declarations and cpp(1) macros  suitable  for  use
14       across  the  Performance Metrics Programming Interface (PMAPI) on stan‐
15       dard output.
16
17       The declarations produced by pmgenmap simplify the  coding  for  client
18       applications using the PMAPI.
19
20       The  input  should  consist of one or more lists of metric names of the
21       form
22
23            listname {
24                metricname1 symbolname1
25                metricname2 symbolname2
26                ...
27            }
28
29       which will generate C and cpp(1) declarations of the form
30
31            char *listname[] = {
32            #define symbolname1 0
33                "metricname1",
34            #define symbolname2 1
35                "metricname2",
36                ...
37            };
38
39       The array declarations produced are suitable as parameters to pmLookup‐
40       Name(3)  and  the  #defined constants may be used to index the vsets in
41       the pmResult structure returned by a pmFetch(3) call.
42
43       Obviously, listname must conform to the C identifier naming rules, each
44       symbolname must conform to the cpp(1) macro naming rules, and each met‐
45       ricname is expected to be a valid performance metrics name (see pmns(5)
46       for more details).
47
48       The  input  may  include sh-style comment lines, i.e. with a `#' as the
49       first non-blank character of a line, and these are translated on output
50       to  either  single line or multi-line C comments in the K&R style.  For
51       example, the input:
52
53
54            # leading block of multi-line comments
55            # initialization group
56            foo {
57                    a.b.c   ONE
58                    d.e.f.g TWO
59                    # embedded block of multi-lines
60                    # comments and boring pad text
61                    xx.yy.zz        THREE
62            }
63
64            # trailing single line comment
65
66       Produces the output:
67
68            /*
69             * leading block of multi-line comments
70             * initialization group
71             */
72            char *foo[] = {
73            #define ONE 0
74                    "a.b.c",
75            #define TWO 1
76                    "d.e.f.g",
77            /*
78             * embedded block of multi-lines
79             * comments and boring pad text
80             */
81            #define THREE 2
82                    "xx.yy.zz",
83
84            };
85
86
87            /* trailing single line comment */
88

EXAMPLE

90       For brevity we have removed the error handling code,  and  assumed  the
91       chosen metrics do not have multiple values.
92
93       The input file
94
95            mystats {
96                kernel.percpu.cpu.idle     IDLE
97                kernel.percpu.cpu.sys      SYS
98                kernel.percpu.cpu.user     USER
99                hinv.ncpu                       NCPU
100            }
101
102       produces the following C code, suitable for #include-ing
103
104            /*
105             * Performance Metrics Name Space Map
106             * Built by pmgenmap from the file
107             * mystats.metrics
108             * on Wed Dec 28 19:44:17 EST 1994
109             *
110             * Do not edit this file!
111             */
112
113            char *mystats[] = {
114            #define IDLE    0
115                    "kernel.percpu.cpu.idle",
116            #define SYS     1
117                    "kernel.percpu.cpu.sys",
118            #define USER    2
119                    "kernel.percpu.cpu.user",
120            #define NCPU    3
121                    "hinv.ncpu",
122
123            };
124
125       Using  the code generated by pmgenmap, we are now able to easily obtain
126       metrics from the Performance Metrics  Collection  Subsystem  (PMCS)  as
127       follows:
128
129
130            #define MAX_PMID 4
131
132                int         trip = 0;
133                int         numpmid = sizeof(mystats)/sizeof(mystats[0]);
134                double      duration;
135                pmResult    *resp;
136                pmResult    *prev;
137                pmID        pmidlist[MAX_PMID];
138
139                pmNewContext(PM_CONTEXT_HOST, "localhost");
140                pmLookupName(numpmid, mystats, pmidlist);
141                pmFetch(numpmid, pmidlist, &resp);
142
143                printf("%d CPUs: %d usr   %d sys   %d   idle0,
144                       resp->vset[NCPU]->vlist[0].value.lval,
145                       resp->vset[USER]->vlist[0].value.lval,
146                       resp->vset[SYS]->vlist[0].value.lval,
147                       resp->vset[IDLE]->vlist[0].value.lval);
148
149       Some  calls to ensure portability have been removed from the code above
150       for the sake of clarity - the example above should not  be  used  as  a
151       template for programming.  In particular, the raw values of the metrics
152       were used when pmLookupDesc(3) should have been called to determine the
153       semantics of each metric.
154
155       More  complete  examples that demonstrate the use of pmgenmap which may
156       be used as a basis for program development  are  included  in  the  PCP
157       demos, e.g.  $PCP_DEMOS_DIR/pmclient.
158

FILES

160       $PCP_VAR_DIR/pmns/*
161                 default PMNS specification files
162

PCP ENVIRONMENT

164       Environment variables with the prefix PCP_ are used to parameterize the
165       file and directory names used by PCP.  On each installation,  the  file
166       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
167       $PCP_CONF variable may be used to specify an alternative  configuration
168       file, as described in pcp.conf(5).
169

NAME

SYNOPSIS

DESCRIPTION

EXAMPLE

FILES

PCP ENVIRONMENT

SEE ALSO