pmatomstr(3) — Linux manual page

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

PMATOMSTR(3)             Library Functions Manual            PMATOMSTR(3)

NAME         top

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

C SYNOPSIS         top

       #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

DESCRIPTION         top

       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  per‐
       formance  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 pmAtom‐
       Str.

NOTES         top

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

SEE ALSO         top

       PMAPI(3),  pmConvScale(3),   pmExtractValue(3),   pmLookupDesc(3),
       pmPrintValue(3), pmTypeStr(3) and pmUnitsStr(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
       pcp@groups.io.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩  on
       2025-08-11.   (At  that  time,  the date of the most recent commit
       that was found in the repository was 2025-08-11.)  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 man-pages@man7.org

Performance Co-Pilot               PCP                       PMATOMSTR(3)

Pages that refer to this page: pmconvscale(3)pmextractvalue(3)pmlookupdesc(3)pmprintvalue(3)pmsemstr(3)pmtypestr(3)pmunitsstr(3)