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

# pmFreeMetricSpec(3)

uniform metric specification parser

Part of [pmParseMetricSpec(3)](/pmParseMetricSpec/3.md).

## NAME

**pmParseMetricSpec**, **pmFreeMetricSpec** - uniform metric specification parser

## C SYNOPSIS

**#include \<pcp/pmapi.h\>**

**int pmParseMetricSpec(const char \****string***,** **int** *isarch***,** **char \****source***,** **pmMetricSpec \*\****rsltp***,** **char \*\****errmsg***);**\
 **void pmFreeMetricSpec(pmMetricSpec \****rslt***);**

**cc ... -lpcp**

## DESCRIPTION

**pmParseMetricSpec** accepts a **string** specifying the name of a PCP performance metric, and optionally the source (either a hostname or a PCP archive filename) and instances for that metric. The syntax is described in [**PCPIntro**(1)](/PCPIntro/1.md).

If neither **host** nor **archive** component of the metric specification is provided, the **isarch** and **source** arguments are used to fill in the returned **pmMetricSpec** structure.

The **pmMetricSpec** structure that is returned via **rsltp** represents the parsed **string** and has the following declaration:

```
    typedef struct {
        int     isarch;      /* source type: 0 -> live host, 1 -> archive, 2 -> local context */
        char    *source;     /* name of source host or archive */
        char    *metric;     /* name of metric */
        int     ninst;       /* number of instances, 0 -> all */
        char    *inst[1];    /* array of instance names */
    } pmMetricSpec;
```

**pmParseMetricSpec** `returns 0 if the given` **string** `was successfully parsed.  In this case all the storage allocated by` **pmParseMetricSpec** `can be released by a single call to` [**free**(3)](/free/3.md) `using the address returned from` **pmMetricSpec** `via` **rsltp**. `The convenience macro` **pmFreeMetricSpec** `is a thinly disguised wrapper for` [**free**(3)](/free/3.md).

**pmParseMetricSpec** `returns` **PM\_ERR\_GENERIC** `and a dynamically allocated error message string in` **errmsg**, `if the given` **string** `does not parse.  Be sure to` [**free**(3)](/free/3.md) `the error message string in this situation.`

`In the case of an error,` **rsltp** `is undefined.` `In the case of success,` **errmsg** `is undefined.` `If` **rsltp-\>ninst** `is 0, then` **rsltp-\>inst\[0\]** `is undefined.`

## SEE ALSO

[**PMAPI**(3)](/PMAPI/3.md) `and` [**pmLookupName**(3)](/pmLookupName/3.md).