1PMGETCHILDREN(3) Library Functions Manual PMGETCHILDREN(3)
2
6 pmGetChildren, pmRequestNamesOfChildren, pmReceiveNamesOfChildren -
7 return the descendent nodes of a PMNS node
8
10 #include <pcp/pmapi.h>
11 int pmGetChildren(const char *name, char ***offspring)
13 int pmRequestNamesOfChildren(int ctx, const char *name, int wantstatus)
14 int pmReceiveNamesOfChildren(int ctx, char ***offspring, int **status)
15 cc ... -lpcp
17
19 Given a fully qualified pathname to a node in the current Performance
20 Metrics Name Space (PMNS), as identified by name, pmGetChildren returns
21 via offspring a list of the relative names of all of the immediate
22 descendent nodes of name in the current PMNS.
23 As a special case, if name is an empty string (i.e.""), the immediate
25 descendents of the root node in the PMNS will be returned.
26 Normally, pmGetChildren will return the number of descendent names dis‐
28 covered, else a value less than zero for an error. The value zero
29 indicates that name is a valid metric name, i.e. is associated with a
30 leaf node in the PMNS.
31 The resulting list of pointers offspring and the values (the relative
33 names) that the pointers reference will have been allocated by
34 pmGetChildren with a single call to malloc(3C), and it is the responsi‐
35 bility of the pmGetChildren caller to free(offspring) to release the
36 space when it is no longer required.
37 When an error occurs, or name is a leaf node (i.e. the result of
39 pmGetChildren is less than one), offspring is undefined (no space will
40 have been allocated, and so calling free(3C) is a singularly bad idea).
41 pmRequestNamesOfChildren and pmReceiveNamesOfChildren are used by
43 applications which must communicate with the PMCD asynchronously.
44 These functions take explict context handle ctx which must refer to a
45 host context (i.e. created by passing PM_CONTEXT_HOST to pmNewContext).
46 pmRequestNamesOfChildren sends request to PMCD to enumerate names of
47 the children of PMNS node and returns without waiting for the response,
48 pmReceiveNamesOfChildren reads reply from PMCD. It is the responsibil‐
49 ity of the application to make sure the data are ready before calling
50 pmReceiveNamesOfChildren to avoid blocking.
51 If in the call to pmRequestNamesOfChildren wantstatus was set to non-
53 zero value then pmReceiveNamesOfChildren will return the status of each
54 child via status. The status will refer to either a leaf node (with
55 value PMNS_LEAF_STATUS) or a non-leaf node (with value PMNS_NON‐
56 LEAF_STATUS), otherwise the status is undefined and should not be ref‐
57 erenced.
58
60 Environment variables with the prefix PCP_ are used to parameterize the
61 file and directory names used by PCP. On each installation, the file
62 /etc/pcp.conf contains the local values for these variables. The
63 $PCP_CONF variable may be used to specify an alternative configuration
64 file, as described in pcp.conf(4). Values for these variables may be
65 obtained programatically using the pmGetConfig(3) function.
66
68 PMAPI(3), pmGetChildrenStatus(3), pmGetConfig(3), pmLoadASCIINameS‐
69 pace(3), pmLoadNameSpace(3), pmLookupName(3), pmNameID(3), pcp.conf(4),
70 pcp.env(4) and pmns(4).
71
73 PM_ERR_NOPMNS
74 Failed to access a PMNS for operation. Note that if the appli‐
75 cation hasn't a priori called pmLoadNameSpace(3) and wants to
76 use the distributed PMNS, then a call to pmGetChildren must be
77 made inside a current context.
78 PM_ERR_NAME
80 The pathname name is not valid in the current PMNS
81 PM_ERR_*
83 Other diagnostics are for protocol failures when accessing the
84 distributed PMNS.
85 PM_ERR_CTXBUSY
87 Context is currently in use by another asynchronous call.
88Performance Co-Pilot SGI PMGETCHILDREN(3)