PMPARSEMETRICSPEC(3)

✨ PMPARSEMETRICSPEC(3) ✨

okay bestie, so this one is pmParseMetricSpec and pmFreeMetricSpec from the Library Functions Manual — the uniform metric specification parser 💅 she's a libpcp girlie, part of the PCP (Performance Co-Pilot) situation, and honestly? she ate.

---

🎀 NAME 🎀

pmParseMetricSpec, pmFreeMetricSpec — uniform metric specification parser. yes that's the whole name section, no notes, periodt ✨

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmapi.h>

int pmParseMetricSpec(const char *string, int isarch, char *source,
                      pmMetricSpec **rsltp, char **errmsg);
void pmFreeMetricSpec(pmMetricSpec *rslt);

cc ... -lpcp

like, you gotta link -lpcp or she simply will not show up. non-negotiable 🫶

---

💖 DESCRIPTION 💖

so pmParseMetricSpec takes a string that names a PCP performance metric, and optionally the source for it — which is either a hostname or a PCP archive filename — plus the instances for that metric. the whole syntax vibe is described over in PCPIntro(1), go check her out 🔥

if you don't provide either the host or the archive component in your metric spec, then the isarch and source arguments get used to fill in the returned pmMetricSpec structure instead. it's giving "we got you, bestie, we'll fill in the blanks" 💖

---

🦋 the struct 🦋

the pmMetricSpec structure that comes back to you via rsltp represents the parsed string, and her declaration is literally this:

typedef struct {
    int     isarch;      /* source type: 0 -> live host, 1 -> archive, 2 -> local context */
    char    *source;     /* name of source host or archive */
    char    *metric;     /* name of metric */
    int     ninst;       /* number of instances, 0 -> all */
    char    *inst[1];    /* array of instance names */
} pmMetricSpec;

look at her. isarch is doing main character work: 0 means live host, 1 means archive, 2 means local context. ninst being 0 means all the instances, and inst[1] is the array of instance names, iykyk 👑

---

💅 what she returns 💅

pmParseMetricSpec returns 0 if the given string was successfully parsed. slay. in that case, literally all the storage allocated by pmParseMetricSpec can be released with a single call to free(3) using the address returned from pmMetricSpec via rsltp. one call. that's it. the convenience macro pmFreeMetricSpec is, and I quote, a thinly disguised wrapper for free(3) — she's not doing anything fancy, she's just free(3) in a cute little outfit 🎀

if the given string does not parse, pmParseMetricSpec returns PM_ERR_GENERIC and hands you a dynamically allocated error message string in errmsg. and bestie, you must free(3) that error message string in this situation. don't leave her hanging 😭

⚠️ undefined-behaviour check, and this is important so listen up: in the case of an error, rsltp is undefined. in the case of success, errmsg is undefined. and if rsltp->ninst is 0, then rsltp->inst[0] is undefined. do not go poking at those, fr fr 💀

---

🌈 SEE ALSO 🌈

• PMAPI(3)
• pmLookupName(3)

---

Performance Co-Pilot · PCP · PMPARSEMETRICSPEC(3) — that's the source, the version and the date, all wrapped up with a bow 🎀✨ thanks for reading, mwah 💖🦋🌸