pmparseunitsstr(3) — Linux manual page

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 al‐
       so a few extra possibilities:

       First,  multiple  equivalent sets of keywords are accepted for the
       time and space dimensions, insensitive to case.  For example, "mi‐
       croseconds", "microsecond", "microsec", "us" are  considered  syn‐
       onymous, 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 out‐
       Mult 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 tra‐
       ditional computer science interpretations of  space  units  incor‐
       rectly  according  to the International System of Units (SI) stan‐
       dard.

       The accepted unit string - in either singular or plural form - and
       the pmParseUnitsStr interpretation for each are: megabyte (is  re‐
       ally mebibyte), gigabyte (is really gibibyte), terabyte (is really
       tebibyte),  petabyte  (is  really  pebibyte),  exabyte  (is really
       exbibyte), zettabyte (is really zebibyte) and yottabyte (is really
       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 er‐
       ror 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
       2026-05-24.   (At  that  time,  the date of the most recent commit
       that was found in the repository was 2026-05-24.)  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),  pcp2opentelemetry(1),  pcp2spark(1),  pcp2template(1),  pcp2xlsx(1),  pcp2xml(1),  pcp2zabbix(1),  pmdaopenmetrics(1),  pmdaopentelemetry(1),  pmrep(1),  pmfetchgroup(3),  pmparseunitsstr(3),  pmregisterderived(3)

HTML rendering created 2026-05-30 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH.