NAME

       pmGetChildrenStatus  -  return  the  descendent nodes of a
       PMNS node and their respective status


C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmGetChildrenStatus(const  char  *name,  char  ***off­
       spring, int **status)

       cc ... -lpcp


DESCRIPTION

       Given  a fully qualified pathname to a node in the current
       Performance Metrics Name Space (PMNS),  as  identified  by
       name,  pmGetChildrenStatus 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.

       If  status is not NULL, then pmGetChildrenStatus will also
       return the status of each child via  status.   The  status
       will   refer   to   either   a   leaf   node  (with  value
       PMNS_LEAF_STATUS  )  or  a  non-leaf  node   (with   value
       PMNS_NONLEAF_STATUS ).

       Normally,  pmGetChildrenStatus  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 pmGetChildrenStatus with a single call
       to  malloc(3C),  and  it  is  the  responsibility  of  the
       pmGetChildrenStatus  caller  to free(offspring) to release
       the space when it is no longer required.  The  same  holds
       true for the status array.

       When  an  error  occurs,  or name is a leaf node (i.e. the
       result of pmGetChildrenStatus is less than one), both off­
       spring  and  status are undefined (no space will have been
       allocated, and so calling 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

       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),  pmGetChildren(3),  pmGetConfig(3),  pmLoadASCI­
       INameSpace(3),     pmLoadNameSpace(3),    pmLookupName(3),
       pmNameID(3), pcp.conf(4), pcp.env(4) and pmns(4).


DIAGNOSTICS

       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  pmGetChildrenStatus 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