__pmLocalPMDA(3)

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,
14               const char *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.
29       * The mmv PMDA.
30       * The sample PMDA provided $PCP_LITE_SAMPLE  or  $PMDA_LOCAL_SAMPLE  is
31         set in the environment - used mostly for QA and testing.
32
33       The  initial  table of PMDAs available for use with PM_CONTEXT_LOCAL is
34       now generated dynamically from all those PMDAs that have been installed
35       as  DSOs  on  the  local  host.  The one exception is the ``pmcd'' PMDA
36       which only operates correctly in the address space of a running pmcd(1)
37       process  and  so  is  not  available  to an application using a PM_CON‐
38       TEXT_LOCAL context.
39
40       __pmLocalPMDA provides a number of services to amend the table of PMDAs
41       available for use with PM_CONTEXT_LOCAL.
42
43       The  op argument specifies the what should be done and takes one of the
44       following values and actions:
45
46       PM_LOCAL_ADD    Append an entry to the table for the PMDA with  a  Per‐
47                       formance  Metrics  Domain  (PMD) of domain, the path to
48                       the DSO PMDA is given by path and the  PMDA's  initial‐
49                       ization routine is init.
50
51       PM_LOCAL_DEL    Removes  all  entries  in  the  table  where the domain
52                       matches, or the path matches.   Setting  the  arguments
53                       domain  to  -1 or path to NULL to force matching on the
54                       other argument.  The init argument is ignored.
55
56       PM_LOCAL_CLEAR  Remove all entries from the table.  All the other argu‐
57                       ments are ignored in this case.
58
59       The  domain,  name and init arguments have similar syntax and semantics
60       to the associated fields in the pmcd(1) configuration  file.   The  one
61       difference  is the path argument which is used by __pmLocalPMDA to find
62       a likely looking DSO by searching in this  order:  $PCP_PMDAS_DIR/path,
63       path,  $PCP_PMDAS_DIR/path.dso-suffix and finally path.dso-suffix (dso-
64       suffix is the local platform specific default file name  suffix  for  a
65       DSO, e.g.  so for Linux, dylib for Mac OS X, dll for Windows, etc.).
66

RETURN VALUE

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

NAME

C SYNOPSIS

DESCRIPTION

RETURN VALUE

SEE ALSO