# pmaddderived

## NAME



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


## 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
           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



           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_.
    


* * *