|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | C SYNOPSIS | DESCRIPTION | DIAGNOSTICS | SEE ALSO | COLOPHON |
|
|
|
PMTRAVERSEPMNS(3) Library Functions Manual PMTRAVERSEPMNS(3)
pmTraversePMNS, pmTraversePMNS_r - traverse the performance
metrics name space
#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
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.
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.
PMAPI(3) and pmGetChildren(3).
This page is part of the PCP (Performance Co-Pilot) project. In‐
formation 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
2025-08-11. (At that time, the date of the most recent commit
that was found in the repository was 2025-08-11.) 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)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|