NAME
pmNameID, pmRequestNameID, pmReceiveNameID - translate a PMID to a
performance metric name
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.
SEE ALSO
PMAPI(3), pmGetChildren(3), pmGetChildrenStatus(3), pmGetConfig(3),
pmLoadASCIINameSpace(3), pmLoadNameSpace(3), pmLookupName(3),
pmNameAll(3), pmNewContext(3), pcp.conf(4), pcp.env(4) and pmns(4).
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.