---
name: "pmAtomStr"
section: "3"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pmAtomStr"
---

# pmAtomStr(3)

convert a performance metric value into a string

## NAME

**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**

## DESCRIPTION

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)](/pmLookupDesc/3.md) 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**.

## NOTES

**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)](/PMAPI/3.md), [**pmConvScale**(3)](/pmConvScale/3.md), [**pmExtractValue**(3)](/pmExtractValue/3.md), [**pmLookupDesc**(3)](/pmLookupDesc/3.md), [**pmPrintValue**(3)](/pmPrintValue/3.md), [**pmTypeStr**(3)](/pmTypeStr/3.md) and [**pmUnitsStr**(3)](/pmUnitsStr/3.md).