---
name: "pmUnitsStr"
section: "3"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pmUnitsStr"
---

# pmUnitsStr(3)

convert a performance metric's units into a string

## 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**

## DESCRIPTION

The encoding of a performance metric's dimensionality and scale uses a *pmUnits* structure; see [**pmLookupDesc**(3)](/pmLookupDesc/3.md).

As an aid to labeling graphs and tables, or for error messages, **pmUnitsStr** will take a dimension and scale specification as per *pu*, and return the corresponding text string. The **pmUnitsStr\_r** function does the same, but stores the result in a user-supplied buffer *buf* of length *buflen*, which should have room for at least 60 bytes. If *buflen* is less than 60 then **pmUnitsStr\_r** returns **NULL** and *buf* is not changed.

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**.

If the \`\`count'' dimension is non-zero, and the \`\`count'' scale is not zero, then the text string will include a decimal scaling factor, e.g. *count x 10^6*.

As a special case, 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*.

## NOTES

**pmUnitsStr** returns a pointer to a static buffer and hence is not thread-safe. Multi-threaded applications should use **pmUnitsStr\_r** instead.

## SEE ALSO

[**PMAPI**(3)](/PMAPI/3.md), [**pmAtomStr**(3)](/pmAtomStr/3.md), [**pmConvScale**(3)](/pmConvScale/3.md), [**pmExtractValue**(3)](/pmExtractValue/3.md), [**pmLookupDesc**(3)](/pmLookupDesc/3.md), [**pmPrintValue**(3)](/pmPrintValue/3.md), [**pmIDStr**(3)](/pmIDStr/3.md), [**pmInDomStr**(3)](/pmInDomStr/3.md), [**pmTypeStr**(3)](/pmTypeStr/3.md), [**pmSemStr**(3)](/pmSemStr/3.md) and [**pmUnitsStr**(3)](/pmUnitsStr/3.md).