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