# pmgenmap

## NAME



           **pmgenmap** - generate C code to simplify handling of performance
           metrics
    


## SYNOPSIS



           **pmgenmap**[_infile_]
    


## DESCRIPTION



           Given one or more lists of metric names in _infile_ or on standard
           input, **pmgenmap** generates C declarations and cpp(1) macros
           suitable for use across the Performance Metrics Programming
           Interface (PMAPI) on standard output.
    
           The declarations produced by **pmgenmap** simplify the coding for
           client applications using the PMAPI.
    
           The input should consist of one or more lists of metric names of
           the form
    
                listname {
                    metricname1 symbolname1
                    metricname2 symbolname2
                    ...
                }
    
           which will generate C and cpp(1) declarations of the form
    
                char *listname[] = {
                #define symbolname1 0
                    "metricname1",
                #define symbolname2 1
                    "metricname2",
                    ...
                };
    
           The array declarations produced are suitable as parameters to
           pmLookupName(3) and the **#define** d constants may be used to index
           the _vset_ s in the _pmResult_ structure returned by a pmFetch(3) call.
    
           Obviously, _listname_ must conform to the C identifier naming rules,
           each _symbolname_ must conform to the cpp(1) macro naming rules, and
           each _metricname_ is expected to be a valid performance metrics name
           (see PMNS(5) for more details).
    
           The input may include **sh** -style comment lines, i.e. with a `**#** ' 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:
    
                # 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
    
           Produces the output:
    
                /*
                 * 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 */
    


## EXAMPLES



           For brevity we have removed the error handling code, and assumed
           the chosen metrics do not have multiple values.
    
           The input file
    
                mystats {
                    kernel.percpu.cpu.idle     IDLE
                    kernel.percpu.cpu.sys      SYS
                    kernel.percpu.cpu.user     USER
                    hinv.ncpu                       NCPU
                }
    
           produces the following C code, suitable for **#include** -ing
    
                /*
                 * 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",
    
                };
    
           Using the code generated by **pmgenmap** , we are now able to easily
           obtain metrics from the Performance Metrics Collection Subsystem
           (PMCS) as follows:
    
                #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   idle0,
                           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);
    
           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 pmLookupDesc(3) should have been
           called to determine the semantics of each metric.
    
           More complete examples that demonstrate the use of **pmgenmap** which
           may be used as a basis for program development are included in the
           PCP demos, e.g.  _$PCP_DEMOS_DIR/pmclient_.
    


## FILES



           _$PCP_VAR_DIR/pmns/*_
                default PMNS specification files
    


## PCP ENVIRONMENT



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


* * *