Movatterモバイル変換

pmparseunitsstr(3) — Linux manual page

PMPARSEUNITSSTR(3)       Library Functions ManualPMPARSEUNITSSTR(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

pmParseUnitsStris 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 asstring.  This specification takes the  general  form  pro‐       duced  bypmUnitsStr(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 x10^3orcount 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 finalout‐Mult result.       Theout andoutMult values must both be allocated  before  callingpmParseUnitsStr(3).   If  the  conversion is successful,pmParseU‐nitsStrreturns  0,  and  fills  inoutandoutMultwith  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       thepmParseUnitsStrinterpretation for each are:megabyte(is  re‐       allymebibyte),gigabyte(is reallygibibyte),terabyte(is reallytebibyte),petabyte(is  reallypebibyte),exabyte(is reallyexbibyte),zettabyte(is reallyzebibyte) andyottabyte(is reallyyobibyte).

RETURN VALUE        top

       A zero status indicates success.  A negative status  indicates  an       error, in which case theerrMsg pointer will contain a textual er‐       ror message, which the caller should laterfree(3).

SEE ALSO        top

PMAPI(3),pmUnitsStr(3),pmConvScale(3), andpmLookupDesc(3).

COLOPHON        top

       This  page is part of thePCP (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 isnot part of the original manual page),  send  a       mail to man-pages@man7.orgPerformance Co-Pilot               PCPPMPARSEUNITSSTR(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)

HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH.