--- name: "pmExtractValue" section: "3" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/pmExtractValue" --- # pmExtractValue(3) extract a performance metric value from a pmResult structure ## NAME **pmExtractValue** - extract a performance metric value from a pmResult structure ## C SYNOPSIS **#include \** **int pmExtractValue(int** *valfmt***,** **const pmValue \****ival***,** **int** *itype***,** **pmAtomValue \****oval***,** **int** *otype***);** **cc ... -lpcp** ## DESCRIPTION The *pmValue* structure is embedded within the *pmResult* structure that is used to return one or more performance metrics; see [**pmFetch**(3)](/pmFetch/3.md). 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 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)](/pmFetch/3.md)). *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)](/pmLookupDesc/3.md) for a particular performance 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 *pmResult* structure that provides the *ival* parameter, and if *valfmt* specifies **PM\_VAL\_INSITU**, then the following input types are not allowed, as these cannot be encoded in 32-bits; **\_\_int64\_t**, **\_\_uint64\_t**, **double**, **char \*** and **void \*** and the corresponding *itype* values are **PM\_TYPE\_64**, **PM\_TYPE\_U64**, **PM\_TYPE\_DOUBLE**, **PM\_TYPE\_STRING**, **PM\_TYPE\_AGGREGATE** and **PM\_TYPE\_EVENT** (or **PM\_TYPE\_HIGHRES\_EVENT**) respectively. If *valfmt* specifies **PM\_VAL\_SPTR** or **PM\_VAL\_DPTR**, 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**). No conversion involving the types **PM\_TYPE\_EVENT**, **PM\_TYPE\_HIGHRES\_EVENT** or **PM\_TYPE\_AGGR** is supported, and the label \`\`BLOB'' in the table below covers all three of these types. ``` | 32 | U32 | 64 | U64 | FLOAT | DBLE | STRNG | BLOB ======|=====|=======|=====|=======|=======|======|=======|====== 32 | Y | S | Y | S | P | P | Y | N U32 | T | Y | Y | Y | P | P | Y | N 64 | T | T,S | Y | S | P | P | Y | N U64 | T | T | T | Y | P | P | Y | N FLOAT | P,T | P,T,S | P,T | P,T,S | Y | Y | P | N DBLE | P,T | P,T,S | P,T | P,T,S | P | Y | P | N STRNG | N | N | N | N | N | N | Y | N BLOB | 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 checking 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)](/pmExtractValue/3.md) using [**malloc**(3)](/malloc/3.md), 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 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. See the **pmFetchGroup** functions for a simpler alternative. ## DIAGNOSTICS **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 [**PMAPI**(3)](/PMAPI/3.md), [**pmAtomStr**(3)](/pmAtomStr/3.md), [**pmConvScale**(3)](/pmConvScale/3.md), [**pmFetch**(3)](/pmFetch/3.md), [**pmFetchGroup**(3)](/pmFetchGroup/3.md), [**pmLookupDesc**(3)](/pmLookupDesc/3.md), [**pmPrintValue**(3)](/pmPrintValue/3.md), [**pmTypeStr**(3)](/pmTypeStr/3.md), [**pmUnitsStr**(3)](/pmUnitsStr/3.md) and [**pmUnpackEventRecords**(3)](/pmUnpackEventRecords/3.md).