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 do‐
       main 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 match‐
       ing 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  pmdaDae‐
       mon(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).

Performance Co-Pilot                                   PCP                                       PMDAINSTANCE(3)