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

NAME

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

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       int pmTraversePMNS(const char *name, void (*dometric)(const char *))
13       int pmRequestTraversePMNS(int ctx, const char *name)
14       int pmReceiveTraversePMNS(int ctx, void (*dometric)(const char *))
15
16       cc ... -lpcp
17

DESCRIPTION

19       The routine pmTraversePMNS may be used to perform a depth-first traver‐
20       sal of the Performance Metrics Name Space (PMNS).
21
22       The  traversal  starts  at  the node identified by name - if name is an
23       empty string (i.e.""), the traversal starts at the root  of  the  PMNS.
24       Usually name would be the pathname of a non-leaf node in the PMNS.
25
26       For  each  leaf  node (i.e. performance metric) found in the traversal,
27       the user-supplied routine dometric is called with the full pathname  of
28       that metric in the PMNS as the single argument.  This argument is null-
29       byte terminated, and is constructed  from  a  buffer  that  is  managed
30       internally  to  pmTraversePMNS.   Consequently  the value is only valid
31       during the call to dometric - if the pathname needs to be retained,  it
32       should be copied using strdup(3C) before returning from dometric.
33
34       On success pmtraversePMNS returns the number of children of name, which
35       may be zero.
36
37       pmRequestTraversePMNS and pmReceiveTraversePMNS are  used  by  applica‐
38       tions  which  must   communicate  with  the PMCD asynchronously.  These
39       functions take explict context handle ctx which must refer  to  a  host
40       context  (i.e.  created  by  passing  PM_CONTEXT_HOST to pmNewContext).
41       pmRequestTraversePMNS sends request to PMCD to return sub-tree of  PMNS
42       and  returns  without  waiting  for the response, pmReceiveTraversePMNS
43       reads reply from PMCD and executes depth-first traversal over  returned
44       sub-tree.  It is the responsibility of the application to make sure the
45       data are ready before calling pmReceiveTraversePMNS.
46
47       Unlike  its  synchronous  counterpart   pmTraversePMNS,   pmReceiveTra‐
48       versePMNS  does  not perform any additional queries to provide compati‐
49       bility with older versions of PCP,  it  is  the  responsibility  of  an
50       application to implement additional traversals.
51

SEE ALSO

53       PMAPI(3) and pmGetChildren(3).
54

DIAGNOSTICS

56       PM_ERR_NOPMNS
57              Failed  to access a PMNS for operation.  Note that if the appli‐
58              cation hasn't a priori called pmLoadNameSpace(3)  and  wants  to
59              use  the distributed PMNS, then a call to pmTraversePMNS must be
60              made inside a current context.
61
62       PM_ERR_NAME
63              The initial pathname name is not valid in the current PMNS.
64
65       PM_ERR_*
66              Other diagnostics are for protocol failures when  accessing  the
67              distributed PMNS.
68
69       PM_ERR_CTXBUSY
70              Context is currently in use by another asynchronous call.
71
72
73
74Performance Co-Pilot                  SGI                    PMTRAVERSEPMNS(3)