Man Linux: Main Page and Category List


       pmExtractValue  -  extract  a  performance metric value from a pmResult


       #include <pcp/pmapi.h>

       int  pmExtractValue(int  valfmt,  const  pmValue  *ival,   int   itype,
       pmAtomValue *oval, int otype)

       cc ... -lpcp


       The pmValue structure is embedded within the pmResult structure that is
       used to return one or more performance metrics; see pmFetch(3).

       All performance metric values may be encoded in  a  pmAtomValue  union,
       defined as follows;

            typedef union {
                __int32_t    l;     /* 32-bit signed */
                __uint32_t   ul;    /* 32-bit unsigned */
                __int64_t    ll;    /* 64-bit signed */
                __uint64_t   ull;   /* 64-bit unsigned */
                float        f;     /* 32-bit floating point */
                double       d;     /* 64-bit floating point */
                char         *cp;   /* char ptr */
                void         *vp;   /* void ptr */
            } pmAtomValue;

       The   routine   pmExtractValue  provides  a  convenient  mechanism  for
       extracting values from  the  pmValue  part  of  a  pmResult  structure,
       optionally converting the data type, and making the result available to
       the application programmer.

       itype defines the data type of the input value held in  ival  according
       to  the  storage  format  defined  by  valfmt  (see pmFetch(3)).  otype
       defines the data type of the result to be placed in oval.

       The value for itype is typically extracted  from  a  pmDesc  structure,
       following  a  call  to  pmLookupDesc(3)  for  a  particular performance

       The otype value should be one of the defined PM_TYPE_...  values,  that
       have a 1:1 correspondence with the fields in the pmAtomValue union.

       Normally  the  valfmt parameter would be plucked from the same pmResult
       structure that provides the ival parameter,  and  if  valfmt  specifies
       PM_VAL_INSITU,  then  the  following  types  are  not allowed, as these
       cannot be encoded in 32-bits; __int64_t, __uint64_t, double, char * and
       void  *  (the  corresponding  itype values are PM_TYPE_64, PM_TYPE_U64,
       valfmt  specifies PM_VAL_PTR, then the value will be extracted from the
       associated pmValueBlock structure, and the  __int32_t,  __uint32_t  and
       float  options  (itype  being PM_TYPE_32, PM_TYPE_U32 and PM_TYPE_FLOAT
       respectively) are not allowed,  as  PM_VAL_INSITU  is  the  appropriate
       encoding for these.

       The  following  table  defines  the  various possibilities for the type
       conversion -- the input type  (itype)  is  shown  vertically,  and  the
       output  type  (otype) is shown horizontally.  Y means the conversion is
       always acceptable, N means the conversion can never be  performed  (the
       function returns PM_ERR_CONV), P means the conversion may lose accuracy
       (but no error status is returned), T means the result may be subject to
       high-order truncation (in which case the function returns PM_ERR_TRUNC)
       and S means the conversion may be impossible due to  the  sign  of  the
       input  value  (in  which case the function returns PM_ERR_SIGN).  If an
       error occurs, the value represented by oval will  be  zero  (or  NULL).
       Note  that  although  some  of  the  conversions  involving  the  types
       PM_TYPE_STRING and  PM_TYPE_AGGREGATE  are  indeed  possible,  but  are
       marked  N  -  the  rationale  is  that  pmExtractValue  should  not  be
       attempting to  duplicate  functionality  already  available  in  the  C
       library via sscanf(3S) and sprintf(3S).

              | 32  |  U32  | 64  |  U64  | FLOAT | DBLE | STRING | AGGR |
       32     |  Y  |   S   |  Y  |   S   |   P   |  P   |   N    |  N   |
       U32    |  T  |   Y   |  Y  |   Y   |   P   |  P   |   N    |  N   |
       64     |  T  |  T,S  |  Y  |   S   |   P   |  P   |   N    |  N   |
       U64    |  T  |   T   |  T  |   Y   |   P   |  P   |   N    |  N   |
       FLOAT  | P,T | P,T,S | P,T | P,T,S |   Y   |  Y   |   N    |  N   |
       DBLE   | P,T | P,T,S | P,T | P,T,S |   P   |  Y   |   N    |  N   |
       STRING |  N  |   N   |  N  |   N   |   N   |  N   |   Y    |  N   |
       AGGR   |  N  |   N   |  N  |   N   |   N   |  N   |   N    |  Y   |

       In  the  cases  where multiple conversion errors could occur, the first
       encountered error will be notified, and the order of  checking  is  not

       If  the output conversion is to one of the pointer types, i.e. otype is
       PM_TYPE_STRING or PM_TYPE_AGGREGATE, then the value  buffer  will  have
       been  allocated  by  pmExtractValue(3)  using malloc(3C), and it is the
       caller’s responsibility  to  free  the  space  when  it  is  no  longer

       Although  this function appears rather complex, it has been constructed
       to assist the development of performance tools  that  wish  to  convert
       values,  whose  type  is  only  known  via  the  type field in a pmDesc
       structure, into a canonical type for local processing.


       PMAPI(3), pmAtomStr(3),  pmConvScale(3),  pmFetch(3),  pmLookupDesc(3),
       pmPrintValue(3), pmTypeStr(3) and pmUnitsStr(3).



              Impossible conversion, marked by N in above table


              High-order truncation occurred


              Conversion of negative value to unsigned type attempted