Man Linux: Main Page and Category List

NAME

       pmGetChildren,   pmRequestNamesOfChildren,  pmReceiveNamesOfChildren  -
       return the descendent nodes of a PMNS node

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmGetChildren(const char *name, char ***offspring)
       int pmRequestNamesOfChildren(int ctx, const char *name, int wantstatus)
       int pmReceiveNamesOfChildren(int ctx, char ***offspring, 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, 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  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
       pmGetChildren  with  a  single  call  to  malloc(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 calling free(3C) is a singularly bad idea).

       pmRequestNamesOfChildren  and  pmReceiveNamesOfChildren  are  used   by
       applications  which  must   communicate  with  the PMCD asynchronously.
       These functions take explict context handle ctx which must refer  to  a
       host context (i.e. created by passing PM_CONTEXT_HOST to pmNewContext).
       pmRequestNamesOfChildren sends request to PMCD to  enumerate  names  of
       the children of PMNS node and returns without waiting for the response,
       pmReceiveNamesOfChildren  reads   reply   from   PMCD.    It   is   the
       responsibility  of  the  application  to  make  sure the data are ready
       before calling pmReceiveNamesOfChildren to avoid blocking.

       If in the call to pmRequestNamesOfChildren wantstatus was set  to  non-
       zero value then pmReceiveNamesOfChildren will 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), otherwise the status is undefined and should  not
       be referenced.

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),
       pmLoadASCIINameSpace(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 pmLoadNameSpace(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.

       PM_ERR_CTXBUSY
              Context is currently in use by another asynchronous call.