Man Linux: Main Page and Category List

NAME

       pmdaFetch,  pmdaSetFetchCallBack  -  fill a pmResult structure with the
       requested metric values

C SYNOPSIS

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

       int pmdaFetch(int numpmid, pmID  *pmidlist,  pmResult  **resp,  pmdaExt
       *pmda);

       void  pmdaSetFetchCallBack(pmdaInterface  *dispatch,  pmdaFetchCallBack
       callback);

       cc ... -lpcp_pmda -lpcp

DESCRIPTION

       pmdaFetch is a generic callback used by a PMDA(3) to  process  a  fetch
       request  from  pmcd(1).  The request from pmcd is initiated by a client
       calling pmFetch(3).

       This is the only generic callback (see  PMDA(3))  that  is  incomplete,
       requiring  a  callback  of it’s own.  The additional callback should be
       registered using pmdaSetFetchCallBack.

       pmdaFetch will allocate and resize the resp result structure, to  store
       values for the numpmid metrics listed in pmidlist.

       For  each  instance  listed in the profile (see pmdaProfile(3)) of each
       metric listed in pmidlist, the registered callback is required to  fill
       a  pmAtomValue  structure  with the metric’s value.  This value is then
       copied into the pmResult structure.

       For example, a PMDA has two metrics (A and B) and  an  instance  domain
       (X)  with  two  instances (X1 and X2).  The instance domain and metrics
       description tables (see pmdaInit(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_U32, 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} }, },
            };

       A callback for pmdaFetch could be defined as:

            static int
            myFetchCallBack(pmdaMetric *mdesc, unsigned int inst, pmdaAtomValue *atom)
            {
                __pmID_int    *idp = (__pmID_int *)&(mdesc->m_desc.pmid);

                switch (idp->item) {
                    case 0:
                        atom->l = /* assign some value for metric A */;
                        break;
                    case 1:
                        switch (inst) {
                            case 0:
                                atom->d = /* assign a value for metric B, instance X1 */;
                                break;
                            case 1:
                                atom->d = /* assign a value for metric B, instance X2 */;
                                break;
                            default:
                                return PM_ERR_INST;
                        }
                    default:
                        return PM_ERR_PMID;
                }
                return 1;
            }

       The metric description mdesc and the instance identifier inst are  used
       to  determine  which  metric  and  instance  is required.  The callback
       should return 1 on success, 0 if the  metric  value  is  not  currently
       available,  or  if  the  PMID  or  the  instance are not supported then
       PM_ERR_PMID or PM_ERR_INST should be returned, respectively.

DIAGNOSTICS

       The following error messages indicate that there is discrepancy between
       the  namespace,  pmdaMetric and pmdaIndom tables passed to pmdaInit(3),
       and the registered fetch callback:

       pmdaFetch: Requested metric metric is not defined
                      A  requested  metric  metric  is  not  listed   in   the
                      pmdaMetric  table.   The  namespace for this PMDA(3) may
                      contain additional metrics.

       pmdaFetch: PMID pmid not handled by fetch callback
                      The  fetch  callback  has  returned  PM_ERR_PMID.   This
                      indicates  that a metric may be listed in the pmdaMetric
                      table, but is not supported by the callback.

       pmdaFetch: Instance inst of PMID pmid not handled by fetch callback
                      The  fetch  callback  has  returned  PM_ERR_INST.   This
                      indicates  that  an  instance of metric is listed in the
                      pmdaIndom table, but is not supported by the callback.

       pmdaFetch: Fetch callback error:
                      The fetch callback  returned  a  result  other  than  0,
                      PM_ERR_PMID or PM_ERR_INST.

       pmdaFetch: Descriptor type (type) for metric pmid is bad
                      The  data type type specified for the metric pmid in the
                      pmdaMetric table is illegal.

       pmdaFetch will return -errno if an error occurred while allocating  the
       pmResult structure or copying the value from the pmAtomValue.

CAVEAT

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

SEE ALSO

       pmcd(1), PMAPI(3), PMDA(3), pmdaDaemon(3), pmdaDSO(3), pmdaInit(3)  and
       pmFetch(3).