---
name: "pmRequestText"
section: "3"
platform: "linux"
package: "libpcp3-dev"
version: "3.3.3-squeeze3"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/pmLookupText"
---

# pmRequestText(3)

return text describing a performance metric

Part of [pmLookupText(3)](/pmLookupText/3.md).

## NAME

**pmLookupText**, **pmRequestText**, **pmReceiveText** - return text describing a performance metric

## C SYNOPSIS

**#include \<pcp/pmapi.h\>**

```
int pmLookupText(pmID pmid, int level, char **buffer)
int pmRequestText(int ctx, pmID pmid, int level)
int pmReceiveText(int ctx, char **buffer)
```

**cc ... -lpcp**

## DESCRIPTION

Provided the source of metrics from the current Performance Metrics Application Programming Interface (PMAPI) context is a host, retrieve descriptive text about the performance metric identified by *pmid*.

The argument *level* should be  **PM\_TEXT\_ONELINE** for a one-line summary, else **PM\_TEXT\_HELP** for a more verbose description, suited to a help dialog.

The space pointed to by *buffer* will have been allocated in **pmLookupText** with **malloc**(3C), and it is the responsibility of the caller to **free**(3C) the space when it is no longer required.

**pmLookupText** returns zero on success.

**pmRequestText** and **pmReceiveText** are used by applications which must  communicate with the PMCD asynchronously.  These functions take explict context handle *ctx* which must refer to a host context (i.e. created by passing **PM\_CONTEXT\_HOST** to **pmNewContext**). **pmRequestText** sends request to PMCD to provide descriptive text about a metric identified by a PMID and  returns without waiting for the response, **pmReceiveText** reads reply from PMCD. It is the responsibility of the application to make sure the data are ready before calling **pmReceiveText** to avoid blocking.

**pmReceiveText** can be used to receive replies from either **pmRequestText** or **pmRequestInDomText**.

## SEE ALSO

[**chkhelp**(1)](/chkhelp/1.md), [**newhelp**(1)](/newhelp/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmGetConfig**(3)](/pmGetConfig/3.md), [**pmLookupDesc**(3)](/pmLookupDesc/3.md), [**pmLookupInDomText**(3)](/pmLookupInDomText/3.md), [**pmRequestInDomText**(3)](/pmRequestInDomText/3.md), [**pcp.conf**(4)](/pcp.conf/4.md) and [**pcp.env**(4)](/pcp.env/4.md).

## DIAGNOSTICS

- **PM\_ERR\_NOTHOST**

  if the current PMAPI context is an archive log (help and one-line text is not maintained in the archive logs)

- **PM\_ERR\_CTXBUSY**

  Context is currently in use by another asynchronous call