PMIGETHANDLE(3)

💖 PMIGETHANDLE 💖

okay bestie, welcome to pmiGetHandle — a lil gem from the Performance Co-Pilot manual pages, section 3 (that's the library-calls girlies, iykyk). she's part of the Log Import squad and she's here to hand you a cute lil key ✨

---

🌸 NAME 🌸

pmiGetHandle — define a handle for a metric-instance pair 🫶

---

✨ C SYNOPSIS ✨

#include <pcp/pmapi.h>
#include <pcp/import.h>

int pmiGetHandle(const char *name, const char *instance);

cc ... -lpcp_import -lpcp

---

🎀 Perl SYNOPSIS 🎀

use PCP::LogImport;

$handle = pmiGetHandle($name, $instance);

---

🦋 Python SYNOPSIS 🦋

from pcp import pmi

handle = log.pmiGetHandle(name, instance)

---

👑 DESCRIPTION 👑

so. this whole function lives inside the Performance Co-Pilot Log Import API (peep LOGIMPORT(3) for the full lore, bestie 💜). and what she does is iconic: pmiGetHandle makes you a handle for a given metric and instance. that handle is literally the return value of the pmiGetHandle call, and you get to reuse it later in your pmiPutValueHandle(3) calls. like, she gave you a VIP wristband and now you skip the line 🎟️✨

the metric's name should match one you already defined earlier in a call to pmiAddMetric(3). don't just make up a name, she WILL notice 💀

now, about the instance situation:

• for singular metrics (the ones defined with an instance domain of PM_INDOM_NULL), instance should be NULL or an empty string. that's it, that's the whole vibe 🙈
• otherwise, instance should match the name of an instance you defined earlier in a call to pmiAddInstance(3) for the metric's instance domain.

and here's the why, because you deserve to know: when you pair this with pmiPutValueHandle(3), using handles gives you a performance improvement over the alternative — which is looking up a metric name and an instance name for every single data value you need for pmiPutValue(3). no cap, that's a glow-up for your loop 🔥

---

🩺 DIAGNOSTICS 🩺

if things go sideways, pmiGetHandle returns a negative value 😭 (not the cute kind). you can turn that sad lil number into an actual error message by calling pmiErrStr(3). always read the error bestie, she's trying to tell you something 💅

---

🌈 SEE ALSO 🌈

• LOGIMPORT(3)
• pmiAddInstance(3)
• pmiAddMetric(3)
• pmiErrStr(3)
• pmiPutValueHandle(3)

---

and that's the page, bestie 🎀 this whole thing comes to you courtesy of Performance Co-Pilot, filed under the PMIGETHANDLE() manual page — go forth, get your handles, and slay ✨💖🦋