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

NAME

6       pmGetChildren,   pmRequestNamesOfChildren,  pmReceiveNamesOfChildren  -
7       return the descendent nodes of a PMNS node
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       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
16       cc ... -lpcp
17

DESCRIPTION

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
24       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
27       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
32       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
38       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
42       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
52       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

PCP ENVIRONMENT

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

SEE ALSO

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

DIAGNOSTICS

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
79       PM_ERR_NAME
80              The pathname name is not valid in the current PMNS
81
82       PM_ERR_*
83              Other diagnostics are for protocol failures when  accessing  the
84              distributed PMNS.
85
86       PM_ERR_CTXBUSY
87              Context is currently in use by another asynchronous call.
88
89
90
91Performance Co-Pilot                  SGI                     PMGETCHILDREN(3)
Impressum