HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |C SYNOPSIS |DESCRIPTION |EXAMPLE |CAVEAT |DIAGNOSTICS |SEE ALSO |COLOPHON | |
PMDAFETCH(3) Library Functions ManualPMDAFETCH(3)pmdaFetch,pmdaSetFetchCallBack- fill a pmResult structure with the requested metric values
#include <pcp/pmapi.h>#include <pcp/pmda.h>int pmdaFetch(intnumpmid, pmID *pmidlist, pmResult **resp,pmdaExt *pmda);void pmdaSetFetchCallBack(pmdaInterface *dispatch,pmdaFetchCallBackcallback);cc ... -lpcp_pmda -lpcp
pmdaFetchis a generic callback used by aPMDA(3) to process a fetch request frompmcd(1). The request frompmcdis initiated by a client callingpmFetch(3). This is one of the few generic callbacks inlibpcp_pmda (seePMDA(3)) that is incomplete, requiring a furtherpmdaFetchCallBack method of its own. The additional callback should be registered usingpmdaSetFetchCallBackand thepmdaFetchCallBackmethod has the following prototype: int func(pmdaMetric *mdesc, unsigned int inst, pmAtomValue *avp)pmdaFetchwill allocate and resize theresp result structure, to store values for thenumpmid metrics listed inpmidlist. For each instance listed in the profile (seepmdaProfile(3)) of each metric listed inpmidlist, thepmdaFetchCallBackmethod is called to fill thepmAtomValuestructure identified byavp with a value for a specific metric-instance pair identified by the metric descriptormdesc and the instanceinst. This value is then copied into thepmResultstructure. ThepmdaFetchCallBackmethod should return a value less than zero for an error, and the most likely cases would bePM_ERR_PMIDif the metric identified bymdesc is not known to the method, orPM_ERR_INSTif the method believes the instanceinst is not known for the metric identified bymdesc. The success error codes depend on the version ofPMDA_INTERFACE the PMDA is using. If the PMDA is usingPMDA_INTERFACE_2then on success thepmdaFetchCallBackmethod should return0. If the PMDA is usingPMDA_INTERFACE_3orPMDA_INTERFACE_4then on success thepmdaFetchCallBackmethod should return1if a value is returned viaavp, else0if no values are currently available for the requested metric-instance pair althoughmdesc andinst both seem reasonable. If the PMDA is usingPMDA_INTERFACE_5or later then on success thepmdaFetchCallBackmethod should returnPMDA_FETCH_STATIC(1) if the value returned viaavp can be ignored bypmdaFetchonce it has been copied into thepmResultstructure, elsePMDA_FETCH_DYNAMIC (2) if the value returned viaavp uses the either thevporcp fields of thepmAtomValueand the associated value (buffer) was allocated using one ofmalloc(3),calloc(3),realloc(3),strdup(3) etc. andpmdaFetchshould release the memory by callingfree(3) once a new buffer has been allocated and the value copied, elsePMDA_FETCH_NOVALUES(0) if no values are currently available for the requested metric-instance pair althoughmdesc andinst both seem reasonable. If thepmdaFetchCallBackmethod returns a value for an instance of a metric of typePM_TYPE_STRINGorPM_TYPE_AGGREGATEsome special care is needed – the method should either use a static buffer, setavp->cp oravp->vp to the address of the buffer and returnPM‐DA_FETCH_STATIC, or use a dynamically allocated buffer, keep a static reference to the buffer's address, returnPMDA_FETCH_STATIC andfree(3) orrealloc(3) or reuse the buffer the next time thepmdaFetchCallBackmethod is called, else use a dynamically allo‐ cated buffer and returnPMDA_FETCH_DYNAMIC.
The following code fragments are for a hypothetical PMDA has with metrics (A, B, C and D) and an instance domain (X) with two in‐ stances (X1 and X2). The instance domain and metrics description tables (seepmdaInit(3)) could be defined as: static pmdaInstid _X[] = { { 0, "X1" }, { 1, "X2" } }; static pmdaIndom indomtab[] = { #define X_INDOM 0 { 0, 2, _X }, }; static pmdaMetric metrictab[] = { /* A */ { (void *)0, { PMDA_PMID(0,0), PM_TYPE_32, PM_INDOM_NULL, PM_SEM_INSTANT, {0,0,0,0,0,0} }, }, /* B */ { (void *)0, { PMDA_PMID(0,1), PM_TYPE_DOUBLE, X_INDOM, PM_SEM_INSTANT, {0,1,0,0,PM_TIME_SEC,0} }, }, /* C */ { (void *)0, { PMDA_PMID(0,2), PM_TYPE_STRING, PM_INDOM_NULL, PM_SEM_INSTANT, {0,0,0,0,0,0} }, }, /* D */ { (void *)0, { PMDA_PMID(0,3), PM_TYPE_STRING, PM_INDOM_NULL, PM_SEM_INSTANT, {0,0,0,0,0,0} }, }, }; ApmdaFetchCallBackmethod to be called frompmdaFetchcould be defined as: int myFetchCallBack(pmdaMetric *mdesc, unsigned int inst, pmAtomValue *avp) { static char sbuf[20]; // reuse this buffer char *dbuf; // malloc'd switch (pmID_item(mdesc->m_desc.pmid)) { case 0: /* assign some value for metric A */; avp->l = ... break; case 1: switch (inst) { case 0: /* assign a value for metric B, instance X1 */; avp->d = ... break; case 1: /* assign a value for metric B, instance X2 */; avp->d = ... break; default: return PM_ERR_INST; } case 2: /* place value for metric C in dbuf[] */ memcpy(dbuf, ...); avp->cp = dbuf; break; case 3: avp->cp = (char *)malloc(somesize); /* place value in avp->cp */ pmsprintf(avp->cp, somesize, ...); return PMDA_FETCH_DYNAMIC; default: return PM_ERR_PMID; } return PMDA_FETCH_STATIC; }The PMDA must be usingPMDA_INTERFACE_2or later, as specified in the call topmdaDSO(3) orpmdaDaemon(3).
The following error messages indicate that there is discrepancy between the namespace,pmdaMetricandpmdaIndomtables passed topmdaInit(3), and the registered fetch callback:pmdaFetch: Requested metricmetricis not defined A requested metricmetric is not listed in thepmdaMetric table. The namespace for thisPMDA(3) may contain addi‐ tional metrics.pmdaFetch: PMIDpmidnot handled by fetch callback ThepmdaFetchCallBackmethod has returnedPM_ERR_PMID. This indicates that a metric may be listed in thepmdaMet‐rictable, but is not supported by the callback method.pmdaFetch: Instanceinstof PMIDpmidnot handled by fetch call‐back ThepmdaFetchCallBackmethod has returnedPM_ERR_INST. This indicates that an instance of metric is listed in thepmdaIndomtable, but is not supported by the callback method.pmdaFetch: Fetch callback error: ThepmdaFetchCallBackmethod returned a result other thanPMDA_FETCH_NOVALUES,PMDA_FETCH_STATIC,PMDA_FETCH_DYNAMIC,PM_ERR_PMIDorPM_ERR_INST.pmdaFetch: Descriptor type (type) for metricpmidis bad The data typetype specified for the metricpmid in thepm‐daMetrictable is illegal.pmdaFetchwill return-errnoif an error occurred while allocating thepmResultstructure or copying the value from thepmAtomValue.
pmcd(1),PMAPI(3),PMDA(3),pmdaDaemon(3),pmdaDSO(3),pmdaInit(3) andpmFetch(3).
This page is part of thePCP (Performance Co-Pilot) project. In‐ formation about the project can be found at ⟨http://www.pcp.io/⟩. If you have a bug report for this manual page, send it to pcp@groups.io. This page was obtained from the project's upstream Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-11.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgPerformance Co-Pilot PCPPMDAFETCH(3)Pages that refer to this page:pmda(3), pmdacache(3), pmdadaemon(3), pmdadso(3), pmdainit(3), pmdamain(3), pmdaprofile(3)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |