# pmlookupname

## NAME



           **pmLookupName** - translate performance metric names into PMIDs
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **int pmLookupName(int** _numpmid_**, const char ****_namelist_**,**
                            **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** depends on the presence of any lookup
           failures, their severity and the number of  metrics  being  looked
           up.
    
           1.  If there are no lookup failures, the return value will be
               _numpmid_.
    
           2.  If a fatal error is encountered, the return value will be less
               than 0.  For example **PM_ERR_TOOSMALL** , **PM_ERR_NOPMNS** or
               **PM_ERR_IPC**.
    
           3.  If _numpmid_ is greater than one and non-fatal error(s) are en‐
               countered, the return value is the number of metric names that
               have successfully been looked up (greater than or equal to ze‐
               ro and less than or equal to _numpmid_).
    
           4.  If _numpmid_ is one and a non-fatal error is encountered, the
               return value is the error code (less than zero).
    
           When errors are encountered, any metrics that cannot be looked up
           result in the corresponding element of _pmidlist_ being set to
           **PM_ID_NULL**.
    
           The slightly convoluted error protocol allows bulk lookups, then
           probing for more error details in the case of a specific failure,
           as shown in the **EXAMPLES** section below.
    
           Note that the error protocol guarantees there is a 1:1 relation‐
           ship between the elements of _namelist_ and _pmidlist_ , hence both
           lists contain exactly _numpmid_ elements.  For this reason, the
           caller is expected to have preallocated a suitably sized array for
           _pmidlist_.
    


## EXAMPLE



           #include <pcp/pmapi.h>
    
           #define NUMPMID (sizeof(names)/sizeof(const char *))
           const char *names[] = {
                          "sample.bin",
                          "sample",
                          "sample.bog",
                          "sample.secret.bar",
                          "sample.secret.bar.bad"
                        };
           pmID pmids[NUMPMID];
    
           int
           main(int argc, char **argv)
           {
               int  sts;
               int  numpmid = NUMPMID;
    
               pmNewContext(PM_CONTEXT_HOST, "local:");
    
               sts = pmLookupName(numpmid, names, pmids);
    
               if (sts < 0) {
                fprintf(stderr, "pmLookupName failed: %s0, pmErrStr(sts));
                exit(1);
               }
               if (sts != numpmid) {
                /*
                 * some of the lookups failed ... report the reason(s)
                 */
                int  i;
    
                for (i = 0; i < numpmid; i++) {
                    if (pmids[i] != PM_ID_NULL) continue;
                    /* this one failed */
                    sts = pmLookupName(1, &names[i], &pmids[i]);
                    fprintf(stderr, "%s: lookup failed: %s0, names[i], pmErrStr(sts));
                }
                exit(1);
               }
    
               /* all good ... */
               ...
           }
    


## 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 **pmLookup‐**
                  **Name** must be made after the creation of a context (see
                  pmNewContext(3)).
    
           **PM_ERR_NAME**
                  _namelist[0]_ does not correspond to a valid metric name in
                  the PMNS.
    
           **PM_ERR_NONLEAF**
                  _namelist[0]_ refers 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.
    


* * *