# pmgetchildrenstatus

## 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 *****_offspring_**,**
                                   **int ****_status_**);**
    
           **cc ... -lpcp**
    


## DESCRIPTION



           Given  a fully qualified pathname to a node in the current Perfor‐
           mance Metrics Name Space (PMNS), as identified by _name_ , **pmGetChil‐**
           **drenStatus** 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 imme‐
           diate descendants 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 ei‐
           ther  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 as‐
           sociated with a leaf node in the PMNS.
    
           The resulting list of pointers _offspring_ **and** the values (the rela‐
           tive  names)  that the pointers reference will have been allocated
           by **pmGetChildrenStatus** with a single call to malloc(3), and it  is
           the  responsibility of the **pmGetChildrenStatus** caller to **free**(_off‐_
           _spring_) 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 _offspring_  and  _status_
           are  undefined  (no  space will have been allocated and so calling
           free(3) is a singularly bad idea).
    


## DIAGNOSTICS



           **PM_ERR_NOPMNS**
                  Failed to access a PMNS for operation.  Note that if the
                  application hasn't a priori called pmLoadNameSpace(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.
    


## PCP ENVIRONMENT



           Environment variables with the prefix **PCP_** are used to parameter‐
           ize the file and directory names used by PCP.  On each installa‐
           tion, the file _/etc/pcp.conf_ contains the local values for these
           variables.  The **$PCP_CONF** variable may be used to specify an al‐
           ternative configuration file, as described in pcp.conf(5).  Values
           for these variables may be obtained programmatically using the
           pmGetConfig(3) function.
    


* * *