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

# pmUnpackHighResEventRecords(3)

unpack event records

## NAME

**pmUnpackHighResEventRecords**, **pmUnpackEventRecords** - unpack event records

## C SYNOPSIS

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

**int pmUnpackHighResEventRecords(pmValueSet \****vsp***,** **int** *idx***,** **pmResult \*\*\****hrap***);**\
 **int pmUnpackEventRecords(pmValueSet \****vsp***,** **int** *idx***,** **pmResult\_v2 \*\*\****rap***);**

**cc ... -lpcp**

## DESCRIPTION

Event records are encoded as a packed array of records within a *pmResult* using a container metric with a value of type **PM\_TYPE\_HIGHRES\_EVENT** and a *pmResult\_v2* when using a metric with a value of type **PM\_TYPE\_EVENT**.

**pmUnpackHighResEventRecords** and **pmUnpackEventRecords** may be used to unpack event records from a metric value identified by *vsp* and *idx*. If the metric has a singular value, *idx* should be 0, else the ordinal instance value identified by *idx* will be unpacked, i.e. vsp-\>vlist\[idx\]. The unpacked records are turned into either *pmResult* or *pmResult\_v2* structures, one per event record and one metric per event parameter, and *hrap* or *rap* is returned as a pointer to an array (NULL pointer terminated) of pointers to the result structures.

The only difference between the two result types is the timestamp scale; the *pmResult* allows for nanosecond precision, whereas *pmResult\_v2* allows for microsecond resolution.

Some control information from the packed event records is unpacked into additional \`\`anonymous'' metrics as follows:

- 1\.

  If the event record has a non-zero flags value, then the corresponding *pmResult*/*pmResult\_v2* will have the flags value encoded with the additional metric **event.flags** that is inserted ahead of all other event parameters.

- 2\.

  If the event record flag is set to **PM\_EVENT\_FLAG\_MISSED**, then the corresponding *pmResult*/*pmResult\_v2* will have one metric **event.missed** with a value that equals the number of event records \`\`missed'' because either the PMDA could not keep up, or the PMAPI client did not collect the event records fast enough.

**pmUnpackHighResEventRecords** returns the number of *pmResult* structures as the return value, which is \>= 0 for success. Similarly, **pmUnpackEventRecords** returns the number of *pmResult\_v2* structures as the return value, which is \>= 0 for success.

*hrap* and the associated *pmResult* structures may be freed using the convenience function [**pmFreeHighResEventResult**(3)](/pmFreeHighResEventResult/3.md).

Similarly, *rap* and the associated *pmResult\_v2* structures may be freed using the convenience function [**pmFreeEventResult**(3)](/pmFreeEventResult/3.md).

## RETURN VALUE

The following errors are possible:

- PM\_ERR\_CONV

  The values associated with *vsp* are not encoded using the format PM\_VAL\_DPTR or PM\_VAL\_SPTR, or the flags at the head of the event record has an unexpected value.

- PM\_ERR\_INST

  The value associated with *vsp* is not singular as expected.

- PM\_ERR\_TYPE

  *vsp* is not a value of type **PM\_TYPE\_HIGHRES\_EVENT** for **pmUnpackHighResEventRecords** or **PM\_TYPE\_EVENT** for **pmUnpackEventRecords**.

- PM\_ERR\_TOOSMALL

  The value identified by *vsp* is not legal because the value length is less than the minimum size, or the number of event records encoded in the (value header) *pmHighResEventArray*/*pmEventArray* structure is negative, or the number of missed event records in the array is negative.

- PM\_ERR\_TOOBIG

  Either **vsp** indicates more than one value is present (all the event records are expected to be packed in a single metric value), or when unpacking the event records, the processing continues past the end of the enclosing value.  Indicates corruption of the packed event record.

- PM\_ERR\_TYPE

  Event parameters must have one of the arithmetic types, else **PM\_TYPE\_AGGREGATE**, **PM\_TYPE\_STRING** or **PM\_TYPE\_AGGREGATE\_STATIC**.

- other values \< 0

  refer to [**pmErrStr**(3)](/pmErrStr/3.md).

## SEE ALSO

[**PMAPI**(3)](/PMAPI/3.md) and [**pmFreeEventResult**(3)](/pmFreeEventResult/3.md).