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(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  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 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, pmTraversePMNS and
       pmTraversePMNS_r will return a negative  error  code,  as  described  in  the  DIAGNOSTICS
       section below.

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.