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
67       Produces the output:
68
69            /*
70             * leading block of multi-line comments
71             * initialization group
72             */
73            char *foo[] = {
74            #define ONE 0
75                    "a.b.c",
76            #define TWO 1
77                    "d.e.f.g",
78            /*
79             * embedded block of multi-lines
80             * comments and boring pad text
81             */
82            #define THREE 2
83                    "xx.yy.zz",
84
85            };
86
87
88            /* trailing single line comment */
89

EXAMPLES

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

FILES

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

PCP ENVIRONMENT

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

NAME

SYNOPSIS

DESCRIPTION

EXAMPLES

FILES

PCP ENVIRONMENT

SEE ALSO