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

# \_\_pmContextWalk(3)

traversal of all PMAPI contexts

## NAME

**\_\_pmContextWalk** - traversal of all PMAPI contexts

## C SYNOPSIS

**#include "pmapi.h"**\
 **#include "libpcp.h"**

**void (\*\_\_pmContextWalkCallback)(void \****handle***, \_\_pmContext \****ctxp***);**\
 **int \_\_pmContextWalk(void \****handle***, \_\_pmContextWalkCallback** *callback***,**

**cc ... -lpcp**

## CAVEAT

This documentation is intended for internal Performance Co-Pilot (PCP) developer use.

These interfaces are not part of the PCP APIs that are guaranteed to remain fixed across releases, and they may not work, or may provide different semantics at some point in the future.

## DESCRIPTION

**\_\_pmContextWalk** provides a thread-safe and lock-safe way of processing each active PMAPI context in turn.

For each valid PMAPI context, *callback* is called with *handle* passed in from the **\_\_pmContextWalk** caller and *ctxp* pointing to a context for which the *c\_lock* lock has been acquired. The *handle* argument is a pointer to an arbitrary object that may be shared between the **\_\_pmContextWalk** caller and the *callback* routine, but is not otherwise accessed by **\_\_pmContextWalk**, so could be **NULL**.

The per-context *c\_lock* is released by **\_\_pmContextWalk** after *callback* is called and should not be unlocked by *callback*.

For the duration of the call to **\_\_pmContextWalk** all context initiation (via [**pmNewContext**(3)](/pmNewContext/3.md), **pmDupContext (3)** or [**pmReconnectContext**(3)](/pmReconnectContext/3.md)) and teardown (via [**pmDestroyContext**(3)](/pmDestroyContext/3.md)) is blocked.

## RETURN VALUES

**\_\_pmContextWalk** returns the number of contexts processed and hence the number of times *callback* was called, else a negative value suitable for reporting with [**pmErrStr**(3)](/pmErrStr/3.md).

## SEE ALSO

[**PMAPI**(3)](/PMAPI/3.md), [**pmDestroyContext**(3)](/pmDestroyContext/3.md), [**pmDupContext**(3)](/pmDupContext/3.md), [**pmErrStr**(3)](/pmErrStr/3.md), [**pmNewContext**(3)](/pmNewContext/3.md) and [**pmReconnectContext**(3)](/pmReconnectContext/3.md).