Man Linux: Main Page and Category List

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 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).