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

# pmGetArchiveLabel(3)

fetch the label record from a set of performance metrics archives

## NAME

**pmGetArchiveLabel** - fetch the label record from a set of performance metrics archives

## C SYNOPSIS

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

**int pmGetArchiveLabel(pmLogLabel \****lp***);**

**cc ... -lpcp**

## DESCRIPTION

Within the framework of the Performance Co-Pilot (PCP), archives of performance metrics values may be accumulated and saved using the program [**pmlogger**(1)](/pmlogger/1.md) and the [**LOGIMPORT**(3)](/LOGIMPORT/3.md) programming interface.

The routines **pmGetArchiveLabel** may be used to fetch the label record from a set of archives that has already been opened using [**pmNewContext**(3)](/pmNewContext/3.md), or [**pmDupContext**(3)](/pmDupContext/3.md), and thereby associated with the current Performance Metrics Application Programming Interface (PMAPI) context.

The result returned via the pointer *lp* is a structure that must be pre-allocated by the caller and has the following format (defined in **pmapi.h**).

```
typedef struct {
  int        magic;       /* PM_LOG_MAGIC | archive format version no. */
  pid_t      pid;         /* PID of logger */
  struct timespec start;  /* start of this archive */
  char       hostname[PM_MAX_HOSTNAMELEN];   /* collection host full name */
  char       timezone[PM_MAX_TIMEZONELEN];   /* generic, squashed $TZ */
  char       zoneinfo[PM_MAX_ZONEINFOLEN];   /* local platform $TZ */
} pmLogLabel;
```

**pmGetArchiveLabel** can be used with either version 2 or version 3 archives, however some mapping may be required with the older version 2 archives, e.g. the *start* time only has microsecond resolution and the *zoneinfo* field is not present. For detailed information about the archive on-disk format, refer to [**LOGARCHIVE**(5)](/LOGARCHIVE/5.md).

For an application using **pmGetArchiveLabel**, the most useful information from the archive label is likely to be in the fields *start*, *hostname*, *timezone*, and *zoneinfo*.

The *zoneinfo* field contains the most detailed timezone information available, and should be used if present (non-zero length string). It will only not be present in the case of version 2 archives - this is a new field added as part of the version 3 format. The *timezone* field will always be present, however it is the 'squashed' timezone value and in certain situations is not the most accurate timezone.

For older applications using **pmGetArchiveLabel**, the most useful information from the archive label is likely to be in the fields *ll\_start*, *ll\_hostname* or *ll\_tz*. Note that the size of the *ll\_hostname* field is *PM\_LOG\_MAXHOSTLEN* (64 bytes) which is less than **MAXHOSTNAMELEN** (see [**gethostbyname**(3)](/gethostbyname/3.md)) on some platforms. These semantics are necessary to retain backwards compatibility with the PCP archive file format.

**pmGetArchiveLabel** return zero for success.

## COMPATIBILITY

Prior to PCP 7.0 and *libpcp.so.4* the *pmLogLabel* structure was somewhat different. To support PMAPI transition, the old interface and semantics can be used if applications are linked with *libpcp.so.3* or recompiled with **-DPMAPI\_VERSION=2**.

For a time in PCP 6.x there was a routine with the same semantics as the current **pmGetArchiveLabel** called **pmGetHighResArchiveLabel** and a structure with same definition as *pmLogLabel* called *pmHighResLogLabel* although these are now deprecated and compile-time support for **pmGetHighResArchiveLabel** and *pmHighResLogLabel* will be removed in a future release.

## DIAGNOSTICS

- **PM\_ERR\_NOCONTEXT**

  the current PMAPI context is either invalid, or not associated with a set of archives

## PCP ENVIRONMENT

Environment variables with the prefix **PCP\_** are used to parameterize the file and directory names used by PCP. On each installation, the file */etc/pcp.conf* contains the local values for these variables. The **$PCP\_CONF** variable may be used to specify an alternative configuration file, as described in [**pcp.conf**(5)](/pcp.conf/5.md). Values for these variables may be obtained programmatically using the [**pmGetConfig**(3)](/pmGetConfig/3.md) function.

## SEE ALSO

[**pmlogger**(1)](/pmlogger/1.md), [**LOGIMPORT**(3)](/LOGIMPORT/3.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmDupContext**(3)](/pmDupContext/3.md), [**pmGetConfig**(3)](/pmGetConfig/3.md), [**pmNewContext**(3)](/pmNewContext/3.md), [**LOGARCHIVE**(5)](/LOGARCHIVE/5.md), [**pcp.conf**(5)](/pcp.conf/5.md) and [**pcp.env**(5)](/pcp.env/5.md).