--- name: "PMDA" section: "3" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/PMDA" --- # PMDA(3) introduction to the Performance Metrics Domain Agent support library ## NAME **PMDA** - introduction to the Performance Metrics Domain Agent support library ## C SYNOPSIS **#include \**\ **#include \** ... assorted routines ... **cc ... -lpcp\_pmda -lpcp** ## DESCRIPTION To assist in the development of Performance Metric Domain Agents (**PMDA**s) for the Performance Co-Pilot (PCP), a procedural interface is provided that extends the Performance Metrics Application Programming Interface ([**PMAPI**(3)](/PMAPI/3.md)) library. These procedures are designed to enable a programmer to quickly build a PMDA which can then be tested and refined. However, this also implies that a PMDA has a particular structure which may not be suitable for all PMDA implementations. Once you are familiar with the PCP and PMDA frameworks, you can quickly implement a new PMDA with only a few data structures and functions. This is covered in far greater detail in the *Performance Co-Pilot Programmer's Guide*. A PMDA is responsible for a set of performance metrics, in the sense that it must respond to requests from [**pmcd**(1)](/pmcd/1.md) for information about performance metrics, instance domains, and instantiated values. This man page contains sections of the **simple PMDA** which is located at *$PCP\_PMDAS\_DIR*/simple. ## COMMUNICATING WITH PMCD Two approaches may be used for connecting a PMDA to a [**pmcd**(1)](/pmcd/1.md) process. A Dynamic Shared Object (DSO) can be attached by [**pmcd**(1)](/pmcd/1.md) using [**dlopen**(3)](/dlopen/3.md) when the [**pmcd**(1)](/pmcd/1.md) process is started. A procedural interface referenced through a shared data structure is used to handle requests from [**pmcd**(1)](/pmcd/1.md) to the PMDA . The preferred approach is for a separate process (daemon) to communicate with [**pmcd**(1)](/pmcd/1.md) using the Performance Data Units (PDU) Inter-Process Communication (IPC) protocol. All PMDAs are launched and controlled by the [**pmcd**(1)](/pmcd/1.md) process on the local host. The requests from the clients are received by [**pmcd**(1)](/pmcd/1.md) and forwarded to the appropriate PMDAs. Responses, when required, are returned through [**pmcd**(1)](/pmcd/1.md) to the clients. The requests (PDUs) that may be sent to a PMDA from [**pmcd**(1)](/pmcd/1.md) are **PDU\_FETCH**, **PDU\_PROFILE**, **PDU\_INSTANCE\_REQ**, **PDU\_DESC\_REQ**, **PDU\_TEXT\_REQ** and **PDU\_RESULT**. If the PMDA implements any dynamic metrics it may also receive **PDU\_PMNS\_CHILD**, **PDU\_PMNS\_IDS**, **PDU\_PMNS\_NAMES** and **PDU\_PMNS\_TRAVERSE** PDUs. ## DEFAULT CALLBACKS FOR HANDLING PDUs To allow a consistent framework, [**pmdaMain**(3)](/pmdaMain/3.md) can be used by a daemon PMDA to handle the communication protocol using the same callbacks as a DSO PMDA. The structure **pmdaInterface** is used to convey the common procedural interface and state information that is used by [**pmcd**(1)](/pmcd/1.md) and a PMDA. This state information includes tables describing the supported metrics and instance domains. As most of the procedural interface is identical for all PMDAs, they are provided as part of this support library ([**pmdaProfile**(3)](/pmdaProfile/3.md), [**pmdaFetch**(3)](/pmdaFetch/3.md), [**pmdaInstance**(3)](/pmdaInstance/3.md), [**pmdaDesc**(3)](/pmdaDesc/3.md), [**pmdaText**(3)](/pmdaText/3.md) and [**pmdaStore**(3)](/pmdaStore/3.md)). However, these routines require access to the **pmdaInterface** state information so it must be correctly initialized using [**pmdaConnect**(3)](/pmdaConnect/3.md), [**pmdaDaemon**(3)](/pmdaDaemon/3.md), [**pmdaOpenLog**(3)](/pmdaOpenLog/3.md), [**pmdaDSO**(3)](/pmdaDSO/3.md), [**pmdaGetOpt**(3)](/pmdaGetOpt/3.md) and [**pmdaInit**(3)](/pmdaInit/3.md). ## INSTANCES AND INSTANCE DOMAINS Three structures are declared in */usr/include/pcp/pmda.h* which provide a framework for declaring the metrics and instances supported by the PMDA. Every instance requires a unique integer identifier and a unique name, as defined by the structure **pmdaInstid**: ``` /* * Instance description: index and name */ typedef struct { int i_inst; /* internal instance identifier */ char *i_name; /* external instance identifier */ } pmdaInstid; ``` `An instance domain requires its own unique identification` (**pmInDom**), `the number of instances the domain represents, and a pointer to an array of` `instance descriptions. This is defined in the structure` **pmdaIndom**: ``` /* * Instance domain description: unique instance id, * number of instances in this domain, and the list of * instances (not null terminated). */ typedef struct { pmInDom it_indom; /* indom, filled in */ int it_numinst; /* number of instances */ pmdaInstid *it_set; /* instance identifiers */ } pmdaIndom; ``` The **simple PMDA** has one instance domain for *simple*.*color* with three instances (*red*, *green* and *blue*), and a second instance domain for *simple*.*now* with instances which can be specified at run-time. These instance domains are defined as: ``` static pmdaInstid _color[] = { { 0, "red" }, { 1, "green" }, { 2, "blue" } }; static pmdaInstid *_timenow = NULL; static pmdaIndom indomtab[] = { #define COLOR_INDOM 0 { COLOR_INDOM, 3, _color }, #define NOW_INDOM 1 { NOW_INDOM, 0, NULL }, }; ``` `The preprocessor macros` **COLOR\_INDOM** `and` **NOW\_INDOM** `are used in the metric description table to identify the instance domains of` `individual metrics. These correspond to the` *serial* `value in the instance domain` **pmInDom** `structure (the` *domain* `field is set by` [**pmdaInit**(3)](/pmdaInit/3.md) `at run-time). The serial value must be unique for each instance domain` `within the PMDA.` `The indom table shown above which is usually passed to` [**pmdaInit**(3)](/pmdaInit/3.md) `does not need to be created` `if one wants to write one's own Fetch and Instance functions.` `See` [**pmdaInit**(3)](/pmdaInit/3.md) `for more details.` ## NAMESPACE `Every PMDA has its own unique` **namespace** `using the format defined in` [**PMNS**(5)](/PMNS/5.md). `In summary, the namespace matches the names of the metrics to the unique` `identifier. The` **simple PMDA** `defines five metrics:` *simple*.*numfetch*, *simple*.*color*, *simple*.*time*.*user,* *simple*.*time*.*sys* `and` *simple*.*now*. `The namespace for these metrics is defined in` *$PCP\_PMDAS\_DIR*/simple/pmns `and is installed as:` ``` simple { numfetch 253:0:0 color 253:0:1 time now 253:2:4 } simple.time { user 253:1:2 sys 253:1:3 } ``` `The domain number of` *253* `is obtained from` *$PCP\_VAR\_DIR*/pmns/stdpmid. `New PMDAs` `should specify a unique domain number in this file, and obtain the` `number during installation. This allows the domain number to change by` `modifying only the file` *$PCP\_VAR\_DIR*/pmns/stdpmid. `The` *simple.time* `and` *simple.now* `metrics are defined in separate clusters to the other metrics which allows a` `PMDA` `to support more than 1024 metrics, as well as grouping similar metrics` `together. Therefore, the item numbers for a new cluster may be identical to` `the item numbers in other clusters. The` **simple PMDA** `continues to increment the item numbers to permit direct mapping (see` [**pmdaInit**(3)](/pmdaInit/3.md)). `The namespace file should be installed and removed with the agent using` [**pmnsadd**(1)](/pmnsadd/1.md) `and` [**pmnsdel**(1)](/pmnsdel/1.md). `See the later sections on INSTALLATION and REMOVAL.` `A simple ASCII namespace can be constructed by creating a file similar to` *$PCP\_PMDAS\_DIR*/simple/root: ``` /* * fake "root" for validating the local PMNS subtree */ #include "$PCP_VAR_DIR/pmns/stdpmid" root { simple } #include "pmns" ``` `and can be referred to with the` **-n** `option in most PCP tools.` ## METRIC DESCRIPTIONS `Each metric requires a description` (**pmDesc**), `which contains its` `Performance Metric Identifier (PMID),` `data type specification, instance domain, semantics` `and units (see` [**pmLookupDesc**(3)](/pmLookupDesc/3.md)). `A handle is also provided for application specific information in the` **pmdaMetric** `structure:` ``` /* * Metric description: handle for extending description, * and the description. */ typedef struct { void* m_user; /* for users external use */ pmDesc m_desc; /* metric description */ } pmdaMetric; ``` `The` **simple PMDA** `defines the metrics as:` ``` static pmdaMetric metrictab[] = { /* numfetch */ { (void *)0, { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT, { 0,0,0,0,0,0} }, }, /* color */ { (void *)0, { PMDA_PMID(0,1), PM_TYPE_32, COLOR_INDOM, PM_SEM_INSTANT, { 0,0,0,0,0,0} }, }, /* time.user */ { (void*)0, { PMDA_PMID(1,2), PM_TYPE_DOUBLE, PM_INDOM_NULL, PM_SEM_COUNTER, { 0, 1, 0, 0, PM_TIME_SEC, 0 } }, }, /* time.sys */ { (void*)0, { PMDA_PMID(1,3), PM_TYPE_DOUBLE, PM_INDOM_NULL, PM_SEM_COUNTER, { 0, 1, 0, 0, PM_TIME_SEC, 0 } }, }, /* now */ { NULL, { PMDA_PMID(2,4), PM_TYPE_U32, NOW_INDOM, PM_SEM_INSTANT, { 0,0,0,0,0,0 } }, }, }; ``` `The macro` **PMDA\_PMID** `(defined in` */usr/include/pcp/pmda.h*) `is used to specify each metric's` *cluster* `and` *item* `fields of the associated` **pmID**. `As with instance domains, the` *domain* `field is set by` [**pmdaInit**(3)](/pmdaInit/3.md) `at run-time, however, the default domain is assumed to be defined by the` `PMDA` `in the macro` **MYDOMAIN**. `The metric table shown above which is usually passed to` [**pmdaInit**(3)](/pmdaInit/3.md) `does not need to be created` `if one wants to write one's own Fetch and Descriptor functions.` `See` [**pmdaInit**(3)](/pmdaInit/3.md) `for more details.` ## DSO PMDA `A` `PMDA` `that is run as a DSO is opened by` [**pmcd**(1)](/pmcd/1.md) `with` [**dlopen**(3)](/dlopen/3.md). [**pmcd**(1)](/pmcd/1.md) `will call the PMDA's` `initialization function that is specified in` *$PCP\_PMCDCONF\_PATH*. `This function is passed a pointer to a` **pmdaInterface** `structure which must be completed. Any callbacks which are` *not* `the default` `PMDA` `support library callbacks must be specified in the` **pmdaInterface** `structure.` `The` **simple PMDA** `uses its own store and fetch callback.` **simple\_fetch**() `calls` [**pmdaFetch**(3)](/pmdaFetch/3.md) `which requires a callback to be set with` [**pmdaSetFetchCallBack**(3)](/pmdaSetFetchCallBack/3.md) `as can be seen in` *$PCP\_PMDAS\_DIR*/simple/simple.c. `The flag` **\_isDSO** `is used to determine if the` `PMDA` `is a daemon or a DSO so that the correct initialization` `routine,` [**pmdaDaemon**(3)](/pmdaDaemon/3.md) `or` [**pmdaDSO**(3)](/pmdaDSO/3.md), `is called.` ## DAEMON PMDA `A` `PMDA` `that is run as a daemon is forked and executed by` [**pmcd**(1)](/pmcd/1.md). `Therefore, unlike a DSO PMDA,` `the starting point for a daemon PMDA is` **main**(). `The agent should parse the command line arguments, create` `a log file and initialize some data structures that` [**pmcd**(1)](/pmcd/1.md) `would initialize for a DSO agent.` `The` **pmdaInterface** `structure must be completely defined by the daemon PMDA.` `The function` [**pmdaDaemon**(3)](/pmdaDaemon/3.md) `can be called at the start of` **main**() `to set most of these fields. Command line parsing can be simplified by using` [**pmdaGetOpt**(3)](/pmdaGetOpt/3.md), `which is similar to` **getopt**(2), `but extracts a common set of options into the` **pmdaInterface** `structure.` *stderr* `can be mapped to a log file using` [**pmdaOpenLog**(3)](/pmdaOpenLog/3.md) `to simplify debugging and error messages. The connection to` [**pmcd**(1)](/pmcd/1.md) `can be made with` [**pmdaConnect**(3)](/pmdaConnect/3.md) `and the loop which handles the incoming PDUs,` [**pmdaMain**(3)](/pmdaMain/3.md), `should be the last function called. This can be seen in` *$PCP\_PMDAS\_DIR*/simple/simple.c. `The` **simple\_init**() `routine is common to an agent that can be run as both a Daemon and DSO` `PMDA.` ## HELP TEXT `Each PMDA must be able to provide` [**pmcd**(1)](/pmcd/1.md) `with the help text for each metric. Most PMDAs` `use specially created files with indexes to support` `efficient retrieval of the help text.` `Tools are provided with PCP to` `create the help text files of appropriate format. See` [**newhelp**(1)](/newhelp/1.md). ## INSTALLATION AND REMOVAL `A series of shell procedures are defined in` *$PCP\_SHARE\_DIR*/lib/pmdaproc.sh `which greatly simplify the installation and removal of a PMDA.` `The` *Install* `scripts for most PMDAs` `should only need to specify the name of the PMDA in` **iam**, `call` **pmdaSetup** `which sets up some default variables,` ```checks permissions (you have to be ``root'' to install or remove``` `a PMDA), checks that you're in the right directory (somewhere that ends` `with /pmdas/`*$iam*`), optionally generate` `the Performance Metrics Name Space (PMNS)` `and PMDA domain` `number files for Perl or Python PMDAs, checks the PMDA domain number is` `valid, etc.,` `specify the communication protocols,` `and finally call` **pmdaInstall** `to do all the work of updating the PMNS, updating the` [**pmcd**(1)](/pmcd/1.md) `control file, notifying or restarting` [**pmcd**(1)](/pmcd/1.md), `Beyond` **pmdaSetup** `and` **pmdaInstall**, `another optional helper routines is` **pmdaChooseConfigFile** `that may be used to interactively select or create a PMDA-specific` `configuration file,` `e.g. `[**pmdalogger**(1)](/pmdalogger/1.md). `The` *Remove* `scripts are even simpler as setting up the communication protocols` `are not required, so set the name of the PMDA in` *iam*, `then call` **pmdaSetup** `followed by a call to` **pmdaRemove**. `Further information is contained in the` *$PCP\_SHARE\_DIR*/lib/pmdaproc.sh `file and the following section.` `Optionally, a PMDA may provide an` *Upgrade* `script alongside` *Install* `and` *Remove*. `If present this script will be used by the` **pmcd** `startup process to ensure corrections to an installation` `have been made before starting the PMDA.` `Examples of such corrections include: updates to` *pmcd.conf* `when a PMDA script or binary has been renamed, when the` `PMDA supports a new format of its configuration file, or` `if there is some latent problem from an earlier install` `(e.g. some PMDAs may need to introduce use of the` **notready** `keyword in` *pmcd.conf*, `as described below).` ## INSTALLATION REFINEMENTS `As outlined below` `there are a number of variables that can be set in a PMDA's` *Install* `script to influence the behaviour of the installation procedures.` `These would typically need to be set before the call to` **pmdaInstall**, `but in some instances (like` *$iam* `and the cases specifically noted below),` `before the call to` **pmdaSetup**. `The following variables control the communication options between the PMDA` `and` [**pmcd**(1)](/pmcd/1.md). `At least one of` *$daemon\_opt*, *$dso\_opt*, *$perl\_opt* `or` *$python\_opt* `must be set to define the supported mode(s) of communication.` `If more than one of these is set the user will be prompted` `to make a selection when the` *Install* `script is run.` - *daemon\_opt* `We are willing to install the PMDA as a daemon.`\ `Default: true` - *dso\_opt* `We are willing to install the PMDA as a DSO, so` [**pmcd**(1)](/pmcd/1.md) `will use` `the dynamic linking loader to attach the PMDA's DSO at run-time and` `communication from` [**pmcd**(1)](/pmcd/1.md) `to the PMDA and back uses procedure calls, not an IPC channel.`\ `Default: false` - *dso\_entry* `For a DSO PMDA, this is the name of the PMDA's initialization routine.`\ `Default: `*${iam}*`_init` - *dso\_name* `For a DSO PMDA, this is the full pathanme of the PMDA's DSO file.`\ `Default: `*$PCP\_PMDAS\_DIR*`/`*$iam*`/pmda_`*$iam*`.`*$dso\_suffix* - *pipe\_opt* `For a daemon PMDA, is the default IPC channel via a` [**pipe**(2)](/pipe/2.md)?\ `Default: Platform-specific, so `**true**` for most, but `**false**` for Windows` - *perl\_opt* `We are willing to install the PMDA as a Perl script and` [**pmcd**(1)](/pmcd/1.md) `will use the` [**perl**(1)](/perl/1.md) `interpreter to run the PMDA.`\ `Default: false` - *pmda\_dir* `Full pathname to the directory where the PMDA's installation files` `(executable, script, PMNS source, help text source, etc) are to` `be found.`\ `Default: output from pwd(1)` `If set, must be done before the call to` **pmdaSetup**. - *pmda\_name* `For a daemon PMDA, this is the name of the PMDA's executable` `binary relative to the` *$pmda\_dir* `directory.`\ `Default: pmda`*$iam* - *python\_opt* `We are willing to install the PMDA as a Python script and` [**pmcd**(1)](/pmcd/1.md) `will use the` [**python**(1)](/python/1.md) `interpreter to run the PMDA.`\ `Default: false` - *ipc\_prot* `For a daemon PMDA, this can be set to either` **binary** `or` **text**. `The default is` **binary** `and` **text** `is rarely used.` `In addition, an optional IPC parameter` **notready** `can be used to signify that the PMDA will start up in the` **notready** `state, e.g. `**ipc\_prot="binary notready"**`.` `Note that the quotes are required.` `The IPC parameters for a PMDA appear in` **pmcd.conf** `in the` **IPC Params** `column.` `For further details, see` [**pmcd**(1)](/pmcd/1.md) `but basically` **pmcd** `will not issue any requests to a PMDA that has started in the` **notready** `state until the PMDA sends a` **PM\_ERR\_PMDAREADY** `PDU.` `This allows PMDAs with long startup times to initialize correctly` `without timing out.` `For details, see` [**pmdaSendError**(3)](/pmdaSendError/3.md) `and` [**pmcd**(1)](/pmcd/1.md). `When a PMDA is in the` **notready** `state, any client requests sent to` **pmcd** `for the PMDA domain will return with the` **PM\_ERR\_PMDANOTREADY** `error.` - *socket\_inet\_def* `For a daemon PMDA using a` [**socket**(2)](/socket/2.md) `as the IPC channel` `the default Internet port number or service name (if known).`\ `Default: ""` - *socket\_opt* `For a daemon PMDA, is the default IPC channel via a` [**socket**(2)](/socket/2.md)?\ `Default: Platform-specific, so `**false**` for most, but `**true**` for Windows` `The following variables control the PMNS options.` - *pmns\_dupok* `Most PMDAs do not have duplicate names for the same PMID in their PMNS.` `But if this is not the case,` *pmns\_dupok* `should be set to` **true**.\ `Default: false` - *pmns\_name* `Each PMDA will add one or more non-leaf nodes to the top of the` `PMNS. The most common case is that all of the metrics for a PMDA` `will be placed below the node named` *$iam*. `If this is not the case, and especially when the PMDA adds more than` `one non-leaf node at the top of the PMNS,` *pmns\_name* `needs to be set to the list of node names (separated by white space),` `e.g. for` [**pmdaproc**(1)](/pmdaproc/1.md) *pmns\_name* `is set to "proc cgroup hotproc".`\ `Default: `*$iam* `It is most important that if` *pmns\_name* `is set to a non-default value in the` *Install* `script then it must also be set to the same value in the` *Remove* `script.` - *pmns\_source* `The name of the PMDA's PMNS source file.` `By default, the name is interpreted as a relative pathname from` `the` *$pmda\_dir* `directory.`\ `Default: pmns` `The following variables provide assorted additional options associated with` `the installation of a PMDA.` - *args* `Additional command line args for the PMDA. These will be appended to the` `PMDA's control line in` *$PCP\_PMCDCONF\_PATH*.\ `Default: ""` - *check\_delay* `Delay (in seconds) after finishing the PMDA installation (or removal)` `before checking the availability of metrics from the PMDA.` `May need to be increased if the PMDA has a lengthy startup procedure.`\ `Default: 0.3` - *signal\_delay* `Delay (in seconds) after notifying` [**pmcd**(1)](/pmcd/1.md) `with a signal. Required to allow` [**pmcd**(1)](/pmcd/1.md) `to complete processing before proceeding to the next step of the` `installation (or removal).`\ `Default: 1` - *configdir* `Determines the directory in which a PMDA's configuration file will be` `stored. Used by` **pmdaChooseConfigFile** `so should be set before calling that procedure.`\ `Default: `*$PCP\_VAR\_DIR*`/config/`*$iam* - *configfile* `Preferred configuration file for the PMDA.` `Used by` **pmdaChooseConfigFile** `so should be set before calling that procedure.`\ `Default: ""` - *default\_configfile* `Default configuration file for the PMDA.` `Used by` **pmdaChooseConfigFile** `so should be set before calling that procedure.`\ `Default: ""` - *dso\_suffix* `Standard suffix for a DSO. Should not need to be changed under` `normal circumstances.`\ `Default: Platform-specific, so 'so' for Linux, 'dylib' for macOS, 'dll' for Windows, etc.` `If set, must be done before the call to` **pmdaSetup**. - *help\_source* `The name of the help text source file that should be used as input to` **pmnewhelp**(1). `By default, the name is interpreted as a relative pathname from` `the` *$pmda\_dir* `directory.`\ `Default: help` - *python\_name* `Full pathname of the Python script for a Python PMDA.`\ `Default: `*$pmda\_dir*`/pmda`*$iam*`.python or `*$pmda\_dir*`/pmda`*$iam*`.py` `The shell procedures in` *$PCP\_SHARE\_DIR*/lib/pmdaproc.sh `manipulate a number of temporary files using the variable` *$tmp* `as the prefix for the name of the temporary files.` *$tmp* `is a directory that is created, used and removed` `internally within the procedures of` *$PCP\_SHARE\_DIR*/lib/pmdaproc.sh `but can also be used as the prefix for temporary files needed by` `a PMDA's` *Install* `or` *Remove* `scripts.` `When used in this way,` *$tmp* ```should be followed by a ``/'' and then a suffix, e.g. ```*$tmp*/myfoo. `The` *Install* `and` *Remove* `scripts should not use` `other temporary file name prefixes nor use` [**sh**(1)](/sh/1.md) **trap** `statements to clean up temporary files as this is all done within` *$PCP\_SHARE\_DIR*/lib/pmdaproc.sh. ## CAVEAT `Failing to complete any of the data structures or calling any of the library` `routines out of order may cause unexpected behavior in the PMDA.` `Due to changes to the` [**PMAPI**(3)](/PMAPI/3.md) `and` [**PMDA**(3)](/PMDA/3.md) `API in the PCP 2.0 release, as described in the product release notes,` `PMDAs built using PCP 2.0 must specify` **PMDA\_INTERFACE\_2** `or later and link with` *libpcp\_pmda.so.2* `and` *libpcp.so.2*. `Pre-existing Daemon PMDAs specifying` **PMDA\_INTERFACE\_1** `will continue to function using the backwards compatible` *libpcp\_pmda.so.1* `and` *libpcp.so.1* `libraries and may be recompiled using the headers installed in` */usr/include/pcp1.x/* `without any modification. These backwards compatible headers and libraries` `are contained in the` *pcp.sw.compat* `subsystem.` ## DIAGNOSTICS `Any` `PMDA` `which uses this library can set` [**PMAPI**(3)](/PMAPI/3.md) `debugging control option` **libpmda** `(with` **-Dlibpmda** `on the command line or via` **3**pmSetDebug**(3))** `to` `to enable the display of debugging information which may be useful during` `development` `(see` [**pmdbg**(1)](/pmdbg/1.md)). `The` *status* `field of the` **pmdaInterface** `structure should be zero after` **pmdaDaemon**, **pmdaDSO**, **pmdaGetOpt**, **pmdaConnect** `and` **pmdaInit** `are called. A value less than zero indicates that initialization has failed.` `Some error messages that are common to most functions in this library are:` - **PMDA interface version** *interface* **not supported** `Most of the functions require that the` *comm.version* `field of the` **pmdaInterface** `structure be set to` **PMDA\_INTERFACE\_2** `or later.` **PMDA\_INTERFACE\_2** `or` **PMDA\_INTERFACE\_3** `implies that the` *version.two* `fields are correctly initialized,` `while` **PMDA\_INTERFACE\_4** `implies that the` *version.four* `fields are correctly initialized` `(see` [**pmdaDaemon**(3)](/pmdaDaemon/3.md) `and` [**pmdaDSO**(3)](/pmdaDSO/3.md)). ## FILES - */usr/include/pcp/pmda.h* `Header file for the` `PMDA` `support library.` - */usr/lib/libpcp\_pmda.so* `Dynamic library containing` `PMDA` `support library routines.` - *$PCP\_PMDAS\_DIR*/trivial `The source of the` **trivial PMDA**. - *$PCP\_PMDAS\_DIR*/simple `The source of the` **simple PMDA**. - *$PCP\_PMDAS\_DIR*/txmon `The source of the` **txmon PMDA**. - *$PCP\_PMCDCONF\_PATH* `Configuration file for` [**pmcd**(1)](/pmcd/1.md). - *$PCP\_VAR\_DIR*/pmns `Location of namespace descriptions for every PMDA.` - *$PCP\_VAR\_DIR*/pmns/stdpmid `The unique domain identifiers for each PMDA.` - *$PCP\_SHARE\_DIR*/lib/pmdaproc.sh `Shell procedures for installing and removing a PMDA.` ## PCP ENVIRONMENT `Environment variables with the prefix` **PCP\_** `are used to parameterize the file and directory names` `used by PCP.` `On each installation, the file` */etc/pcp.conf* `contains the local values for these variables.` `The` *$PCP\_CONF* `variable may be used to specify an alternative` `configuration file,` `as described in` [**pcp.conf**(5)](/pcp.conf/5.md). `Values for these variables may be obtained programmatically` `using the` [*pmGetConfig*(3)](/pmGetConfig/3.md) `function.` ## SEE ALSO [**dbpmda**(1)](/dbpmda/1.md), [**newhelp**(1)](/newhelp/1.md), [**pmcd**(1)](/pmcd/1.md), [**pmnsadd**(1)](/pmnsadd/1.md), [**pmnsdel**(1)](/pmnsdel/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**PMWEBAPI**(3)](/PMWEBAPI/3.md), [**pmdaConnect**(3)](/pmdaConnect/3.md), [**pmdaDaemon**(3)](/pmdaDaemon/3.md), [**pmdaDesc**(3)](/pmdaDesc/3.md), [**pmdaDSO**(3)](/pmdaDSO/3.md), [**pmdaFetch**(3)](/pmdaFetch/3.md), [**pmdaGetOpt**(3)](/pmdaGetOpt/3.md), [**pmdaInit**(3)](/pmdaInit/3.md), [**pmdaInstance**(3)](/pmdaInstance/3.md), [**pmdaMain**(3)](/pmdaMain/3.md), [**pmdaOpenLog**(3)](/pmdaOpenLog/3.md), [**pmdaProfile**(3)](/pmdaProfile/3.md), [**pmdaStore**(3)](/pmdaStore/3.md), [**pmdaText**(3)](/pmdaText/3.md), [**pmLookupDesc**(3)](/pmLookupDesc/3.md) `and` [**PMNS**(5)](/PMNS/5.md). `For a complete description of the` *pcp\_pmda* `library and the PMDA development process, refer to the Insight book` *Performance Co-Pilot Programmer's Guide*.