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

# pmReconnectContext(3)

reconnect to a PMAPI context

## NAME

**pmReconnectContext** - reconnect to a PMAPI context

## C SYNOPSIS

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

**int pmReconnectContext(int** *handle***);**

**cc ... -lpcp**

## DESCRIPTION

As a consequence of network, host or Performance Metrics Collector Daemon (PMCD) failures, an application's connection to a PMCD may be established and then subsequently lost.

The routine **pmReconnectContext** allows an application to request that the context identified by *handle* should be re-established, provided the associated metrics source is accessible.

When the source of metrics associated with the context *handle* is [**pmcd**(1)](/pmcd/1.md), then to avoid flooding the system with reconnect requests, **pmReconnectContext** will only attempt a reconnection after a suitable delay from the previous unsuccessful attempt to reconnect this context. This imposed restriction on the reconnect re-try time interval uses an exponential back-off so that the initial delay is 5 seconds after the first unsuccessful attempt, then 10 seconds, then 20 seconds, then 40 seconds and then 80 seconds thereafter.

The environment variable **PMCD\_RECONNECT\_TIMEOUT** may be used to redefine the back-off intervals, see [**PMAPI**(3)](/PMAPI/3.md).

Calling **pmReconnectContext** with a handle identifying a currently connected [**pmcd**(1)](/pmcd/1.md) context will cause the connection to be broken before any reconnection is attempted.

If *handle* identifies a context associated with an archive source of metrics, **pmReconnectContext** returns without delay.

If the reconnection succeeds, **pmReconnectContext** returns *handle*.

As a side-effect of reconnecting, any derived metrics that have previously been defined using [**pmRegisterDerived**(3)](/pmRegisterDerived/3.md), [**pmRegisterDerivedMetric**(3)](/pmRegisterDerivedMetric/3.md) or [**pmLoadDerivedConfig**(3)](/pmLoadDerivedConfig/3.md) will be re-processed and re-bound to the available metrics from the reconnected source. The support of dynamic definition for derived metrics provides one use case where **pmReconnectContext** may be called even if the connection to the metrics source has not been lost.

Note that even in the case of a successful reconnection, **pmReconnectContext** does not change the current Performance Metrics Application Programming Interface (PMAPI) context, so *handle* remains valid.

When attempting to connect to a remote [**pmcd**(1)](/pmcd/1.md) on a machine that is booting, **pmReconnectContext** could potentially block for a long time until the remote machine finishes its initialization. **pmReconnectContext** will abort and return an error if the connection has not been established after some specified interval has elapsed.  The default interval is 5 seconds.  This may be modified by setting **PMCD\_CONNECT\_TIMEOUT** in the environment to a real number of seconds for the desired timeout. This is most useful in cases where the remote host is at the end of a slow network, requiring longer latencies to establish the connection correctly.

## CAVEAT

Applications that use [**gethostbyname**(3)](/gethostbyname/3.md) should exercise caution because the static fields in *struct hostent* may not be preserved across some [**PMAPI**(3)](/PMAPI/3.md) calls. In particular, [**pmNewContext**(3)](/pmNewContext/3.md) and [**pmReconnectContext**(3)](/pmReconnectContext/3.md) both may call [**gethostbyname**(3)](/gethostbyname/3.md) internally.

## DIAGNOSTICS

**PM\_ERR\_NOCONTEXT**

-

  *handle* does not identify a valid PMAPI context

**-ETIMEDOUT**

-

  The re-try time has not elapsed, or the reconnection is attempted and fails.

## ENVIRONMENT

- **PMCD\_CONNECT\_TIMEOUT**

  Timeout period (in seconds) for [**pmcd**(1)](/pmcd/1.md) connection attempts.

- **PMCD\_RECONNECT\_TIMEOUT**

  Redefines the back-off intervals - refer to [**PMAPI**(3)](/PMAPI/3.md).

## SEE ALSO

[**pmcd**(1)](/pmcd/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmLoadDerivedConfig**(3)](/pmLoadDerivedConfig/3.md), [**pmNewContext**(3)](/pmNewContext/3.md), [**pmRegisterDerived**(3)](/pmRegisterDerived/3.md), [**pmRegisterDerivedMetric**(3)](/pmRegisterDerivedMetric/3.md) and [**pmUseContext**(3)](/pmUseContext/3.md).