pmtraversepmns(3) — Linux manual page

PMTRAVERSEPMNS(3)       Library Functions Manual       PMTRAVERSEPMNS(3)

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.

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.

SEE ALSO

       PMAPI(3) and pmGetChildren(3).

COLOPHON

       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 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  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), pmgetderivedcontrol(3)

---