NAME | C SYNOPSIS | DESCRIPTION | SEE ALSO | DIAGNOSTICS | COLOPHON

PMTRAVERSEPMNS(3)         Library Functions Manual         PMTRAVERSEPMNS(3)

NAME         top

       pmTraversePMNS,  pmTraversePMNS_r  - traverse the performance metrics
       name space

C SYNOPSIS         top

       #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         top

       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         top

       PMAPI(3) and pmGetChildren(3).

DIAGNOSTICS         top

       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.

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@groups.io.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2018-04-30.  (At that time, the date of the most recent commit that
       was found in the repository was 2018-04-30.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Performance Co-Pilot                 PCP                   PMTRAVERSEPMNS(3)

Pages that refer to this page: pcp-mpstat(1)pmdachildren(3)pmdainit(3)