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

# pmSetMode(3)

set collection time and mode parameters for the current PMAPI context

## NAME

**pmSetMode** - set collection time and mode parameters for the current PMAPI context

## C SYNOPSIS

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

**int pmSetMode(int** *mode***,** **const struct timespec \****when***,** **const struct timespec \****delta***);**

**cc ... -lpcp**

## DESCRIPTION

**pmSetMode** are used to define the collection time and/or mode for accessing performance metrics and metadata in the current Performance Metrics Application Programming Interface (PMAPI) context. This mode affects the semantics of subsequent calls to the following PMAPI routines: [**pmFetch**(3)](/pmFetch/3.md), [**pmFetchArchive**(3)](/pmFetchArchive/3.md), [**pmLookupDesc**(3)](/pmLookupDesc/3.md), [**pmGetInDom**(3)](/pmGetInDom/3.md), [**pmLookupInDom**(3)](/pmLookupInDom/3.md), [**pmLookupLabels**(3)](/pmLookupLabels/3.md) and [**pmNameInDom**(3)](/pmNameInDom/3.md).

Intended mainly for retrospective analysis of performance metrics from a PCP archive, the options described below allow an application to implement seeking to an arbitrary time within the archive, playback, fast forward, reverse, etc. by alternating calls to **pmSetMode** and [**pmFetch**(3)](/pmFetch/3.md).

If *mode* is **PM\_MODE\_LIVE** then all information is returned from the active pool of performance metrics as of the time that the PMAPI call is made, and the other two parameters to **pmSetMode** (*when* and *delta*) are ignored. **PM\_MODE\_LIVE** is the default mode when a new PMAPI context is created with type **PM\_CONTEXT\_HOST** (i.e. fetching metrics from **pmcd (1))** or **PM\_CONTEXT\_LOCAL**, and this *mode* is rarely used in calls to **pmSetMode**

The other values of *mode* are used with PCP archives where the associated PMAPI context must be of type **PM\_CONTEXT\_ARCHIVE** (when it was created with [**pmNewContext**(3)](/pmNewContext/3.md)) and the *when* parameter defines the current time within the archive. All requests for metric values and metadata (metric descriptions and instance identifiers from the instance domains) will be processed to reflect the state in the archive as of the current time.

When selecting a value for *when*, the time at the start of the archive can be established from the *ll\_start* field in the structure returned from a call to [**pmGetArchiveLabel**(3)](/pmGetArchiveLabel/3.md) or the *start* field in the structure returned from a call to [**pmGetArchiveLabel**(3)](/pmGetArchiveLabel/3.md), and the time at the end of the archive can be established by calling [**pmGetArchiveEnd**(3)](/pmGetArchiveEnd/3.md)

As a special case, if *when* is **NULL** then the *mode* and *delta* arguments are used as described below, but the current time in the archive is not altered.

## TIME-DRIVEN ARCHIVE MODE

If *mode* is **PM\_MODE\_INTERP** then as metric values are retrieved from the archive with [**pmFetch**(3)](/pmFetch/3.md) the current time is returned as the timestamp in the *pmResult* structure and the current time moves on; if *delta* is positive, the current time moves forwards, else the current time moves backwards. The adjustment to the current time is applied even if the [**pmFetch**(3)](/pmFetch/3.md) fails to return values for any metrics or returns an error, e.g. **PM\_ERR\_EOL** because the current time is outside the range defined by the records in the archive.

When metric values are being requested via [**pmFetch**(3)](/pmFetch/3.md) the current time may not exactly match the times at which values have been recorded in the archive, so the returned metric values are computed from the observed metric values in the archive (usually at times close to the current time).

For metrics with semantics of **PM\_SEM\_COUNTER**, the computed value is based on linear interpolation between the last observation before the current time and the first observation after the current time.

For metrics with semantics of **PM\_SEM\_INSTANT** or **PM\_SEM\_DISCRETE**, the computed value is based on values in the neighbourhood of the current time.

The algorithms used in these computations depend on the semantics of the metrics and the time series of observed values in the archive; a fuller explanation may be found in the white paper *Explaining Value Interpolation with PCP Archives* found at **https://pcp.io/papers/archive-interpolation.pdf**.

## RECORD-DRIVEN ARCHIVE MODES

If *mode* is **PM\_MODE\_FORW** or **PM\_MODE\_BACK** then when metric values are being requested via [**pmFetch**(3)](/pmFetch/3.md) the archive will be scanned in a forwards (**PM\_MODE\_FORW**) or backwards (**PM\_MODE\_BACK**) direction in time, until an archive record is encountered with values for **at least one** of the requested metrics. This archive record is used to provide as many of the requested metrics as possible and these are returned with the timestamp if the record in the archive, which becomes the new current time.

Note that any metrics requested via [**pmFetch**(3)](/pmFetch/3.md) that do **not** have a value in the archive record at the new current time will return no values, and so this mode is most useful for archives where all of the metrics of interest have been logged regularly at the same time in the archive. Otherwise, each [**pmFetch**(3)](/pmFetch/3.md) will contain only the subset of the requested metrics and any associated instances found in the qualifying archive record.

The *delta* parameter is ignored, because the current time is driven by the timestamp in the matching archive record. So there is no concept of stepping through the archive in regular time with this mode, although if the requested metrics appear at regular intervals in the archive the current time may advance by regular intervals, but this is serendipitous.

If no qualifying metrics can be found in the requested direction of searching before the end or start of the archive is encountered, then [**pmFetch**(3)](/pmFetch/3.md) returns the special error indicator, **PM\_ERR\_EOL**.

## RECOMMENDATIONS

When processing PCP archives, **PM\_MODE\_INTERP** is preferred because:

- •

  This maximizes the information that will be returned in each [**pmFetch**(3)](/pmFetch/3.md)

- •

  This returns values at regular intervals of the current time, independent of the logging frequency for requested metrics in the archive.

- •

  This works with **any** PCP archive, as opposed to the record-driven modes which may work acceptably for archives with regular logging of all requested metrics, but may fail to report complete or useful results for other archives.

- •

  This mode provides the closest semantic match to **PM\_MODE\_LIVE** and leads to the least user surprise when moving between real-time monitoring and retrospective analysis.

## EXAMPLES

To replay interpolated metrics from an archive at 10 second intervals, the following code fragment could be used:

```
struct timeval mytime;
int mydelta = 10 * 1000;      /* msec */
pmLogLabel label;
pmResult result;
pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
pmGetArchiveLabel(&label);
mytime = label.ll_start;
pmSetMode(PM_MODE_INTERP, &mytime, mydelta)
while (pmFetch(numpmid, pmidlist, &result) != PM_ERR_EOL) {
    /*
     * process interpolated metric values as of
     * result->timestamp
     */
    . . .
    pmFreeResult(result);
}
```

The following code fragment may be used to dump values for selected metrics in an archive in reverse temporal sequence.

```
struct timespec mytime;
pmResult result;
pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
pmGetArchiveEnd(&mytime);
pmSetMode(PM_MODE_BACK, &mytime, NULL);
while (pmFetch(npmid, pmidlist, &result) != PM_ERR_EOL) {
    /*
     * process logged metric values as of result->timestamp
     */
    . . .
    pmFreeResult(result);
}
```

## COMPATIBILITY

Prior to PCP 7.0 the *when* argument was a `struct timeval` and the *delta* argument was an `int` (in units of milliseconds). To support PMAPI transition, the old interface and semantics can be used if applications are recompiled with **-DPMAPI\_VERSION=2**.

For a time in PCP 6.x there was a routine with the same semantics as the current **pmSetMode** called **pmSetModeHighRes** although this is now deprecated and compile-time support for **pmSetModeHighRes** will be removed in a future release.

## DIAGNOSTICS

- **PM\_ERR\_MODE**

  The *mode* parameter is invalid

## SEE ALSO

[**pmcd**(1)](/pmcd/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmFetch**(3)](/pmFetch/3.md), [**pmFetchArchive**(3)](/pmFetchArchive/3.md), [**pmGetArchiveEnd**(3)](/pmGetArchiveEnd/3.md), [**pmGetArchiveLabel**(3)](/pmGetArchiveLabel/3.md), [**pmGetInDom**(3)](/pmGetInDom/3.md), [**pmLookupDesc**(3)](/pmLookupDesc/3.md), [**pmLookupInDom**(3)](/pmLookupInDom/3.md), [**pmLookupLabels**(3)](/pmLookupLabels/3.md), [**pmNameInDom**(3)](/pmNameInDom/3.md) and [**pmNewContext**(3)](/pmNewContext/3.md).