1PMTRAVERSEPMNS(3)          Library Functions Manual          PMTRAVERSEPMNS(3)
2
3
4

NAME

6       pmTraversePMNS,  pmTraversePMNS_r  -  traverse  the performance metrics
7       name space
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       int pmTraversePMNS(const char *name, void (*dometric)(const char *));
13       int pmTraversePMNS_r(const char *name, void (*dometric_r)(const char *, void *), void *closure);
14
15       cc ... -lpcp
16

DESCRIPTION

18       The routine pmTraversePMNS may be used to perform a depth-first traver‐
19       sal of the Performance Metrics Name Space (PMNS).
20
21       The  traversal  starts  at  the node identified by name - if name is an
22       empty string (i.e. ""), the traversal starts at the root of  the  PMNS.
23       Usually name would be the pathname of a non-leaf node in the PMNS.
24
25       For  each  leaf  node (i.e. performance metric) found in the traversal,
26       the user-supplied routine dometric is called with the full pathname  of
27       that metric in the PMNS as the single argument.  This argument is null-
28       byte terminated, and is constructed  from  a  buffer  that  is  managed
29       internally  to  pmTraversePMNS.   Consequently  the value is only valid
30       during the call to dometric - if the pathname needs to be retained,  it
31       should be copied using strdup(3) before returning from dometric.
32
33       The  pmTraversePMNS_r  routine  performs  the same function, except the
34       callback method func_r has an additional parameter that will be closure
35       from the initial call to pmTraversePMNS_r.  The additional parameter to
36       pmTraversePMNS_r and the callback method allows the caller to pass con‐
37       text through pmTraversePMNS_r and into the callback method func_r, mak‐
38       ing the service  more  useful  for  multi-threaded  applications  where
39       thread-private data can be accessed in the callback method via the clo‐
40       sure argument.
41
42       On success pmTraversePMNS returns the number of children of name, which
43       may be zero.
44

SEE ALSO

46       PMAPI(3) and pmGetChildren(3).
47

DIAGNOSTICS

49       PM_ERR_NOPMNS
50              Failed  to access a PMNS for operation.  Note that if the appli‐
51              cation hasn't a priori called pmLoadNameSpace(3)  and  wants  to
52              use  the distributed PMNS, then a call to pmTraversePMNS must be
53              made inside a current context.
54
55       PM_ERR_NAME
56              The initial pathname name is not valid in the current PMNS.
57
58       PM_ERR_*
59              Other diagnostics are for protocol failures when  accessing  the
60              distributed PMNS.
61
62
63
64Performance Co-Pilot                  PCP                    PMTRAVERSEPMNS(3)