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

# pmAddDerivedText(3)

add help text for a derived metric

## NAME

**pmAddDerivedText** - add help text for a derived metric

## C SYNOPSIS

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

**int pmAddDerivedText(const char \****name***,** **int** *type***,** **const char \****text***);**

**cc ... -lpcp**

## DESCRIPTION

Derived metrics provide a way of extending the Performance Metrics Name Space (PMNS) with new metrics defined at the PCP client-side using expressions over the existing performance metrics. Global derived metrics are defined using [**pmRegisterDerived**(3)](/pmRegisterDerived/3.md) or [**pmRegisterDerivedMetric**(3)](/pmRegisterDerivedMetric/3.md) or [**pmLoadDerivedConfig**(3)](/pmLoadDerivedConfig/3.md), and per-context derived metrics are defined using [**pmAddDerived**(3)](/pmAddDerived/3.md) or [**pmAddDerivedMetric**(3)](/pmAddDerivedMetric/3.md).

Once a derived metric has been defined, **pmAddDerivedText** may be used to associate the help *text* with the derived metric identified by *name*.

Help text may be a \`\`one line'' summary or a more verbose \`\`multi-line'' block of text, and *type* should be **PM\_TEXT\_ONELINE** or **PM\_TEXT\_HELP** respectively. To associate both styles of help text with a derived metric, **pmAddDerivedText** would need to be called twice with different values for *type*.

Once a particular *type* of help text has been associated with a derived metric it cannot be deleted or redefined.

Applications using the Performance Metrics Application Programming Interface (PMAPI) are able to retrieve help text for specific metrics using [**pmLookupText**(3)](/pmLookupText/3.md).

## DIAGNOSTICS

**pmAddDerivedText** returns zero on success, else an error code.

The return value **PM\_ERR\_NAME** indicates *name* does not correspond to a previously defined derived metric.

Repeated calls for the same *name* and *type* will result a return value of **PM\_ERR\_TEXT**.

A return value of **PM\_ERR\_ARG** indicates that *type* is not one of the expected values.

## SEE ALSO

[**PCPIntro**(1)](/PCPIntro/1.md), [**pmAddDerived**(3)](/pmAddDerived/3.md), [**pmAddDerivedMetric**(3)](/pmAddDerivedMetric/3.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmLoadDerivedConfig**(3)](/pmLoadDerivedConfig/3.md), [**pmLookupText**(3)](/pmLookupText/3.md), [**pmRegisterDerived**(3)](/pmRegisterDerived/3.md), [**pmRegisterDerivedMetric**(3)](/pmRegisterDerivedMetric/3.md) and [**PMNS**(5)](/PMNS/5.md).