1PMDAINIT(3) Library Functions Manual PMDAINIT(3)
2
6 pmdaInit - initialize a PMDA
7
9 #include <pcp/pmapi.h>
10 #include <pcp/impl.h>
11 #include <pcp/pmda.h>
12 void pmdaInit(pmdaInterface *dispatch, pmdaIndom *indoms, int nindoms,
14 pmdaMetric *metrics, int nmetrics)
15 cc ... -lpcp_pmda -lpcp
17
19 pmdaInit initializes a PMDA so that it is ready to receive PDUs from
20 pmcd(1). The function expects as arguments the instance domain table
21 (indoms) and the metric description table (metrics) that are initial‐
22 ized by the PMDA. The arguments nindoms and nmetrics should be set to
23 the number of instances and metrics in the tables, respectively.
24 Much of the pmdaInterface structure can be automatically initialized
26 with pmdaDaemon(3), pmdaGetOpt(3) and pmdaDSO(3). pmdaInit completes
27 the PMDA initialization phase with three operations. The first opera‐
28 tion adds the domain and instance numbers to the instance and metric
29 tables. Singular metrics (metrics without an instance domain) should
30 have the instance domain PM_INDOM_NULL set in the indom field of the
31 pmDesc structure (see pmLookupDesc(3)). Metrics with an instance
32 domain should set this field to be the serial number of the instance
33 domain in the indoms table.
34 The instance domain table may be made empty by setting indoms to NULL
36 and nindoms to 0. This allows the caller to provide custom Fetch and
37 Instance callback functions. The metric table may be made empty by
38 setting metrics to NULL and nmetrics to 0. This allows the caller to
39 provide custom Fetch and Descriptor callback functions.
40
42 For example, a PMDA has three metrics: A, B and C, and two instance
43 domains X and Y, with two instances in each instance domain. The
44 instance domain and metrics description tables could be defined as:
45 static pmdaInstid _X[] = {
47 { 0, "X1" }, { 1, "X2" }
48 };
49 static pmdaInstid _Y[] = {
51 { 0, "Y1" }, { 1, "Y2" }
52 };
53 static pmdaIndom indomtab[] = {
55 #define X_INDOM 0
56 { X_INDOM, 2, _X },
57 #define Y_INDOM 3
58 { Y_INDOM, 2, _Y }
59 };
60 static pmdaMetric metrictab[] = {
62 /* A */
63 { (void *)0,
64 { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT,
65 { 0,0,0,0,0,0} }, },
66 /* B */
67 { (void *)0,
68 { PMDA_PMID(0,1), PM_TYPE_U32, X_INDOM, PM_SEM_INSTANT,
69 { 0,0,0,0,0,0} }, },
70 /* C */
71 { (void *)0,
72 { PMDA_PMID(0,2), PM_TYPE_DOUBLE, Y_INDOM, PM_SEM_INSTANT,
73 { 0,1,0,0,PM_TIME_SEC,0} }, }
74 };
75 The metric description table defines metric A with no instance domain,
77 metric B with instance domain X and metric C with instance domain Y.
78 Metric C has units of seconds, while the other metrics have no units
79 (simple counters). pmdaInit will take these structures and assign the
80 PMDA(3) domain number to the it_indom field of each instance domain.
81 This identifier also replaces the indom field of all metrics which have
82 that instance domain, so that they are correctly associated.
83 The second stage opens the help text file, if one was specified with
85 the -h command line option (see pmdaGetOpt(3)) or as a helptext argu‐
86 ment to pmdaDSO(3) or pmdaDaemon(3).
87 The final stage determines if the metrics can be directly mapped to the
89 metric table using their unique identifiers. If all of the metric PMID
90 item numbers correspond to the position in the metrics table, then
91 direct mapping is used. This can greatly improve the efficiency of the
92 callback functions.
93
95 pmdaInit will set dispatch->status to a value less than zero if there
96 is an error that would prevent the PMDA(3) from successfully running.
97 pmcd(1) will terminate the connection to the PMDA(3) if this occurs.
98 pmdaInit may issue any of these messages:
100 PMDA interface version interface not supported
102 The interface version is not supported by pmdaInit.
103 Using pmdaFetch() but fetch call back not set
105 The fetch callback, pmdaFetch(3), requires an additional
106 callback to be provided using pmdaSetFetchCallBack(3).
107 Illegal instance domain inst for metric pmid
109 The instance domain inst that was specified for metric
110 pmid is not within the range of the instance domain ta‐
111 ble.
112 No help text path specified
114 The help text callback, pmdaText(3), requires a help
115 text file for the metrics to have been opened, however
116 no path to the help text was specified as a command line
117 option, or as an argument to pmdaDSO(3) or pmdaDae‐
118 mon(3). This message is only a warning.
119 Direct mapping for metrics disabled @ num
121 The unit numbers of the metrics did not correspond to
122 the index in the metric description table. The direct
123 mapping failed for metric number num in the metrics ta‐
124 ble. This is less efficient but is not fatal and the
125 message is only a warning.
126
128 The PMDA must be using PMDA_INTERFACE_2 or later, as specified in the
129 call to pmdaDSO(3) or pmdaDaemon(3).
130
132 newhelp(1), pmcd(1), PMAPI(3), PMDA(3), pmdaDaemon(3), pmdaDSO(3),
133 pmdaFetch(3), pmdaGetOpt(3), pmdaText(3) and pmLookupDesc(3).
134Performance Co-Pilot SGI PMDAINIT(3)