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

# pmRequestNames(3)

translate performance metric names into PMIDs

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

## NAME

**pmLookupName**, **pmRequestNames**, **pmReceiveNames** - translate performance metric names into PMIDs

## C SYNOPSIS

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

```
int pmLookupName(int numpmid, char **namelist, pmID *pmidlist)
int pmRequestNames(int ctx, int numpmid, char **namelist)
int pmReceiveNames(int ctx, pmID *pmidlist)
```

**cc ... -lpcp**

## DESCRIPTION

Given a list in *namelist* containing *numpmid* full pathnames for performance metrics from a Performance Metrics Name Space (PMNS), **pmLookupName** returns the list of associated Performance Metric Identifiers (PMIDs) via  *pmidlist*.

The result from **pmLookupName** will be the number of names translated in the absence of errors, else  an error code less than zero. When errors are encountered, the corresponding value in *pmidlist* will be PM\_ID\_NULL.

Note that the error protocol guarantees there is a 1:1 relationship between the elements of *namelist* and *pmidlist*, hence both lists contain exactly *numpmid* elements. For this reason, the caller is expected to have pre-allocated a suitably sized array for *pmidlist*.

**pmRequestNames** and **pmReceiveNames** 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**). **pmRequestNames** sends request to translate names to PMIDs to PMCD and returns without waiting for the response, **pmReceiveNames** reads reply from PMCD. It is the responsibility of  the application to make sure the data are ready before calling  **pmReceiveNames** to avoid blocking.

## SEE ALSO

[**PMAPI**(3)](/PMAPI/3.md), [**pmGetChildren**(3)](/pmGetChildren/3.md), [**pmGetChildrenStatus**(3)](/pmGetChildrenStatus/3.md), [**pmGetConfig**(3)](/pmGetConfig/3.md), [**pmLoadNameSpace**(3)](/pmLoadNameSpace/3.md), [**pmNameID**(3)](/pmNameID/3.md), [**pmNewContext**(3)](/pmNewContext/3.md), [**pcp.conf**(4)](/pcp.conf/4.md) and [**pcp.env**(4)](/pcp.env/4.md).

## DIAGNOSTICS

- **PM\_ERR\_TOOSMALL**

  *numpmid* must be at least 1

- **PM\_ERR\_NOPMNS**

  Failed to access a PMNS for operation. Note that if the application hasn't a priori called  [**pmLoadNameSpace**(3)](/pmLoadNameSpace/3.md) and wants to use the distributed PMNS, then a call to **pmLookupName** must be made after the creation of a context (see  [**pmNewContext**(3)](/pmNewContext/3.md)).

- **PM\_ERR\_NAME**

  One or more of the elements of *namelist* does not correspond to a valid metric name in the PMNS.

- **PM\_ERR\_NONLEAF**

  A name referred to a node in the PMNS but it was not a leaf node.

- **PM\_ERR\_\***

  Other diagnostics are for protocol failures when accessing the distributed PMNS.

- **PM\_ERR\_CTXBUSY**

  Context is currently in use by another asynchronous call.