# __pmlocalpmda

## NAME



           **__pmLocalPMDA** - change the table of DSO PMDAs for PM_CONTEXT_LOCAL
           contexts
    


## C SYNOPSIS



           **#include "pmapi.h"**
           **#include "libpcp.h"**
    
           **int __pmLocalPMDA(int** _op_**, int** _domain_**, const char ***_name_**,**
                             **const char ***_init_**);**
    
           **cc ... -lpcp**
    


## CAVEAT



           This  documentation  is intended for internal Performance Co-Pilot
           (PCP) developer use.
    
           These interfaces are not part of the PCP APIs that are  guaranteed
           to  remain  fixed  across  releases, and they may not work, or may
           provide different semantics at some point in the future.
    


## DESCRIPTION



           PCP contexts of type **PM_CONTEXT_LOCAL** are  used  by  clients  that
           wish to fetch metrics directly from one or more PMDAs on the local
           host without involving pmcd(1).  A PMDA that is to be used in this
           way must have been built as a Dynamic Shared Object (DSO).
    
           Historically  the  table  of  PMDAs available for use with **PM_CON‐**
           **TEXT_LOCAL** was hardcoded to the following:
    
           * The PMDA (or PMDAs) that export the operating system performance
             data and data about process activity.
           * The **mmv** PMDA.
           * The **sample** PMDA provided **$PCP_LITE_SAMPLE** or **$PMDA_LOCAL_SAMPLE**
             is set in the environment - used mostly for QA and testing.
    
           The initial table of PMDAs available for use with **PM_CONTEXT_LOCAL**
           is now generated dynamically from all those PMDAs that have been
           installed as DSOs on the local host.  The one exception is the
           ``pmcd'' PMDA which only operates correctly in the address space
           of a running pmcd(1) process and so is not available to an appli‐
           cation using a **PM_CONTEXT_LOCAL** context.
    
           **__pmLocalPMDA** provides a number of services to amend the table of
           PMDAs available for use with **PM_CONTEXT_LOCAL**.
    
           The _op_ argument specifies the what should be done and takes one of
           the following values and actions:
    
           PM_LOCAL_ADD    Append an entry to the table for the PMDA with a
                           Performance Metrics Domain (PMD) of _domain_ , the
                           path to the DSO PMDA is given by _path_ and the PM‐
                           DA's initialization routine is _init_.
    
           PM_LOCAL_DEL    Removes all entries in the table where the _domain_
                           matches, or the _path_ matches.  Setting the argu‐
                           ments _domain_ to -1 or _path_ to **NULL** to force match‐
                           ing on the _other_ argument.  The _init_ argument is
                           ignored.
    
           PM_LOCAL_CLEAR  Remove all entries from the table.  All the other
                           arguments are ignored in this case.
    
           The _domain_ , _name_ and _init_ arguments have similar syntax and seman‐
           tics to the associated fields in the pmcd(1) configuration file.
           The one difference is the _path_ argument which is used by **__pmLo‐**
           **calPMDA** to find a likely looking DSO by searching in this order:
           **$PCP_PMDAS_DIR** /_path_ , _path_ , **$PCP_PMDAS_DIR** /_path_._dso-suffix_ and fi‐
           nally _path_._dso-suffix_ (_dso-suffix_ is the local platform specific
           default file name suffix for a DSO, e.g.  **so** for Linux, **dylib** for
           Mac OS X, **dll** for Windows, etc.).
    


## RETURN VALUE



           In most cases, **__pmLocalPMDA** returns 0 to indicate success.  If _op_
           is invalid, then the return value is **PM_ERR_CONV** else if there is
           no matching table entry found for a **PM_LOCAL_DEL** operation,
           PM_ERR_INDOM is returned.
    


* * *