---

pmaddderived(3) — Linux manual page

PMADDDERIVED(3) Library Functions Manual PMADDDERIVED(3)

NAME top

 pmAddDerived, pmAddDerivedMetric - register a per-context derived
 metric name and definition

C SYNOPSIS top

 #include <pcp/pmapi.h>
 char *pmAddDerived(char *name, char *expr);
 int pmAddDerivedMetric(char *name, char *expr, char **errmsg);
 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.
 The pmAddDerived and pmAddDerivedMetric routines may be used to
 create per-context derived metrics, and can only be used after the
 current PMAPI context has been created with pmNewContext(3).
 Per-context derived metrics are similar in all aspects except
 scope to global derived metrics. The latter are defined across
 all PMAPI contexts and are created with the associated
 pmRegisterDerived(3), pmRegisterDerivedMetric(3) and
 pmLoadDerivedConfig(3) routines.
 The arguments to pmAddDerived are the name of the new derived met‐
 ric and expr is an expression defining how the values of name
 should be computed.
 pmAddDerivedMetric is the exact functional equivalent to pmAd‐
 dDerived except that it provides a simplified model of error han‐
 dling, where a formatted message is returned via the errmsg para‐
 meter.
 Refer to the pmRegisterDerived(3) man page for a complete descrip‐
 tion of the syntactic rules for name, the syntactic and semantic
 rules for expr, return values and the associated error reporting
 mechanisms, and the expression evaluation rules.
 Note that for per-context derived metrics, all syntactic and se‐
 mantic checks are performed at the time pmAddDerived or pmAd‐
 dDerivedMetric is called. This is different to global derived
 metrics where the semantic checks are delayed until the metric is
 used in a specific PMAPI context.
 There is no ``unregister'' method, so once registered a per-con‐
 text derived metric persists for the life of the PMAPI context,
 but it is destroyed as a side-effect of pmDestroyContext(3).

DIAGNOSTICS top

 On success, pmAddDerived returns NULL.
 If a syntactic error is found at the time of calling, the value
 returned by pmAddDerived is a pointer into expr indicating where
 the error was found. To identify what the error was, the applica‐
 tion should call pmDerivedErrStr(3) to retrieve the corresponding
 parser error message.
 pmAddDerivedMetric returns 0 and errmsg is undefined if the pars‐
 ing is successful.
 If the given expr does not conform to the required syntax pmAd‐
 dDerivedMetric returns -1 and a dynamically allocated error mes‐
 sage string in errmsg. The error message is terminated with a
 newline and includes both the input name and expr, along with an
 indicator of the position at which the error was detected. e.g.
 Error: pmAddDerivedMetric("my.disk.rates", ...) syntax
 error
 4rat(disk.dev.read)
 ^
 The position indicator line may be followed by an additional diag‐
 nostic line describing the nature of the error, when available.
 In the case of an error, the caller is responsible for calling
 free(3) to release the space allocated for errmsg.

SEE ALSO top

 PCPIntro(1), PMAPI(3), pmDerivedErrStr(3), pmDestroyContext(3),
 pmLoadDerivedConfig(3), pmNewContext(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 PMADDDERIVED(3)

---

Pages that refer to this page: pminfo(1), pmaddderivedtext(3), pmgetderivedcontrol(3), pmregisterderived(3), pmwebapi(3)

---

---

---