---
name: "pmgenmap"
section: "1"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pmgenmap"
---

# pmgenmap(1)

generate C code to simplify handling of performance metrics

## 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)](/cpp/1.md) 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)](/cpp/1.md) 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)](/pmLookupName/3.md) and the **#define**d constants may be used to index the *vset*s in the *pmResult* structure returned by a [**pmFetch**(3)](/pmFetch/3.md) call.

Obviously, *listname* must conform to the C identifier naming rules, each *symbolname* must conform to the [**cpp**(1)](/cpp/1.md) macro naming rules, and each *metricname* is expected to be a valid performance metrics name (see [**PMNS**(5)](/PMNS/5.md) 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)](/pmLookupDesc/3.md) 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)](/pcp.conf/5.md).

## SEE ALSO

[**cpp**(1)](/cpp/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmFetch**(3)](/pmFetch/3.md), [**pmLookupName**(3)](/pmLookupName/3.md), [**pmNewContext**(3)](/pmNewContext/3.md), [**pcp.conf**(5)](/pcp.conf/5.md), [**pcp.env**(5)](/pcp.env/5.md) and [**PMNS**(5)](/PMNS/5.md).