User  |  Syst  |  Libr  |  Device  |  Files  |  Other  |  Admin  |  Head  |

---

   pmaddderived    ( 3 )

---

---

Имя (Name)

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

---

Синопсис C (C Synopsis)

#include <pcp/pmapi.h>

       char *pmAddDerived(char *name, char *expr);
       int pmAddDerivedMetric(char *name, char *expr, char **errmsg);

       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.

       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
       pmRegisterLoadConfig(3) routines.

       The arguments to pmAddDerived are the name of the new derived
       metric and expr is an expression defining how the values of name
       should be computed.

       pmAddDerivedMetric is the exact functional equivalent to
       pmAddDerived except that it provides a simplified model of error
       handling, where a formatted message is returned via the errmsg
       parameter.

       Refer to the pmRegisterDerived(3) man page for a complete
       description 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
       semantic checks are performed at the time pmAddDerived or
       pmAddDerivedMetric 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-
       context derived metric persists for the life of the PMAPI
       context, but it is destroyed as a side-effect of
       pmDestroyContext(3).

---

Диагностика (Diagnostic)

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
       application should call pmDerivedErrStr(3) to retrieve the
       corresponding parser error message.

       pmAddDerivedMetric returns 0 and errmsg is undefined if the
       parsing is successful.

       If the given expr does not conform to the required syntax
       pmAddDerivedMetric returns -1 and a dynamically allocated error
       message 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
       diagnostic 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)

PCPIntro(1), PMAPI(3), pmDerivedErrStr(3), pmDestroyContext(3),
       pmLoadDerivedConfig(3), pmNewContext(3), pmRegisterDerived(3),
       pmRegisterDerivedMetric(3) and PMNS(5).

---