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

DIAGNOSTICS

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

PCP ENVIRONMENT

63       Environment variables with the prefix PCP_ are used to parameterize the
64       file and directory names used by PCP.  On each installation,  the  file
65       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
66       $PCP_CONF variable may be used to specify an alternative  configuration
67       file,  as  described in pcp.conf(5).  Values for these variables may be
68       obtained programmatically using the pmGetConfig(3) function.
69

SEE ALSO

71       PMAPI(3),  pmGetChildren(3),  pmGetConfig(3),  pmLoadASCIINameSpace(3),
72       pmLoadNameSpace(3),    pmLookupName(3),    pmNameID(3),    pcp.conf(5),
73       pcp.env(5) and PMNS(5).
74
75
76
77Performance Co-Pilot                  PCP               PMGETCHILDRENSTATUS(3)