PMUNITSSTR(3)

💖 PMUNITSSTR(3) — from the Library Functions Manual, bestie 💖

okay so. this is a page from the Library Functions Manual, and it's about two lil functions — pmUnitsStr and pmUnitsStr_r — that take a performance metric's units and turn them into a string you can actually read. it's giving translator. it's giving glow-up for numbers. 🦋

---

✨ NAME ✨

pmUnitsStr, pmUnitsStr_r — convert a performance metric's units into a string

---

✨ C SYNOPSIS ✨

#include <pcp/pmapi.h>

const char *pmUnitsStr(const pmUnits *pu);
char *pmUnitsStr_r(const pmUnits *pu, char *buf, int buflen);

cc ... -lpcp

link it with -lpcp and you're so good. 🫶

---

✨ DESCRIPTION ✨

so the way a performance metric's dimensionality and scale get encoded? it uses a pmUnits structure — go check pmLookupDesc(3) for the whole lore. 💅

pmUnitsStr is here to help with labeling graphs and tables, or for error messages, and what it does is take a dimension + scale spec as per *pu and hand you back the corresponding text string. iconic behavior.

pmUnitsStr_r does the same exact thing, except it stores the result in a buffer you supply — buf, of length buflen — and that buffer should have room for at least 60 bytes. no cap.

⚠️ if buflen is less than 60, then pmUnitsStr_r returns NULL and buf is not changed. it just ✨refuses✨, respectfully.

for example, {1, -2, 0, PM_SPACE_MBYTE, PM_TIME_SEC, 0} as the value of *pu gives the result string:

Mbyte / sec^2

the string value result from pmUnitsStr is held in a single static buffer, so the returned value is only valid until the next call to pmUnitsStr. 👀 so don't go holding onto it like it's gonna stay. it will not stay. it's a one-call-at-a-time kind of situation.

and if the count'' dimension is non-zero, and the count'' scale is not zero, then the text string will include a decimal scaling factor — like:

count x 10^6

💀

special case alert 🚨 — if all components of the dimension are zero, then the ``count'' scale is used to produce the text. if this scale is zero, the result is an empty string. otherwise the result is of the form:

x1 0^2

periodt.

---

✨ NOTES ✨

pmUnitsStr returns a pointer to a static buffer and hence is not thread-safe. 😭 multi-threaded applications should use pmUnitsStr_r instead — that's literally why it exists, bestie.

---

✨ SEE ALSO ✨

PMAPI(3), pmAtomStr(3), pmConvScale(3), pmExtractValue(3), pmLookupDesc(3), pmPrintValue(3), pmIDStr(3), pmInDomStr(3), pmTypeStr(3), pmSemStr(3) and pmUnitsStr(3).

---

and that's the whole page, bestie!! 🎀 this one came out of the Performance Co-Pilot crew, tagged PCP, and it's page PMUNITSSTR(3) — slay, go format some units, i'm obsessed 💖✨🌸