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  partial matching is performed and name should match one of the
       instance names exactly.

       If name is a null string but inst is an instance identifier in the instance domain  indom,
       then  result  will  contain 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 specified in the call to pmdaDSO(3)
       or pmdaDaemon(3).

       Because of optional partial matching up to the first space 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).