---
name: "pmtraversepmns"
section: "3"
platform: "linux"
package: "libpcp3-dev"
version: "4.3.2+really4.3.1-0.1"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/pmTraversePMNS"
---

# pmtraversepmns(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.

## SEE ALSO

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

## 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.