1PMLOCALPMDA(3)             Library Functions Manual             PMLOCALPMDA(3)
2
3
4

NAME

6       __pmLocalPMDA - change the table of DSO PMDAs for PM_CONTEXT_LOCAL con‐
7       texts
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11       #include <pcp/impl.h>
12
13       int __pmLocalPMDA(int op, int domain,  const  char  *name,  const  char
14       *init)
15
16       cc ... -lpcp
17

DESCRIPTION

19       PCP  contexts of type PM_CONTEXT_LOCAL are used by clients that wish to
20       fetch metrics directly from one or more PMDAs on the local host without
21       involving  pmcd(1).   A  PMDA  that is to be used in this way must have
22       been built as a Dynamic Shared Object (DSO).
23
24       Historically the table of PMDAs available for use with PM_CONTEXT_LOCAL
25       was hardcoded to the following:
26
27       * The PMDA (or PMDAs) that export the operating system performance data
28         and data about process activity.  On Irix, the per-process  data  was
29         only available if $PMDA_LOCAL_PROC is set in the environment.
30       * The mmv PMDA.
31       * The  sample  PMDA  provided $PCP_LITE_SAMPLE or $PMDA_LOCAL_SAMPLE is
32         set in the environment - used mostly for QA and testing.
33
34       The initial table of PMDAs available for use with  PM_CONTEXT_LOCAL  is
35       now generated dynamically from all those PMDAs that have been installed
36       as DSOs on the local host.  The one  exception  is  the  ``pmcd''  PMDA
37       which only operates correctly in the address space of a running pmcd(1)
38       process and so is not available  to  an  application  using  a  PM_CON‐
39       TEXT_LOCAL context.
40
41       __pmLocalPMDA provides a number of services to amend the table of PMDAs
42       available for use with PM_CONTEXT_LOCAL.
43
44       The op argument specifies the what should be done and takes one of  the
45       following values and actions:
46
47       PM_LOCAL_ADD    Append  an  entry to the table for the PMDA with a Per‐
48                       formance Metrics Domain (PMD) of domain,  the  path  to
49                       the  DSO  PMDA is given by path and the PMDA's initial‐
50                       ization routine is init.
51
52       PM_LOCAL_DEL    Removes all entries  in  the  table  where  the  domain
53                       matches,  or  the  path matches.  Setting the arguments
54                       domain to -1 or path to NULL to force matching  on  the
55                       other argument.  The init argument is ignored.
56
57       PM_LOCAL_CLEAR  Remove all entries from the table.  All the other argu‐
58                       ments are ignored in this case.
59
60       The domain, name and init arguments have similar syntax  and  semantics
61       to  the  associated  fields in the pmcd(1) configuration file.  The one
62       difference is the path argument which is used by __pmLocalPMDA to  find
63       a  likely  looking DSO by searching in this order: $PCP_PMDAS_DIR/path,
64       path, $PCP_PMDAS_DIR/path.dso-suffix and finally path.dso-suffix  (dso-
65       suffix  is  the  local platform specific default file name suffix for a
66       DSO, e.g.  so for Linux, dylib for Mac OS X, dll for Windows, etc.).
67

RETURN VALUE

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

SEE ALSO

75       pmcd(1), PMAPI(3), pmNewContext(3) and __pmSpecLocalPMDA(3).
76
77
78
79Performance Co-Pilot                                            PMLOCALPMDA(3)
Impressum