NAME
pmGetChildren - return the descendent nodes of a PMNS node
C SYNOPSIS
#include <pcp/pmapi.h>
int pmGetChildren(const char *name, char ***offspring)
cc ... -lpcp
DESCRIPTION
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 descendents of the root node in the PMNS
will be returned.
Normally, pmGetChildren will return the number of descen
dent names discovered, else a value less than zero for an
error. The value zero indicates that name is a valid met
ric 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 mal
loc(3C), 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 call
ing free(3C) is a singularly bad idea).
PCP ENVIRONMENT
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(4). Values for these variables
may be obtained programatically using the pmGetConfig(3)
function.
SEE ALSO
PMAPI(3), pmGetChildrenStatus(3), pmGetConfig(3), pmLoad
ASCIINameSpace(3), pmLoadNameSpace(3), pmLookupName(3),
pmNameID(3), pcp.conf(4), pcp.env(4) and pmns(4).
PM_ERR_NOPMNS
Failed to access a PMNS for operation. Note that
if the application hasn't a priori called pmLoad
NameSpace(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.
Man(1) output converted with
man2html