1PMUNITSSTR(3)              Library Functions Manual              PMUNITSSTR(3)
2
3
4

NAME

6       pmUnitsStr,  pmUnitsStr_r - convert a performance metric's units into a
7       string
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       const char *pmUnitsStr(const pmUnits *pu);
13       char *pmUnitsStr_r(const pmUnits *pu, char *buf, int buflen);
14
15       cc ... -lpcp
16

DESCRIPTION

18       The encoding of a performance metric's dimensionality and scale uses  a
19       pmUnits structure; see pmLookupDesc(3).
20
21       As  an  aid  to labeling graphs and tables, or for error messages, pmU‐
22       nitsStr will take a dimension and scale specification as  per  pu,  and
23       return  the  corresponding text string.  The pmUnitsStr_r function does
24       the same, but stores the result in a user-supplied buffer buf of length
25       buflen,  which  should  have  room for at least 60 bytes.  If buflen is
26       less than 60 then pmUnitsStr_r returns NULL and buf is not changed.
27
28       For example {1, -2, 0, PM_SPACE_MBYTE, PM_TIME_SEC, 0}, as the value of
29       *pu gives the result string Mbyte / sec^2.
30
31       The string value result from pmUnitsStr is held in a single static buf‐
32       fer, so the returned value is only valid until the next  call  to  pmU‐
33       nitsStr.
34
35       If  the ``count'' dimension is non-zero, and the ``count'' scale is not
36       zero, then the text string will include a decimal scaling  factor,  eg.
37       count x 10^6.
38
39       As  a  special  case, if all components of the dimension are zero, then
40       the ``count'' scale is used to produce the text.  If this scale is zero
41       the  result  is an empty string, otherwise the result is of the form x1
42       0^2.
43

NOTES

45       pmUnitsStr returns a pointer to  a  static  buffer  and  hence  is  not
46       thread-safe.    Multi-threaded  applications  should  use  pmUnitsStr_r
47       instead.
48

SEE ALSO

50       PMAPI(3),     pmAtomStr(3),     pmConvScale(3),      pmExtractValue(3),
51       pmLookupDesc(3),  pmPrintValue(3),  pmIDStr(3),  pmInDomStr(3), pmType‐
52       Str(3), pmSemStr(3) and pmUnitsStr(3).
53
54
55
56Performance Co-Pilot                  PCP                        PMUNITSSTR(3)
Impressum