# pmtraversepmns

## NAME



           **pmTraversePMNS** , **pmTraversePMNS_r** - traverse the performance
           metrics name space
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **int pmTraversePMNS(const char ***_name_**,**
                              **void (***_dometric_**)(const char *));**
           **int pmTraversePMNS_r(const char ***_name_**,**
                                **void (***_dometric_r_**)(const char *, void *),**
                                **void ***_closure_**);**
    
           **cc ... -lpcp**
    


## DESCRIPTION



           The  routine  **pmTraversePMNS** may be used to perform a depth-first
           traversal of the Performance Metrics Name Space (PMNS).
    
           The traversal starts at the node identified by _name_ - if  _name_  is
           an empty string (i.e. **""**), the traversal starts at the root of the
           PMNS.   Usually  _name_  would be the pathname of a non-leaf node in
           the PMNS.
    
           For each leaf node (i.e. performance metric) found in the  traver‐
           sal,  the  user-supplied  routine _dometric_ is called with the full
           pathname of that metric in the PMNS as the single argument.   This
           argument is null-byte terminated, and is constructed from a buffer
           that  is  managed  internally to **pmTraversePMNS**.  Consequently the
           value is only valid during the call to _dometric_ - if the  pathname
           needs  to  be retained, it should be copied using strdup(3) before
           returning from _dometric_.
    
           The **pmTraversePMNS_r** routine performs the  same  function,  except
           the  callback  method _func_r_ has an additional parameter that will
           be _closure_ from the initial call to **pmTraversePMNS_r**.   The  addi‐
           tional  parameter  to **pmTraversePMNS_r** and the callback method al‐
           lows the caller to pass context through **pmTraversePMNS_r** and  into
           the  callback  method  _func_r_ ,  making the service more useful for
           multi-threaded applications where thread-private data can  be  ac‐
           cessed in the callback method via the _closure_ argument.
    
           On  success  **pmTraversePMNS** and **pmTraversePMNS_r** return the number
           of leaf nodes found in the traversal, which will  be  one  (1)  if
           _name_ is either a leaf node, or a derived metric or a non-leaf node
           with  one  child.   If _name_ is a non-leaf node, the returned value
           will be zero or greater (zero is  returned  in  the  special  case
           where _name_ is a dynamic root node that currently has no children).
           In  all  cases,  derived metrics present in the PMNS subtree below
           _name_ are counted as leaf-nodes.  If an  an  error  occurs,  **pmTra‐**
           **versePMNS** and **pmTraversePMNS_r** will return a negative error code,
           as described in the **DIAGNOSTICS** section below.
    


## 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 **pmTra‐**
                  **versePMNS** must be made inside a current context.
    
           **PM_ERR_NAME**
                  The initial pathname _name_ is not valid in the current PMNS.
    
           **PM_ERR_***
                  Other diagnostics are for protocol failures when accessing
                  the distributed PMNS.
    


* * *