pmGetChildren - return the descendent nodes of a PMNS node
#include <pcp/pmapi.h>
int pmGetChildren(const char * name, char ***offspring);
cc ... -lpcp
Given a fully qualified pathname to a node in the current Performance Metrics
Name Space (PMNS), as identified by
name,
pmGetChildren returns
via
offspring a list of the relative names of all of the immediate
descendent nodes of
name in the current PMNS.
As a special case, if
name is an empty string (i.e.
""),
the immediate descendants of the root node in the PMNS will be returned.
Normally,
pmGetChildren will return the number of descendent names
discovered, else a value less than zero for an error. The value zero indicates
that
name is a valid metric name, i.e. is associated with a leaf node
in the PMNS.
The resulting list of pointers
offspring and the values (the
relative names) that the pointers reference will have been allocated by
pmGetChildren with a single call to
malloc(3), and it is the
responsibility of the
pmGetChildren caller to
free(
offspring) to release the space when it is no longer
required.
When an error occurs, or
name is a leaf node (i.e. the result of
pmGetChildren is less than one),
offspring is undefined (no
space will have been allocated, and so calling
free(3) is a singularly
bad idea).
- PM_ERR_NOPMNS
- Failed to access a PMNS for operation. Note that if the
application hasn't a priori called pmLoadNameSpace(3) and wants to use the
distributed PMNS, then a call to pmGetChildren must be made inside
a current context.
- PM_ERR_NAME
- The pathname name is not valid in the current
PMNS
- PM_ERR_*
- Other diagnostics are for protocol failures when accessing
the distributed PMNS.
Environment variables with the prefix
PCP_ are used to parameterize the
file and directory names used by PCP. On each installation, the file
/etc/pcp.conf contains the local values for these variables. The
$PCP_CONF variable may be used to specify an alternative configuration
file, as described in
pcp.conf(5). Values for these variables may be
obtained programmatically using the
pmGetConfig(3) function.
PMAPI(3),
pmGetChildrenStatus(3),
pmGetConfig(3),
pmLoadASCIINameSpace(3),
pmLoadNameSpace(3),
pmLookupName(3),
pmNameID(3),
pcp.conf(5),
pcp.env(5) and
PMNS(5).