PMUNPACKEVENTRECORDS(3)

💖 PMUNPACKEVENTRECORDS 💖

okay bestie, welcome to the Library Functions Manual section of the pcp cinematic universe, where we take event records that are all squished together and set them free. it's giving ✨liberation✨

---

🎀 NAME 🎀

pmUnpackHighResEventRecords, pmUnpackEventRecords — unpack event records. yes queen, that's literally the whole job. two functions, one mission, zero drama 💅

---

🌸 C SYNOPSIS 🌸

like here's how you actually call them, copy-paste ready, no notes:

#include <pcp/pmapi.h>

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

cc ... -lpcp

don't forget that -lpcp at the end or the linker will simply end you 🔥

---

🦋 DESCRIPTION 🦋

so here's the tea 🍓: event records are encoded as a packed array of records inside a pmResult, using a container metric with a value of type PM_TYPE_HIGHRES_EVENT, and a pmResult_v2 when you're using a metric with a value of type PM_TYPE_EVENT.

pmUnpackHighResEventRecords and pmUnpackEventRecords are the two besties you call to unpack those event records out of a metric value that's identified by vsp and idx. here's the vibe check on idx:

• if the metric has a singular value, idx should be 0 👑
• otherwise, the ordinal instance value identified by idx gets unpacked, i.e. vsp->vlist[idx] — that one. exactly that one. no cap.

the unpacked records get turned into either pmResult or pmResult_v2 structures, one per event record and one metric per event parameter, and hrap or rap comes back to you as a pointer to an array (NULL pointer terminated) of pointers to those result structures. iconic behavior, honestly 😭

the only difference between the two result types is the timestamp scale:

• pmResult allows for nanosecond precision ⚡
• pmResult_v2 allows for microsecond resolution 🔬

---

✨ the control info situation ✨

some control information from the packed event records gets unpacked into additional ``anonymous'' metrics, and here's the full rundown, no skipping, we don't do that here:

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, which is inserted ahead of all other event parameters. front of the line, main character energy 👑
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 😔 we've all been there

---

🧚 return values, the cute part 🧚

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. 💖

---

🌈 cleanup era 🌈

hrap and the associated pmResult structures may be freed using the convenience function pmFreeHighResEventResult(3). 🫶

similarly, rap and the associated pmResult_v2 structures may be freed using the convenience function pmFreeEventResult(3). 🫶

not me reminding you to free your memory… bestie please free your memory. it's not a want, it's a need 🙈

---

💀 RETURN VALUE 💀

the following errors are possible, and yes we're listing all of them, sit down and sip your strawberry drink 🍓:

• 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. the vibes are off, essentially 💀
• PM_ERR_INST — the value associated with vsp is not singular as expected. it was supposed to be one (1) and it was not.
• PM_ERR_TYPE — vsp is not a value of type PM_TYPE_HIGHRES_EVENT for pmUnpackHighResEventRecords or PM_TYPE_EVENT for pmUnpackEventRecords. wrong type, wrong era, wrong everything.
• 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. negative?? in THIS economy?? 😭
• 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. 🚨 that's the scary one, handle with care
• PM_ERR_TYPE — event parameters must have one of the arithmetic types, else PM_TYPE_AGGREGATE, PM_TYPE_STRING or PM_TYPE_AGGREGATE_STATIC. (yes, PM_ERR_TYPE shows up twice in the original list — we're keeping both, we don't erase history 💅)
• other values < 0 — refer to pmErrStr(3).

---

⭐ SEE ALSO ⭐

PMAPI(3) and pmFreeEventResult(3). go read them, they're lowkey essential, iykyk 📚✨

---

and that's the whole page, bestie — brought to you by Performance Co-Pilot, PCP, on the date stamped in that footer, which we are absolutely not retyping because we're too busy slaying 💜👑💅