pmunitsstr(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | NOTES | SEE ALSO | COLOPHON

PMUNITSSTR(3)            Library Functions Manual           PMUNITSSTR(3)

NAME         top

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

C SYNOPSIS         top

       #include <pcp/pmapi.h>

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

       cc ... -lpcp

DESCRIPTION         top

       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 fac‐
       tor, 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         top

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

SEE ALSO         top

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

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.   In‐
       formation  about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a  bug  report  for  this  manual  page,  send  it  to
       pcp@groups.io.  This page was obtained from the project's upstream
       Git  repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2025-08-11.  (At that time, the date of  the  most  recent  commit
       that was found in the repository was 2025-08-11.)  If you discover
       any  rendering  problems  in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the  page,
       or you have corrections or improvements to the information in this
       COLOPHON  (which  is not part of the original manual page), send a
       mail to man-pages@man7.org

Performance Co-Pilot               PCP                      PMUNITSSTR(3)

Pages that refer to this page: pmlogsummary(1)pmatomstr(3)pmconvscale(3)pmextractvalue(3)pmidstr(3)pmindomstr(3)pmlookupdesc(3)pmparseunitsstr(3)pmprintvalue(3)pmsemstr(3)pmtypestr(3)pmunitsstr(3)pmwebapi(3)