pmextractvalue(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | DIAGNOSTICS | SEE ALSO | COLOPHON

PMEXTRACTVALUE(3)       Library Functions Manual       PMEXTRACTVALUE(3)

NAME         top

       pmExtractValue - extract a performance metric value from a
       pmResult structure

C SYNOPSIS         top

       #include <pcp/pmapi.h>

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

       cc ... -lpcp

DESCRIPTION         top

       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 */
                pmValueBlock *vbp;  /* pmValueBlock 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 avail‐
       able to the application programmer.

       itype defines the data type of the input value held in  ival  ac‐
       cording 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 struc‐
       ture, following a call to pmLookupDesc(3) for a  particular  per‐
       formance metric.

       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 pm‐
       Result structure that provides the ival parameter, and if  valfmt
       specifies  PM_VAL_INSITU,  then  the  following types are not al‐
       lowed,  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,     PM_TYPE_DOUBLE,
       PM_TYPE_STRING,  PM_TYPE_AGGREGATE  and PM_TYPE_EVENT respective‐
       ly).  If valfmt specifies PM_VAL_SPTR or  PM_VAL_DPTR,  then  the
       value  will  be extracted from the associated pmValueBlock struc‐
       ture, and the __int32_t, __uint32_t and float options (itype  be‐
       ing  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 con‐
       version 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 at‐
       tempting to duplicate functionality already available  in  the  C
       library via sscanf(3) and sprintf(3).

       No conversion involving the type PM_TYPE_EVENT is supported.

             | 32  |  U32  | 64  |  U64  | FLOAT | DBLE | STRNG | AGGR | EVENT
       ======|=====|=======|=====|=======|=======|======|=======|======|=======
       32    |  Y  |   S   |  Y  |   S   |   P   |  P   |   N   |  N   |   N
       U32   |  T  |   Y   |  Y  |   Y   |   P   |  P   |   N   |  N   |   N
       64    |  T  |  T,S  |  Y  |   S   |   P   |  P   |   N   |  N   |   N
       U64   |  T  |   T   |  T  |   Y   |   P   |  P   |   N   |  N   |   N
       FLOAT | P,T | P,T,S | P,T | P,T,S |   Y   |  Y   |   N   |  N   |   N
       DBLE  | P,T | P,T,S | P,T | P,T,S |   P   |  Y   |   N   |  N   |   N
       STRNG |  N  |   N   |  N  |   N   |   N   |  N   |   Y   |  N   |   N
       AGGR  |  N  |   N   |  N  |   N   |   N   |  N   |   N   |  Y   |   N
       EVENT |  N  |   N   |  N  |   N   |   N   |  N   |   N   |  N   |   N

       In  the  cases  where multiple conversion errors could occur, the
       first encountered error will be notified, and the order of check‐
       ing is not defined.

       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(3),  and  it  is  the  caller's responsibility to free the
       space when it is no longer required.

       Although this function appears rather complex, it has  been  con‐
       structed 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.
       See the pmFetchGroup functions for a simpler alternative.

DIAGNOSTICS         top

       PM_ERR_CONV

              Impossible conversion, marked by N in above table

       PM_ERR_TRUNC

              High-order truncation occurred

       PM_ERR_SIGN

              Conversion of negative value to unsigned type attempted

SEE ALSO         top

       PMAPI(3),     pmAtomStr(3),      pmConvScale(3),      pmFetch(3),
       pmFetchGroup(3),  pmLookupDesc(3), pmPrintValue(3), pmTypeStr(3),
       pmUnitsStr(3) and pmUnpackEventRecords(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
       [email protected].    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
       [email protected]

Performance Co-Pilot               PCP                 PMEXTRACTVALUE(3)

Pages that refer to this page: pcpintro(3)pmapi(3)pmatomstr(3)pmconvscale(3)pmextractvalue(3)pmfetch(3)pmfetchgroup(3)pmlookupdesc(3)pmprintvalue(3)pmsemstr(3)pmtypestr(3)pmunitsstr(3)