Provided by: libpcp3-dev_3.5.11_amd64 bug

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 explicit 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), pmGetChildren(3),  pmGetChildrenStatus(3),  pmGetConfig(3),  pmLoadNameSpace(3),
       pmNameID(3), pmNewContext(3), pcp.conf(4) and pcp.env(4).

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) and wants to use the distributed PMNS, then a call
              to pmLookupName must be made after the creation of a context (see pmNewContext(3)).

       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.