pmAtomStr man page

pmAtomStr, pmAtomStr_r — convert a performance metric value into a string

C Synopsis

#include <pcp/pmapi.h>

const char *pmAtomStr(const pmAtomValue *avp, int type);
char *pmAtomStr_r(const pmAtomValue *avp, int type, char *buf, int buflen);

cc ... -lpcp


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;

Given the performance metric value pointed to by avp, and a performance metric type defined by type, pmAtomStr will generate the corresponding metric value as a string, suitable for diagnostic or report output. The pmAtomStr_r function does the same, but stores the result in a user-supplied buffer buf of length buflen, which should have room for at least 80 bytes.

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

If the type is PM_TYPE_STRING values longer than 38 characters will be truncated after 34 characters, and truncation shown with ellipsis “...” at the end of the value.

If the type is PM_TYPE_AGGREGATE then up to the first three 32-bit words are displayed as hexadecimal values.

If the type is PM_TYPE_EVENT then a summary of the number of event records found in the value is generated.

The return value from pmAtomStr is held in a single static buffer, so the returned value is only valid until the next call to pmAtomStr.


pmAtomStr returns a pointer to a static buffer and hence is not thread-safe. Multi-threaded applications should use pmAtomStr_r instead.

See Also

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

Referenced By

pmConvScale(3), pmExtractValue(3), pmLookupDesc(3), pmPrintValue(3), pmSemStr(3), pmTypeStr(3), pmUnitsStr(3).

Explore man page connections for pmAtomStr(3).

pmatomstr(3) is an alias of pmAtomStr(3).

PCP Performance Co-Pilot