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  in‐
29       ternally  to pmTraversePMNS.  Consequently the value is only valid dur‐
30       ing 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 and pmTraversePMNS_r  return  the  number  of
43       leaf nodes found in the traversal, which will be one (1) if name is ei‐
44       ther a leaf node, or a derived metric  or  a  non-leaf  node  with  one
45       child.   If name is a non-leaf node, the returned value will be zero or
46       greater (zero is returned in the special case where name is  a  dynamic
47       root  node that currently has no children).  In all cases, derived met‐
48       rics present in the PMNS subtree below name are counted as  leaf-nodes.
49       If  an an error occurs, pmTraversePMNS and pmTraversePMNS_r will return
50       a negative error code, as described in the DIAGNOSTICS section below.
51

DIAGNOSTICS

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

SEE ALSO

67       PMAPI(3) and pmGetChildren(3).
68
69
70
71Performance Co-Pilot                  PCP                    PMTRAVERSEPMNS(3)
Impressum