PMPARSEUNITSSTR(3)

🎀 pmParseUnitsStr — the Library Functions Manual glow-up 🎀

okay bestie, so this one lives in the PCP Library Functions Manual, and it's literally the function that reads units for you. no cap.

---

✨ NAME ✨

pmParseUnitsStr — parse units specification 🦋

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmapi.h>

int pmParseUnitsStr(const char *string, struct pmUnits *out,
                    double *outMult, char **errMsg);

cc ... -lpcp

---

💅 DESCRIPTION 💅

So pmParseUnitsStr is the girl whose whole job is to encapsulate the interpretation of a units (dimension and scale) specification inside command line switches, for all the PCP client tools to use. she's the translator, the vibe-checker, the main character of unit parsing 💖

You call her with the unit/scale spec sitting in string. That spec takes the general form that pmUnitsStr(3) produces. briefly: the format lets you have a /-separated divisor and dividend, and each one lists space-separated dimensions/scales along the space, time, and count axes. iconic honestly.

and then there's a few extra possibilities that are lowkey the best part:

• First — multiple equivalent sets of keywords are accepted for the time and space dimensions, and it's insensitive to case. so for example "microseconds", "microsecond", "microsec", "us" are all considered synonymous. same energy for "kilobytes", "KB", "KiB", "kiloByte", and so on. pick your fighter, they all slay 💅
• Second — units may be offered in any order, e.g. ms kb count x 10^3 or count x 10^3 kb ms. the way that she doesn't care about your ordering? obsessed. but — and this is the catch — they may not be repeated within the denominator or within the numerator. each scale/unit keyword may be immediately followed by positive or negative exponents, e.g. ^-4. 🫶
• Third — numerical scaling factors may be supplied. these get factored together with implicit scale conversions into the final outMult result. ✨

heads up bestie: the out and outMult values must both be allocated before calling pmParseUnitsStr(3). no allocating mid-call, that's not the vibe.

if the conversion is successful, pmParseUnitsStr returns 0, and fills in out and outMult with the unit/scales defined by the input parameter. 🌈

if the argument strings could not be parsed, she returns a negative status code. it's giving "not today." 💀

---

🔥 EXAMPLES 🔥

here's the receipts, bestie — string goes in, out and outMult come out:

• 2 count → out is {0,1,0,0,0,0}, outMult is 0.5
• count / 7.5 nanosecond → out is {0,1,-1,0,0,0}, outMult is 7.5
• 10 kilobytes / 2.5e2 count x 10^3 → out is {1,-1,0,1,3,0}, outMult is 25
• millisecond / second^2 → out is {0,0,-1,0,0,3}, outMult is 1000
• mib/s → out is {1,0,-1,2,0,3}, outMult is 1

---

💀 BUGS 💀

okay so for backward compatibility, this interface interprets several traditional computer science interpretations of space units incorrectly according to the International System of Units (SI) standard. it's giving ✨chaos✨ and not the fun kind. 🙈

the accepted unit string — in either singular or plural form — and the pmParseUnitsStr interpretation for each are:

• megabyte (is really mebibyte)
• gigabyte (is really gibibyte)
• terabyte (is really tebibyte)
• petabyte (is really pebibyte)
• exabyte (is really exbibyte)
• zettabyte (is really zebibyte)
• yottabyte (is really yobibyte)

so yeah. she's lying to you about bytes. knowingly. for legacy reasons. 😭

---

⭐ RETURN VALUE ⭐

• A zero status indicates success. 🎉
• A negative status indicates an error — in which case the errMsg pointer will contain a textual error message, which the caller should later free(3). don't forget the free bestie, that's a leak otherwise 💅

---

🦋 SEE ALSO 🦋

PMAPI(3), pmUnitsStr(3), pmConvScale(3), and pmLookupDesc(3). go read them, they're all part of the same friend group 🫶

---

and that's the whole page, babe ✨ this one's from Performance Co-Pilot, aka PCP, and it's the PMPARSEUNITSSTR(3) page — so go parse some units, allocate your out and outMult first, and free your errMsg like the responsible icon you are. periodt. 💖