Man Linux: Main Page and Category List

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).