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

NAME

6       pmGetChildren - return the descendent nodes of a PMNS node
7

C SYNOPSIS

9       #include <pcp/pmapi.h>
10
11       int pmGetChildren(const char *name, char ***offspring);
12
13       cc ... -lpcp
14

DESCRIPTION

16       Given  a  fully qualified pathname to a node in the current Performance
17       Metrics Name Space (PMNS), as identified by name, pmGetChildren returns
18       via  offspring a list of the relative names of all of the immediate de‐
19       scendent nodes of name in the current PMNS.
20
21       As a special case, if name is an empty string (i.e.""),  the  immediate
22       descendants of the root node in the PMNS will be returned.
23
24       Normally, pmGetChildren will return the number of descendent names dis‐
25       covered, else a value less than zero for an error.  The value zero  in‐
26       dicates  that  name  is  a valid metric name, i.e. is associated with a
27       leaf node in the PMNS.
28
29       The resulting list of pointers offspring and the values  (the  relative
30       names)  that  the  pointers  reference  will  have  been  allocated  by
31       pmGetChildren with a single call to malloc(3), and it is the  responsi‐
32       bility  of  the  pmGetChildren caller to free(offspring) to release the
33       space when it is no longer required.
34
35       When an error occurs, or name is  a  leaf  node  (i.e.  the  result  of
36       pmGetChildren  is less than one), offspring is undefined (no space will
37       have been allocated, and so calling free(3) is a singularly bad idea).
38

DIAGNOSTICS

40       PM_ERR_NOPMNS
41              Failed to access a PMNS for operation.  Note that if the  appli‐
42              cation  hasn't  a  priori called pmLoadNameSpace(3) and wants to
43              use the distributed PMNS, then a call to pmGetChildren  must  be
44              made inside a current context.
45
46       PM_ERR_NAME
47              The pathname name is not valid in the current PMNS
48
49       PM_ERR_*
50              Other  diagnostics  are for protocol failures when accessing the
51              distributed PMNS.
52

PCP ENVIRONMENT

54       Environment variables with the prefix PCP_ are used to parameterize the
55       file  and  directory names used by PCP.  On each installation, the file
56       /etc/pcp.conf contains the  local  values  for  these  variables.   The
57       $PCP_CONF  variable may be used to specify an alternative configuration
58       file, as described in pcp.conf(5).  Values for these variables  may  be
59       obtained programmatically using the pmGetConfig(3) function.
60

SEE ALSO

62       PMAPI(3),   pmGetChildrenStatus(3),  pmGetConfig(3),  pmLoadASCIINameS‐
63       pace(3), pmLoadNameSpace(3), pmLookupName(3), pmNameID(3), pcp.conf(5),
64       pcp.env(5) and PMNS(5).
65
66
67
68Performance Co-Pilot                  PCP                     PMGETCHILDREN(3)
Impressum