PMADDDERIVEDTEXT(3)

💖 PMADDDERIVEDTEXT(3) — the pmAddDerivedText era 💖

okay bestie, sit down, hydrate, because today we're talking about Performance Co-Pilot's very own pmAddDerivedText from the Library Functions Manual, and honestly? it's giving "tiny function, big feelings" 🎀

---

✨ NAME ✨

pmAddDerivedText — add help text for a derived metric 🫶

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmapi.h>

int pmAddDerivedText(const char *name, int type, const char *text);

cc ... -lpcp

no cap, that's the whole signature. three args, one int back, and the cc ... -lpcp at the bottom is your little reminder to link against libpcp or literally nothing works 💅

---

🦋 DESCRIPTION 🦋

okay so first, the lore. Derived metrics are how you extend the Performance Metrics Name Space (PMNS) with brand new metrics that you define on the PCP client-side, using expressions over the performance metrics that already exist. it's like DIY but for metrics. iconic behavior ✨

so the derived metrics come into existence in two flavors:

• Global derived metrics — defined using pmRegisterDerived(3) or pmRegisterDerivedMetric(3) or pmLoadDerivedConfig(3)
• Per-context derived metrics — defined using pmAddDerived(3) or pmAddDerivedMetric(3)

once a derived metric has been defined, pmAddDerivedText is the girl you call to associate help text with the derived metric identified by name. like, now your metric has a little bio. a blurb. a whole personality 🌈

and the help text can be either vibe:

• a "one line" summary — pass type as PM_TEXT_ONELINE
• a more verbose "multi-line" block of text — pass type as PM_TEXT_HELP

and yes, you can absolutely have both. to associate both styles of help text with a derived metric, you'd call pmAddDerivedText twice with different values for type. two calls, two texts, one very well-documented metric 👑

⚠️ okay important: once a particular type of help text has been associated with a derived metric, it cannot be deleted or redefined. periodt. so get it right the first time, bestie 😭

lastly, apps using the Performance Metrics Application Programming Interface (PMAPI) can retrieve help text for specific metrics using pmLookupText(3). so all that text you added? it's findable. it's living its best life. it's searchable 💖

---

🎀 DIAGNOSTICS 🎀

pmAddDerivedText returns zero on success, else an error code. so zero = slay, anything else = read the room (and the error code).

• PM_ERR_NAME — this means name does not correspond to a previously defined derived metric. like, you're calling for a metric that doesn't exist yet. define it first, babe 🙈
• PM_ERR_TEXT — repeated calls for the same name and type will result in this return value. you already gave it a bio, stop rewriting it 💀
• PM_ERR_ARG — this means type is not one of the expected values. it's not PM_TEXT_ONELINE, it's not PM_TEXT_HELP, it's just wrong. vibe check failed 🚫

---

🌟 SEE ALSO 🌟

PCPIntro(1), pmAddDerived(3), pmAddDerivedMetric(3), PMAPI(3), pmLoadDerivedConfig(3), pmLookupText(3), pmRegisterDerived(3), pmRegisterDerivedMetric(3) and PMNS(5).

---

and that's the whole page, bestie!! this manual page came to you courtesy of Performance Co-Pilot — PMADDDERIVEDTEXT(3), Library Functions Manual, out here doing the absolute most so your derived metrics can have help text like the main characters they are 💜✨ go add some text, you've got this, iykyk 🫶