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).
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, eg. 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), pmAtomStr(3), pmConvScale(3), pmExtractValue(3), pmLookupDesc(3), pmPrintValue(3), pmIDStr(3), pmInDomStr(3), pmTypeStr(3), pmSemStr(3) and pmUnitsStr(3).
Referenced By
pmAtomStr(3), pmConvScale(3), pmExtractValue(3), pmIDStr(3), pmInDomStr(3), pmlogsummary(1), pmLookupDesc(3), pmParseUnitsStr(3), pmPrintValue(3), pmSemStr(3), pmTypeStr(3), PMWEBAPI(3).
The man pages pmunitsstr(3) and pmUnitsStr_r(3) are aliases of pmUnitsStr(3).