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

# pmTraversePMNS\_r(3)

traverse the performance metrics name space

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

## NAME

**pmTraversePMNS**, **pmTraversePMNS\_r** - traverse the performance metrics name space

## C SYNOPSIS

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

**int pmTraversePMNS(const char \****name***,** **void (\****dometric***)(const char \*));** **int pmTraversePMNS\_r(const char \****name***,** **void (\****dometric\_r***)(const char \*, void \*),** **void \****closure***);**

**cc ... -lpcp**

## DESCRIPTION

The routine **pmTraversePMNS** may be used to perform a depth-first traversal of the Performance Metrics Name Space (PMNS).

The traversal starts at the node identified by *name* - if *name* is an empty string (i.e. **""**), the traversal starts at the root of the PMNS. Usually *name* would be the pathname of a non-leaf node in the PMNS.

For each leaf node (i.e. performance metric) found in the traversal, the user-supplied routine *dometric* is called with the full pathname of that metric in the PMNS as the single argument. This argument is null-byte terminated, and is constructed from a buffer that is managed internally to **pmTraversePMNS**. Consequently the value is only valid during the call to *dometric* - if the pathname needs to be retained, it should be copied using [**strdup**(3)](/strdup/3.md) before returning from *dometric*.

The **pmTraversePMNS\_r** routine performs the same function, except the callback method *func\_r* has an additional parameter that will be *closure* from the initial call to **pmTraversePMNS\_r**. The additional parameter to **pmTraversePMNS\_r** and the callback method allows the caller to pass context through **pmTraversePMNS\_r** and into the callback method *func\_r*, making the service more useful for multi-threaded applications where thread-private data can be accessed in the callback method via the *closure* argument.

On success **pmTraversePMNS** and **pmTraversePMNS\_r** return the number of leaf nodes found in the traversal, which will be one (1) if *name* is either a leaf node, or a derived metric or a non-leaf node with one child. If *name* is a non-leaf node, the returned value will be zero or greater (zero is returned in the special case where *name* is a dynamic root node that currently has no children). In all cases, derived metrics present in the PMNS subtree below *name* are counted as leaf-nodes. If an an error occurs, **pmTraversePMNS** and **pmTraversePMNS\_r** will return a negative error code, as described in the **DIAGNOSTICS** section below.

## DIAGNOSTICS

- **PM\_ERR\_NOPMNS**

  Failed to access a PMNS for operation. Note that if the application hasn't a priori called [pmLoadNameSpace(3)](/pmLoadNameSpace/3.md) and wants to use the distributed PMNS, then a call to **pmTraversePMNS** must be made inside a current context.

- **PM\_ERR\_NAME**

  The initial pathname *name* is not valid in the current PMNS.

- **PM\_ERR\_\***

  Other diagnostics are for protocol failures when accessing the distributed PMNS.

## SEE ALSO

[**PMAPI**(3)](/PMAPI/3.md) and [**pmGetChildren**(3)](/pmGetChildren/3.md).