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