# pmparseunitsstr

## NAME



           **pmParseUnitsStr** - parse units specification
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **int pmParseUnitsStr(const char ***_string_**, struct pmUnits ***_out_**,**
                               **double ***_outMult_**, char ****_errMsg_**);**
    
           **cc ... -lpcp**
    


## DESCRIPTION



           **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



           ┌───────────────────────────────────┬────────────────┬─────────┐
           │              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



           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



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


* * *