oracular (3) pmAddDerivedText.3.gz

NAME

       pmAddDerivedText - add help text for a derived metric

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmAddDerivedText(const char *name, int type, const char *text);

       cc ... -lpcp

DESCRIPTION

       Derived  metrics  provide  a  way of extending the Performance Metrics Name Space (PMNS) with new metrics
       defined at the PCP client-side using expressions over the existing performance metrics.   Global  derived
       metrics  are  defined using pmRegisterDerived(3) or pmRegisterDerivedMetric(3) or pmLoadDerivedConfig(3),
       and per-context derived metrics are defined using pmAddDerived(3) or pmAddDerivedMetric(3).

       Once a derived metric has been defined, pmAddDerivedText may be used to associate the help text with  the
       derived metric identified by name.

       Help  text  may be a ``one line'' summary or a more verbose ``multi-line'' block of text, and type should
       be PM_TEXT_ONELINE or PM_TEXT_HELP respectively.  To associate both styles of help text  with  a  derived
       metric, pmAddDerivedText would need to be called twice with different values for type.

       Once  a  particular  type  of help text has been associated with a derived metric it cannot be deleted or
       redefined.

       Applications using the Performance Metrics Application Programming Interface (PMAPI) are able to retrieve
       help text for specific metrics using pmLookupText(3).

DIAGNOSTICS

       pmAddDerivedText returns zero on success, else an error code.

       The return value PM_ERR_NAME indicates name does not correspond to a previously defined derived metric.

       Repeated calls for the same name and type will result a return value of PM_ERR_TEXT.

       A return value of PM_ERR_ARG indicates that type is not one of the expected values.

SEE ALSO

       PCPIntro(1),  pmAddDerived(3),  pmAddDerivedMetric(3), PMAPI(3), pmLoadDerivedConfig(3), pmLookupText(3),
       pmRegisterDerived(3), pmRegisterDerivedMetric(3) and PMNS(5).