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

# pmDerivedControl(3)

get and set controls for derived metrics

## NAME

**pmGetDerivedControl**, **pmSetDerivedControl**  - get and set controls for derived metrics

## C SYNOPSIS

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

**int pmGetDerivedControl(int** *what***, int \****valuep***);**\
 **int pmSetDerivedControl(int** *what***, int** *value***);**

**cc ... -lpcp**

## DESCRIPTION

These routines may be used to influence the behaviour of the derived metric services that are activated for global derived metrics using [**pmRegisterDerived**(3)](/pmRegisterDerived/3.md), [**pmRegisterDerivedMetric**(3)](/pmRegisterDerivedMetric/3.md) and [**pmLoadDerivedConfig**(3)](/pmLoadDerivedConfig/3.md), or per-context derived metrics using [**pmAddDerived**(3)](/pmAddDerived/3.md) and [**pmAddDerivedMetric**(3)](/pmAddDerivedMetric/3.md).

The *what* argument selects a control or option, the *value* argument provides a value for **pmSetDerivedControl** and the *valuep* argument is used to return the value for **pmGetDerivedControl**.

The *what* argument has one of the following values:

- **PCP\_DERIVED\_GLOBAL\_LIMIT**

  The maximum number of global derived metrics that may be defined. The *value* should be greater than zero, or -1 (for no limit). The initial value is -1.

- **PCP\_DERIVED\_CONTEXT\_LIMIT**

  The maximum number of per-context derived metrics that may be defined. The *value* should be greater than zero, or -1 (for no limit). The initial value is -1.

- **PCP\_DERIVED\_DEBUG\_SYNTAX**

  Debug diagnostics during parsing of derived metric expression. The *value* 1 enables the diagnostics, 0 disables them. The initial value is 0.

- **PCP\_DERIVED\_DEBUG\_SEMANTICS**

  Debug diagnostics for semantic checks during the binding of metrics in the derived metric expression to the available metrics in a new PMAPI context. The *value* 1 enables the diagnostics, 0 disables them. The initial value is 0.

- **PCP\_DERIVED\_DEBUG\_EVAL**

  Debug diagnostics when derived metrics are used in PMAPI operations like [**pmFetch**(3)](/pmFetch/3.md), [**pmGetChildren**(3)](/pmGetChildren/3.md), [**pmGetChildrenStatus**(3)](/pmGetChildrenStatus/3.md), [**pmLookupDesc**(3)](/pmLookupDesc/3.md), [**pmLookupName**(3)](/pmLookupName/3.md), [**pmNameAll**(3)](/pmNameAll/3.md), [**pmNameID**(3)](/pmNameID/3.md) and [**pmTraversePMNS**(3)](/pmTraversePMNS/3.md). The *value* 1 enables the diagnostics, 0 disables them. The initial value is 0.

- **PCP\_DERIVED\_OPTION\_NOVALUE**

  When a performance metric (used as an operand in a derived metric expression) is no available (e.g. missing from a PCP archive context or not provided by any PMDA for a host context), then the default behaviour is to mark the derived metric as undefined. If this option is set to 1 (the default is 0), then any metric that is not available is mapped to the **novalue**() constructor (refer to [**pmRegisterDerived**(3)](/pmRegisterDerived/3.md) for details), which in essence means the metric is defined, but attempts to retrieve values via [**pmFetch**(3)](/pmFetch/3.md) will return **PM\_ERR\_VALUE** (Missing metric value(s)).

## RETURN VALUES

Both routines return 0 on success, else a value less than 0 that can be decoded using [**pmErrStr**(3)](/pmErrStr/3.md).

Some overloading of error codes is needed to accommodate the unusual semantics of these routines, as described below.

| | |
| --- | --- |
| Error | Meaning |
| PM\_ERR\_NAME | *what* is not one of the expected values |
| PM\_ERR\_ARG | the *value* provided to **pmSetDerivedControl** is not within the acceptable range |
| PM\_ERR\_NOCONTEXT | getting or setting **PCP\_DERIVED\_CONTEXT\_LIMIT** only makes sense when there is a current PMAPI context |
| PM\_ERR\_AGAIN | **pmSetDerivedControl** request would violate precedence rules (see below) |

## OTHER OPTIONS

All of the controls and options that are exposed by **pmSetDerivedControl** can also be set in two other ways.

- 1\.

  Setting the **PCP\_DERIVED\_CONTROL** environment variable to a value of the form *name*=*integer* where *name* is one of the *what* macros described above, stripped of the **PCP\_DERIVED\_** prefix, e.g. *novalue=1*. *name* is case insensitive and multiple specifications are allowed, separated by commas.  No whitespace is allowed.

- 2\.

  Use of a **#control** line in a derived metric configuration file, where the text following the **#control** follows exactly the same rules as for the **PCP\_DERIVED\_CONTROL** environment variable described above.

Given these options can be specified in multiple ways, possibly with different values, the precedence rules are if **PCP\_DERIVED\_CONTROL** is set, then that value is honoured, else the most recently set value from **#control** or **pmSetDerivedControl** is used.

## SEE ALSO

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