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  traversal,  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(3C) 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  additional  parameter to pmTraversePMNS_r and the callback method
       allows 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 accessed in the callback method via the closure argument.

       On success pmTraversePMNS returns the number of children of name, which may be zero.

SEE ALSO

       PMAPI(3) and pmGetChildren(3).

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 pmTraversePMNS 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.