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

# pmFetchArchive(3)

get performance metric values directly from archives

## NAME

**pmFetchArchive**, - get performance metric values directly from archives

## C SYNOPSIS

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

**int pmFetchArchive(pmResult \*\****result***);**

**cc ... -lpcp**

## DESCRIPTION

The **pmFetchArchive** API is a variant of the [**pmFetch**(3)](/pmFetch/3.md) interface that may only be used when the current Performance Metrics Application Programming Interface (PMAPI) context is associated with a set of archives.

The *result* is instantiated with all of the metrics (and instances) from the next archive record, consequently there is no notion of a list of desired metrics, and the instance profile of the PMAPI context is ignored.

**pmFetchArchive** may return a *result* in which *numpmid* is zero. This is a *\<mark\>* record that indicates a temporal discontinuity in the time series of performance metrics. This can happen at the boundary between archives in a set or if the archive associated with the current PMAPI context was created using [**pmlogextract**(1)](/pmlogextract/1.md) to concatenate two or more PCP archives, and the *\<mark\>* record marks a point in time between the end of one input archive and the start of the next input archive.

It is expected that **pmFetchArchive** will be used to create utilities that scan sets of archives, while the more common access to the archives would be via the **pmFetch** interface.

To skip records within the set of archives, use [**pmSetMode**(3)](/pmSetMode/3.md) to change the collection time within the current PMAPI context, then call either **pmFetchArchive**

Note that the *result* returned by **pmFetchArchive** is dynamically allocated, and must be released using [**pmFreeResult**(3)](/pmFreeResult/3.md), but not [**free**(3)](/free/3.md). See [**pmFetch**(3)](/pmFetch/3.md), and [**pmFreeResult**(3)](/pmFreeResult/3.md) for further details.

**pmFetchArchive** returns zero on success.

## DIAGNOSTICS

- **PM\_ERR\_NOTARCHIVE**

  the current PMAPI context is not associated with a set of archives

## COMPATIBILITY

Prior to PCP 7.0 the *timestamp* field in the `pmResult` struct was a `struct timeval`. 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 **pmFetchArchive** called **pmFetchHighResArchive**, and a struct with the same definition as the current `pmResult` struct called `pmResultHighRes`, although both are now deprecated and compile-time support for **pmFetchHighResArchive** and `pmResultHighRes` will be removed in a future release.

## SEE ALSO

[**PMAPI**(3)](/PMAPI/3.md), [**pmFetch**(3)](/pmFetch/3.md), [**pmFreeResult**(3)](/pmFreeResult/3.md), [**pmNewContext**(3)](/pmNewContext/3.md), [**pmSetMode**(3)](/pmSetMode/3.md) and [**pmTrimNameSpace**(3)](/pmTrimNameSpace/3.md).