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

NAME

6       pmGetChildrenStatus  -  return  the descendent nodes of a PMNS node and
7       their respective status
8

C SYNOPSIS

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

DESCRIPTION

18       Given  a  fully qualified pathname to a node in the current Performance
19       Metrics Name Space (PMNS), as identified by  name,  pmGetChildrenStatus
20       returns  via offspring a list of the relative names of all of the imme‐
21       diate descendent nodes of name in the current PMNS.
22
23       As a special case, if name is an empty string (i.e.""),  the  immediate
24       descendants of the root node in the PMNS will be returned.
25
26       If  status  is  not NULL, then pmGetChildrenStatus will also return the
27       status of each child via status.  The status will  refer  to  either  a
28       leaf node (with value PMNS_LEAF_STATUS ) or a non-leaf node (with value
29       PMNS_NONLEAF_STATUS ).
30
31       Normally, pmGetChildrenStatus will  return  the  number  of  descendent
32       names  discovered, else a value less than zero for an error.  The value
33       zero indicates that name is a valid metric  name,  i.e.  is  associated
34       with a leaf node in the PMNS.
35
36       The  resulting  list of pointers offspring and the values (the relative
37       names)  that  the  pointers  reference  will  have  been  allocated  by
38       pmGetChildrenStatus  with a single call to malloc(3), and it is the re‐
39       sponsibility of the pmGetChildrenStatus caller  to  free(offspring)  to
40       release  the  space when it is no longer required.  The same holds true
41       for the status array.
42
43       When an error occurs, or name is  a  leaf  node  (i.e.  the  result  of
44       pmGetChildrenStatus  is  less  than one), both offspring and status are
45       undefined (no space will have been allocated, and so calling free(3) is
46       a singularly bad idea).
47

PCP ENVIRONMENT

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

SEE ALSO

57       PMAPI(3),  pmGetChildren(3),  pmGetConfig(3),  pmLoadASCIINameSpace(3),
58       pmLoadNameSpace(3),    pmLookupName(3),    pmNameID(3),    pcp.conf(5),
59       pcp.env(5) and pmns(5).
60

DIAGNOSTICS

62       PM_ERR_NOPMNS
63              Failed to access a PMNS for operation.  Note that if the  appli‐
64              cation  hasn't  a  priori called pmLoadNameSpace(3) and wants to
65              use the distributed PMNS, then  a  call  to  pmGetChildrenStatus
66              must be made inside a current context.
67
68       PM_ERR_NAME
69              The pathname name is not valid in the current PMNS
70
71       PM_ERR_*
72              Other  diagnostics  are for protocol failures when accessing the
73              distributed PMNS.
74
75
76
77Performance Co-Pilot                  PCP               PMGETCHILDRENSTATUS(3)