---
name: "pmReceiveTraversePMNS"
section: "3"
platform: "linux"
package: "libpcp3-dev"
version: "3.3.3-squeeze3"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/pmReceiveTraversePMNS"
---

# pmReceiveTraversePMNS(3)

traverse the performance metrics name space

## NAME

**pmTraversePMNS**, **pmRequestTraversePMNS**, **pmReceiveTraversePMNS** - traverse the performance metrics name space

## C SYNOPSIS

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

```
int pmTraversePMNS(const char *name, void (*dometric)(const char *))
int pmRequestTraversePMNS(int ctx, const char *name)
int pmReceiveTraversePMNS(int ctx, void (*dometric)(const char *))
```

**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**(3C) before returning from *dometric*.

On success **pmtraversePMNS** returns the number of children of *name*, which may be zero.

**pmRequestTraversePMNS** and **pmReceiveTraversePMNS** are used by applications which must  communicate with the PMCD asynchronously. These functions take explict context handle *ctx* which must refer to a host context (i.e. created by passing **PM\_CONTEXT\_HOST** to **pmNewContext**). **pmRequestTraversePMNS** sends request to PMCD to return sub-tree of PMNS and returns without waiting for the response, **pmReceiveTraversePMNS** reads reply from PMCD and executes depth-first traversal over returned sub-tree. It is the responsibility of the application to make sure the data are ready before calling **pmReceiveTraversePMNS**.

Unlike its synchronous counterpart **pmTraversePMNS**, **pmReceiveTraversePMNS** does not perform any additional queries to provide compatibility with older versions of PCP, it is the responsibility of an application to implement additional traversals.

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

- **PM\_ERR\_CTXBUSY**

  Context is currently in use by another asynchronous call.