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

# pmdaLabel(3)

fill pmLabelSet structures with metric labels

## NAME

**pmdaLabel**, **pmdaSetLabelCallBack** - fill pmLabelSet structures with metric labels

## C SYNOPSIS

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

**int pmdaLabel(int** *ident***,** **int** *type***,** **pmLabelSet \*\****sets***,** **pmdaExt \****pmda***);**\
 **int pmdaSetLabelCallBack(pmdaInterface \****dispatch***,** **pmdaLabelCallBack** *callback***);**

**cc ... -lpcp\_pmda -lpcp**

## DESCRIPTION

As part of the Performance Metrics Domain Agent (PMDA) API (see [**PMDA**(3)](/PMDA/3.md)), **pmdaLabel** uses the standard [**PMDA**(3)](/PMDA/3.md) data structures to return the labels for performance domain, instance domain, metric or individual instances in "JSONB" format in the given *sets* data structure.

The *type* argument determines the interpretation of *ident* and the requested form of label, as follows:

- **PM\_LABEL\_DOMAIN**

  when *ident* is a PMDA domain identifier,

- **PM\_LABEL\_CLUSTER**

  when *ident* is a metric identifier and labels for the cluster containing that metric are being requested.

- **PM\_LABEL\_ITEM**

  when *ident* is a metric identifier,

- **PM\_LABEL\_INDOM**

  when *ident* is an instance domain identifier, or

- **PM\_LABEL\_INSTANCES**

  when *ident* is a metric identifier and labels for all instances of that metric are being requested.

The label *sets* pointer must be initialised to NULL before calling **pmdaLabel** and space is only to be allocated when labels are present and returned. In this case, the return code must indicate the number of label *sets* that have been allocated. This will only ever be greater than one in the **PM\_LABEL\_INSTANCES** case.

This is one of the few generic callbacks in *libpcp\_pmda* (see [**PMDA**(3)](/PMDA/3.md)) that is incomplete, requiring a further **pmdaLabelCallBack** method of its own. The additional callback should be registered using **pmdaSetLabelCallBack** and the **pmdaLabelCallBack** method has the following prototype:

```
int func(pmInDom indom, unsigned int inst, pmLabelSet **set)
```

*The purpose of the* **pmdaLabelCallBack** *routine is to return the label(s) for an individual instance* *inst* *of a given instance domain,* *indom*. *Its successful return code differs significantly to* **pmdaLabel**, *as described below.*

## CAVEAT

*The PMDA must be using* **PMDA\_INTERFACE\_7** *or later, as specified in the call to* [**pmdaDSO**(3)](/pmdaDSO/3.md) *or* [**pmdaDaemon**(3)](/pmdaDaemon/3.md).

## DIAGNOSTICS

*On success* **pmdaLabel** *returns the number of label* *sets* *created.* *This is usually zero or one, except in the case of* **PM\_LABEL\_INSTANCES** *where more than one label* *sets* *will often be returned, one for each instance of the requested metric.*

*By contrast, on success of the* **pmdaLabelCallBack** *routine the number of labels successfully added to the provided* *labelset pointer must be returned (and not the total number of label* *sets*).

*If labels for the requested entity could not be obtained due to a* *catastrophic failure, such as an out of memory condition, these* *routines will return a negative error code.*

## SEE ALSO

[**pminfo**(1)](/pminfo/1.md), [**malloc**(3)](/malloc/3.md), [**PMAPI**(3)](/PMAPI/3.md), [**PMDA**(3)](/PMDA/3.md), [**pmdaDaemon**(3)](/pmdaDaemon/3.md), [**pmdaDSO**(3)](/pmdaDSO/3.md), [**pmdaInit**(3)](/pmdaInit/3.md) *and* [**pmLookupLabels**(3)](/pmLookupLabels/3.md).