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

# pmTrimNameSpace(3)

prune a performance metrics name space

## NAME

**pmTrimNameSpace** - prune a performance metrics name space

## C SYNOPSIS

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

**int pmTrimNameSpace(void);**

**cc ... -lpcp**

## DESCRIPTION

In some (rare) cases it is helpful to prune the Performance Metrics Name Space (PMNS) to match the available metrics.

The default PMNS that is accessible to a Performance Metrics Application Programming Interface (PMAPI) client is provided by the current PMAPI context:

- •

  for a PMAPI context of type **PM\_CONTEXT\_HOST** the PMNS is provided by [**pmcd**(1)](/pmcd/1.md) on the associated host and no pruning is required

- •

  for a PMAPI context of type **PM\_CONTEXT\_ARCHIVE** the PMNS is stored within the associated Performance Co-Pilot (PCP) archive and no pruning is required

- •

  for a PMAPI context of type **PM\_CONTEXT\_LOCAL** at the first PMAPI call requiring access to the PMNS it is loaded from the default local location **$PCP\_VAR\_DIR/pmns/root** (or **$PMNS\_DEFAULT**) and no pruning is required.

If the default PMNS is in effect then calling **pmTrimNameSpace** is a no-op and returns zero with no change to the PMNS.

PMAPI clients also have the option of over-riding the default PMNS by loading a *local* PMNS from a file (see [**PMNS**(5)](/PMNS/5.md) for the format) by calling [**pmLoadASCIINameSpace**(3)](/pmLoadASCIINameSpace/3.md) or [**pmLoadNameSpace**(3)](/pmLoadNameSpace/3.md) and this is when some PMNS pruning *may* be useful.

If a *local* PMNS is in effect when **pmTrimNameSpace** is called then the first action is to restore the PMNS to the state as of the completion of the last [**pmLoadASCIINameSpace**(3)](/pmLoadASCIINameSpace/3.md) or [**pmLoadNameSpace**(3)](/pmLoadNameSpace/3.md), so that the effects of consecutive calls to **pmTrimNameSpace** are **not** additive.

The subsequent actions of **pmTrimNameSpace** depend on the type of the current PMAPI context.

- •

  For a context of type **PM\_CONTEXT\_ARCHIVE** the *local* PMNS is trimmed to exclude metrics for which no description can be found in the PCP archive. The PMNS is further trimmed to remove empty subtrees that do not contain any performance metric. Since PCP archives usually contain some subset of all metrics named in a PMNS, **pmTrimNameSpace** effectively prunes the application's PMNS to contain only the names of the metrics in the archive.

- •

  For a context of type **PM\_CONTEXT\_HOST** or **PM\_CONTEXT\_LOCAL** no further action is required.

On success, **pmTrimNameSpace** returns zero.

## DIAGNOSTICS

- **PM\_ERR\_NOPMNS**

  there has been some earlier problem with establishing the relevant PMNS

- **PM\_ERR\_NOCONTEXT**

  the current PMAPI context is invalid

## SEE ALSO

[**pmlogger**(1)](/pmlogger/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmLoadASCIINameSpace**(3)](/pmLoadASCIINameSpace/3.md), [**pmLoadNameSpace**(3)](/pmLoadNameSpace/3.md), [**pmNewContext**(3)](/pmNewContext/3.md) and [**PMNS**(5)](/PMNS/5.md).