C SYNOPSIS

#include <pcp/pmapi.h>

int pmNameID(pmID pmid, char **name)
int pmRequestNameID(int ctx, pmID pmid)
int pmRecieveNameID(int ctx, char **name)

cc ... -lpcp

DESCRIPTION

Given a Performance Metric ID (PMID) via pmid, pmNameID will determine the corresponding metric name, if any, in the Performance Metrics Name Space (PMNS), and return this via name.

If the PMNS contains multiple names associated with the requested PMID, one of these will be returned via name, but there is no way to determine which of the duplicate names this will be. See pmNameAll(3) if all of the corresponding names are required.

name is a null-byte terminated string, allocated by pmNameID using malloc(3C) and it is the caller's responsibility to call free(3C) to release the storage when the value is no longer required.

In the absence of errors, pmNameID returns zero.

pmRequestNameID and pmReceiveNameID 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. creared by passing PM_CONTEXT_HOST to pmNewContext). pmRequestNameID sends request to PMCD to translate PMID to a metric name and returns without waiting for the response, pmReceiveNameID reads reply from PMCD. It is the responsibility of the application to make sure the data are ready before calling pmReceiveNameID to avoid blocking.

DIAGNOSTICS

PM_ERR_NOPMNS

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

PM_ERR_PMID

pmid does not correspond to a defined PMID in the PMNS.

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.