pmparseunitsstr(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | EXAMPLES | BUGS | RETURN VALUE | SEE ALSO | COLOPHON

PMPARSEUNITSSTR(3)      Library Functions Manual      PMPARSEUNITSSTR(3)

NAME         top

       pmParseUnitsStr - parse units specification

C SYNOPSIS         top

       #include <pcp/pmapi.h>

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

       cc ... -lpcp

DESCRIPTION         top

       pmParseUnitsStr  is designed to encapsulate the interpretation of
       a units (dimension  and  scale)  specification  in  command  line
       switches for use by the PCP client tools.

       This function expects to be called with the unit/scale specifica‐
       tion  as  string.  This specification takes the general form pro‐
       duced by pmUnitsStr(3).  Briefly, the format  allows  /-separated
       divisor   and   dividend,  each  listing  space-separated  dimen‐
       sions/scales along the space, time, and count  axes.   There  are
       also a few extra possibilities:

       First,  multiple equivalent sets of keywords are accepted for the
       time and space dimensions, insensitive  to  case.   For  example,
       "microseconds",  "microsecond",  "microsec",  "us" are considered
       synonymous, as are "kilobytes", "KB", "KiB", "kiloByte",  and  so
       on.

       Second,  units  may  be offered in any order, e.g., ms kb count x
       10^3 or count x 10^3 kb ms.  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 are fac‐
       tored together with implicit scale  conversions  into  the  final
       outMult result.

       The  out and outMult values must both be allocated before calling
       pmParseUnitsStr(3).  If the conversion is  successful,  pmParseU‐
       nitsStr  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, it returns a negative status code.

EXAMPLES         top

       ┌───────────────────────────────────┬────────────────┬─────────┐
       │              string               │      out       │ outMult │
       ├───────────────────────────────────┼────────────────┼─────────┤
       │ 2 count                           │ {0,1,0,0,0,0}  │ 0.5     │
       │ count / 7.5 nanosecond            │ {0,1,-1,0,0,0} │ 7.5     │
       │ 10 kilobytes / 2.5e2 count x 10^3 │ {1,-1,0,1,3,0} │ 25      │
       │ millisecond / second^2            │ {0,0,-1,0,0,3} │ 1000    │
       │ mib/s                             │ {1,0,-1,2,0,3} │ 1       │
       └───────────────────────────────────┴────────────────┴─────────┘

BUGS         top

       For  backward  compatibility,  this  interface interprets several
       traditional computer science interpretations of space  units  in‐
       correctly  according  to  the  International System of Units (SI)
       standard.

       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 re‐
       ally tebibyte), petabyte (is really pebibyte), exabyte (is really
       exbibyte), zettabyte (is really zebibyte) and yottabyte (is real‐
       ly yobibyte).

RETURN VALUE         top

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

SEE ALSO         top

       PMAPI(3), pmUnitsStr(3), pmConvScale(3), and pmLookupDesc(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   2024-06-14.
       (At  that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  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                PMPARSEUNITSSTR(3)

Pages that refer to this page: pcp2elasticsearch(1)pcp2graphite(1)pcp2influxdb(1)pcp2json(1)pcp2openmetrics(1)pcp2spark(1)pcp2template(1)pcp2xlsx(1)pcp2xml(1)pcp2zabbix(1)pmdaopenmetrics(1)pmrep(1)pmfetchgroup(3)pmparseunitsstr(3)pmregisterderived(3)