PMSTORE(3)

💖 PMSTORE(3) — the modify your metrics page, bestie 💖

okay so welcome to pmStore, straight out of the Library Functions Manual ✨ this is the one where you get to change the values of performance metrics and honestly? iconic.

---

🌸 NAME 🌸

pmStore — modify values of performance metrics 💅

---

✨ C SYNOPSIS ✨

#include <pcp/pmapi.h>

int pmStore(const pmResult *result);

cc ... -lpcp

like yes that's the whole vibe, short and slay 🎀

---

🦋 DESCRIPTION 🦋

so. in some special cases it may be helpful to modify the current values of performance metrics, okay? like resetting a counter to zero, or changing a “metric” that's actually a control variable for some agent out there collecting performance metrics. it's giving main character energy for control freaks (affectionate) 😌

pmStore is literally a lightweight inverse of pmFetch(3). no cap. 🔥

you, the caller, have to build the result data structure yourself — and yeah, of course it could have been handed to you by an earlier pmFetch(3) call, that's totally valid 💖

⚠️ it is an error to pass a result to pmStore where the numval field inside any of the pmValueSet structures has a value less than one. not a vibe. don't do it. 😭

the current Performance Metrics Application Programming Interface (PMAPI) context has to be one with a host as the source of metrics, and the current value of the nominated metrics will get changed. which means — and this is the important part bestie — pmStore cannot be used to make retrospective changes to information in either the archives, or in the recent past for real-time sources of metrics. no time travel, sorry 🕰️💀

the return code from pmStore is zero for success ✨ periodt.

---

🎀 DIAGNOSTICS 🎀

• PM_ERR_GENERIC — at least one of the modifications was rejected. and here's the tea: no other status is available from below the PMAPI (this is the lightweight part of the functionality!). so if the outcome of storing into individual metrics actually matters to you, the caller should make one call to either pmStore for each metric. on the other hand, if you're in a situation where the outcome is not critical, a bulk modification can be performed in a single call 🫶
• PM_ERR_NOTHOST — the current PMAPI context is an archive rather than a host, or it's a host that is not set to the current time, i.e. it's been “rewound” to the recent past using pmSetMode(3). rewound?? not the time machine arc 😭
• PM_ERR_TOOSMALL — the number of metrics specified in result is less than one. zero metrics is not a moment, it's an error 💀
• PM_ERR_VALUE — one or more of the pmValueSets in result has a numval field with a value less than one 🙈

---

🌈 COMPATIBILITY 🌈

okay history lesson, stay with me 🧚

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 still be used if applications are recompiled with -DPMAPI_VERSION=2 ✨

and for a time in PCP 6.x there was a routine with the same semantics as the current pmStore called pmStoreHighRes, plus a struct with the same definition as the current pmResult struct called pmResultHighRes. however 💀 both are now deprecated, and compile-time support for pmStoreHighRes and pmResultHighRes will be removed in a future release. so like, don't get attached bestie 🥲

---

💜 SEE ALSO 💜

• PMAPI(3)
• pmFetch(3)
• pmSetMode(3)

---

and that's the whole page, bestie 🫶 this gem came to you from Performance Co-Pilot — that's the PCP crew — and yeah, the page is literally named PMSTORE(3) so you'll always know where to find it 💖 bye ily, go reset a counter responsibly ✨🎀🦋