NAME
pmdaChildren - translate a PMID to a set of dynamic performance metric
names
C SYNOPSIS
#include <pcp/pmapi.h>
#include <pcp/impl.h>
#include <pcp/pmda.h>
int pmdaChildren(char *name, int traverse, char ***offspring, int
**status, pmdaExt *pmda)
cc ... -lpcp_pmda -lpcp
DESCRIPTION
As part of the Performance Metrics Domain Agent (PMDA) API (see
PMDA(3)), pmdaChildren is the generic callback for returning dynamic
metric names (and their status) that are descendents of name.
Because implementing dynamic performance metrics requires specific PMDA
support, and the facility is an optional component of a PMDA (most
PMDAs do not support dynamic performance metrics), pmdaChildren is a
skeleton implementation that returns PM_ERR_NAME.
A PMDA that supports dynamic performance metrics will provide a private
callback that replaces pmdaChildren (by assignment to
version.four.children of the pmdaInterface structure) and takes the
initial metric name and returns names via offspring[] and the leaf or
non-leaf status of each via status[].
If traverse is 0, then the behaviour is akin to pmGetChildren(3) and
offspring[] contains the relative name component for the immediate
descendents of name.
If traverse is 1, then the behaviour is akin to pmTraversePMNS(3) and
offspring[] contains the absolute names of all dynamic metrics that are
decendents of name.
The resulting list of pointers offspring and the values (the names)
that the pointers reference will have been allocated by pmdaChildren
with a single call to malloc(3C), and the caller of pmdaChildren will
call free(offspring) to release the space when it is no longer
required. The same holds true for the status array.
DIAGNOSTICS
pmdaChildren returns PM_ERR_NAME if the name is not recognized or
cannot be translated, otherwise the number of descendent metric names
found.
CAVEAT
The PMDA must be using PMDA_PROTOCOL_4 or later, as specified in the
call to pmdaDSO(3) or pmdaDaemon(3).
SEE ALSO
PMAPI(3), PMDA(3), pmdaDaemon(3), pmdaDSO(3), pmdaMain(3),
pmGetChildren(3) and pmTraversePMNS(3).