NAME

       pmdaInit - initialize a PMDA


C SYNOPSIS

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

       void  pmdaInit(pmdaInterface *dispatch, pmdaIndom *indoms,
       int nindoms, pmdaMetric *metrics, int nmetrics)

       cc ... -lpcp_pmda -lpcp


DESCRIPTION

       pmdaInit initializes a PMDA so that it is ready to receive
       PDUs  from pmcd(1).  The function expects as arguments the
       instance domain table (indoms) and the metric  description
       table  (metrics)  that  are  initialized  by the PMDA. The
       arguments nindoms and nmetrics should be set to the number
       of instances and metrics in the tables, respectively.

       Much  of  the pmdaInterface structure can be automatically
       initialized   with   pmdaDaemon(3),   pmdaGetOpt(3)    and
       pmdaDSO(3).   pmdaInit  completes  the PMDA initialization
       phase with three operations.  The first operation adds the
       domain  and  instance  numbers  to the instance and metric
       tables.  Singular metrics  (metrics  without  an  instance
       domain)  should have the instance domain PM_INDOM_NULL set
       in  the  indom  field  of  the   pmDesc   structure   (see
       pmLookupDesc(3)).   Metrics with an instance domain should
       set this field to be the serial  number  of  the  instance
       domain in the indoms table.

       The  instance  domain  table  may be made empty by setting
       indoms to NULL and nindoms to 0.  This allows  the  caller
       to  provide  custom Fetch and Instance callback functions.
       The metric table may be made empty by setting  metrics  to
       NULL and nmetrics to 0.  This allows the caller to provide
       custom Fetch and Descriptor callback functions.


EXAMPLE

       For example, a PMDA has three metrics: A, B and C, and two
       instance  domains  X  and  Y,  with  two instances in each
       instance domain.  The instance domain and metrics descrip­
       tion tables could be defined as:

            static pmdaInstid _X[] = {
                { 0, "X1" }, { 1, "X2" }
            };

            static pmdaInstid _Y[] = {
                { 0, "Y1" }, { 1, "Y2" }


            static pmdaIndom indomtab[] = {
            #define X_INDOM 0
                { X_INDOM, 2, _X },
            #define Y_INDOM 3
                { Y_INDOM, 2, _Y }
            };

            static pmdaMetric metrictab[] = {
            /* A */
                { (void *)0,
                  { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT,
                    { 0,0,0,0,0,0} }, },
            /* B */
                { (void *)0,
                  { PMDA_PMID(0,1), PM_TYPE_U32, X_INDOM, PM_SEM_INSTANT,
                    { 0,0,0,0,0,0} }, },
            /* C */
                { (void *)0,
                  { PMDA_PMID(0,2), PM_TYPE_DOUBLE, Y_INDOM, PM_SEM_INSTANT,
                    { 0,1,0,0,PM_TIME_SEC,0} }, }
            };

       The  metric  description  table  defines  metric A with no
       instance domain, metric B with instance domain X and  met­
       ric  C with instance domain Y.  Metric C has units of sec­
       onds, while the other metrics have no units (simple  coun­
       ters).  pmdaInit will take these structures and assign the
       PMDA(3) domain  number  to  the  it_indom  field  of  each
       instance  domain.  This identifier also replaces the indom
       field of all metrics which have that instance  domain,  so
       that they are correctly associated.

       The  second  stage  opens  the  help text file, if one was
       specified with the -h command  line  option  (see  pmdaGe­
       tOpt(3))  or  as  a  helptext  argument  to  pmdaDSO(3) or
       pmdaDaemon(3).

       The final stage determines if the metrics can be  directly
       mapped to the metric table using their unique identifiers.
       If all of the metric PMID item numbers correspond  to  the
       position  in  the  metrics  table,  then direct mapping is
       used.  This can greatly  improve  the  efficiency  of  the
       callback functions.


DIAGNOSTICS

       pmdaInit  will  set  dispatch->status to a value less than
       zero if there is an error that would prevent  the  PMDA(3)
       from  successfully  running.   pmcd(1)  will terminate the
       connection to the PMDA(3) if this occurs.

       pmdaInit may issue any of these messages:

                      The interface version is not  supported  by
                      pmdaInit.

       Using pmdaFetch() but fetch call back not set
                      The  fetch callback, pmdaFetch(3), requires
                      an additional callback to be provided using
                      pmdaSetFetchCallBack(3).

       Illegal instance domain inst for metric pmid
                      The instance domain inst that was specified
                      for metric pmid is not within the range  of
                      the instance domain table.

       No help text path specified
                      The   help   text   callback,  pmdaText(3),
                      requires a help text file for  the  metrics
                      to have been opened, however no path to the
                      help text was specified as a  command  line
                      option,  or as an argument to pmdaDSO(3) or
                      pmdaDaemon(3).   This  message  is  only  a
                      warning.

       Direct mapping for metrics disabled @ num
                      The  unit  numbers  of  the metrics did not
                      correspond  to  the  index  in  the  metric
                      description   table.   The  direct  mapping
                      failed for metric number num in the metrics
                      table.   This  is less efficient but is not
                      fatal and the message is only a warning.


CAVEAT

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


SEE ALSO

       newhelp(1),  pmcd(1),  PMAPI(3),  PMDA(3),  pmdaDaemon(3),
       pmdaDSO(3), pmdaFetch(3), pmdaGetOpt(3),  pmdaText(3)  and
       pmLookupDesc(3).


Man(1) output converted with man2html