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 "pmapi.h"
11       #include "libpcp.h"
12
13       int __pmLocalPMDA(int op, int domain, const char *name,
14               const char *init);
15
16       cc ... -lpcp
17

CAVEAT

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

DESCRIPTION

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

RETURN VALUE

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

SEE ALSO

82       pmcd(1), PMAPI(3), pmNewContext(3) and __pmSpecLocalPMDA(3).
83
84
85
86Performance Co-Pilot                                            PMLOCALPMDA(3)
Impressum