pmaddderivedtext(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | DIAGNOSTICS | SEE ALSO | COLOPHON

PMADDDERIVEDTEXT(3)      Library Functions Manual     PMADDDERIVEDTEXT(3)

NAME         top

       pmAddDerivedText - add help text for a derived metric

C SYNOPSIS         top

       #include <pcp/pmapi.h>

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

       cc ... -lpcp

DESCRIPTION         top

       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-con‐
       text  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 de‐
       rived metric it cannot be deleted or redefined.

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

DIAGNOSTICS         top

       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         top

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

COLOPHON         top

       This page is part of the PCP (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  is not part of the original manual page), send a
       mail to man-pages@man7.org

Performance Co-Pilot                                  PMADDDERIVEDTEXT(3)