NAME

       pmdaInstance - return instance descriptions for a PMDA


C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/impl.h>
       #include <pcp/pmda.h>

       int  pmdaInstance(pmInDom  indom,  int  inst,  char *name,
       __pmInResult **result, pmdaExt *pmda);

       cc ... -lpcp_pmda -lpcp


DESCRIPTION

       pmdaInstance uses the standard PMDA(3) data structures  to
       return information concerning the instance domain indom.

       The  result  structure  is constructed by pmdaInstance and
       will contain one or more instance names and/or identifiers
       as specified by the inst and name arguments.

       If  inst  has  the  value  PM_IN_NULL  and  name is a null
       string, result will contain all the  instances  names  and
       identifiers in the instance domain.

       If  inst is PM_IN_NULL but name is the name of an instance
       in the instance domain indom, then result will contain the
       instance  identifier for instance name.  Note that if name
       contains no spaces, partial matching up to the first space
       in  the instance name is performed, i.e.  ``1'' will match
       instance name ``1 minute''.  If name contains an  embedded
       space,  then  no  partical  matching is performed and name
       should match one of the instance names exactly.

       If name is a null string but inst is an  instance  identi­
       fier  in  the instance domain indom, then result will con­
       tain the name for instance inst.  The result structure  is
       allocated  with  malloc(3)  and  should be released by the
       caller with free(3).


DIAGNOSTICS

       If any errors occur during the execution of  pmdaInstance,
       the  result  structure  is  deallocated.   If the instance
       domain indom is not supported by  the  PMDA,  pmdaInstance
       will return PM_ERR_INDOM.

       If  the  inst or name does not correspond to any instances
       in the indom domain, pmdaInstance will return PM_ERR_INST.


CAVEAT

       The PMDA must be using PMDA_INTERFACE_2 or later, as spec­
       ified in the call to pmdaDSO(3) or pmdaDaemon(3).

       in  the  instance  name,  the PMDA developer should ensure
       that if instance names are allowed  to  have  spaces,  the
       names are unique up to the first space.


SEE ALSO

       malloc(3), PMAPI(3), PMDA(3) and pmGetInDom(3).


Man(1) output converted with man2html