'\"macro stdmacro
.\"
.\" Copyright (c) 2000-2004 Silicon Graphics, Inc.  All Rights Reserved.
.\" 
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\" 
.\"
.\" add in the -me strings for super and subscripts
.ie n \{\
.       ds [ \u\x'-0.25v'
.       ds ] \d
.       ds { \d\x'0.25v'
.       ds } \u
.\}
.el \{\
.       ds [ \v'-0.4m'\x'-0.2m'\s-3
.       ds ] \s0\v'0.4m'
.       ds { \v'0.4m'\x'0.2m'\s-3
.       ds } \s0\v'-0.4m'
.\}
.TH PMDA 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3PMDA\f1 \- introduction to the Performance Metrics Domain Agent support library
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.br
#include <pcp/pmda.h>
.sp
cc ... \-lpcp_pmda \-lpcp
.ft 1
.SH DESCRIPTION
.de CW
.ie t \f(CW\\$1\f1\\$2
.el \fI\\$1\f1\\$2
..
To assist in the development of Performance Metric Domain Agents 
.RB ( PMDA s)
for the Performance Co-Pilot (PCP),
a procedural interface is provided that extends the Performance Metrics
Application Programming Interface (
.BR PMAPI (3)) 
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.
.PP
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
.IR "Performance Co-Pilot Programmer's Guide" .
.PP
A
PMDA
is responsible for a set of performance metrics, in the sense that it must
respond to requests from
.BR pmcd (1)
for information about performance metrics, instance domains, and instantiated
values.
.PP
This man page contains sections of the 
.B simple PMDA
which is located at
.IR $PCP_PMDAS_DIR /simple.
.SH COMMUNICATING WITH PMCD
Two approaches may be used for connecting a
PMDA 
to a 
.BR pmcd (1)
process.  A Dynamic Shared Object (DSO) can be attached by
.BR pmcd (1)
using
.BR dlopen (3)
when the
.BR pmcd (1)
process is started.  A procedural interface referenced through a shared data
structure is used to handle requests from
.BR pmcd (1)
to the PMDA .
.PP
The preferred approach is for a separate process (daemon) to communicate with 
.BR pmcd (1)
using the Performance Data Units (PDU) Inter-Process Communication (IPC)
protocol.
.PP
All PMDAs
are launched and controlled by the
.BR pmcd (1)
process on the local host.  The requests from the clients are received by
.BR pmcd (1)
and forwarded to the appropriate PMDAs.
Responses, when required, are returned through 
.BR pmcd (1)
to the clients.  The requests (PDUs) that may be sent to a
PMDA
from
.BR pmcd (1)
are
.BR PDU_FETCH ,
.BR PDU_PROFILE ,
.BR PDU_INSTANCE_REQ ,
.BR PDU_DESC_REQ ,
.BR PDU_TEXT_REQ 
and
.BR PDU_RESULT .
If the PMDA implements any dynamic metrics it may also receive
.BR PDU_PMNS_CHILD ,
.BR PDU_PMNS_IDS ,
.B PDU_PMNS_NAMES
and
.B PDU_PMNS_TRAVERSE
PDUs.
.SH DEFAULT CALLBACKS FOR HANDLING PDUs
To allow a consistent framework,
.BR pmdaMain (3)
can be used by a daemon
PMDA
to handle the communication protocol using the same callbacks as a DSO
PMDA.
The structure
.B pmdaInterface
is used to convey the common procedural interface and state information that is
used by 
.BR pmcd (1)
and a PMDA.
This state information includes tables describing the supported metrics and
instance domains.
.PP
As most of the
procedural interface is identical for all PMDAs,
they are provided as part of
this support library
.RB ( pmdaProfile (3),
.BR pmdaFetch (3),
.BR pmdaInstance (3),
.BR pmdaDesc (3),
.BR pmdaText (3)
and
.BR pmdaStore (3)). 
However, these routines require access to the 
.B pmdaInterface
state information so it must be correctly initialized using 
.BR pmdaConnect (3),
.BR pmdaDaemon (3),
.BR pmdaOpenLog (3),
.BR pmdaDSO (3),
.BR pmdaGetOpt (3)
and
.BR pmdaInit (3).
.SH INSTANCES AND INSTANCE DOMAINS
Three structures are declared in
.I /usr/include/pcp/pmda.h
which provide a framework for declaring the metrics and instances supported by
the 
PMDA.
.PP
Every instance requires a unique integer identifier and a unique name, as defined by
the structure
.BR pmdaInstid :
.PP
.nf
.ft CW
.in +0.5i
/*
 * Instance description: index and name
 */

typedef struct {
    int         i_inst;        /* internal instance identifier */
    char        *i_name;       /* external instance identifier */
} pmdaInstid;
.in
.fi
.PP
An instance domain requires its own unique identification
.RB ( pmInDom ),
the number of instances the domain represents, and a pointer to an array of
instance descriptions.  This is defined in the structure 
.BR pmdaIndom :
.PP
.nf
.ft CW
.in +0.5i
/*
 * 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;
.in
.fi
.ft 1
.PP
The
.B simple PMDA 
has one instance domain for 
.IR simple . color
with three instances
.RI ( red ,
.I green 
and
.IR blue ),
and a second instance domain for
.IR simple . now
with instances which can be specified at run-time.
These instance domains are defined as:
.PP
.nf
.ft CW
.in +0.5i
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 },
};
.in
.fi
.PP
The preprocessor macros
.B COLOR_INDOM
and
.B NOW_INDOM
are used in the metric description table to identify the instance domains of
individual metrics.  These correspond to the
.I serial
value in the instance domain 
.B pmInDom
structure (the 
.I domain
field is set by
.BR pmdaInit (3)
at run-time).  The serial value must be unique for each instance domain
within the PMDA. 
.PP
The indom table shown above which is usually passed to 
.BR pmdaInit (3)
does not need to be created 
if one wants to write one's own Fetch and Instance functions.
See 
.BR pmdaInit (3)
for more details.
.SH NAMESPACE
Every PMDA has its own unique 
.B namespace 
using the format defined in 
.BR pmns (5). 
In summary, the namespace matches the names of the metrics to the unique
identifier.  The
.B simple PMDA
defines five metrics:
.IR simple . numfetch ,
.IR simple . color ,
.IR simple . time . user,
.IR simple . time . sys
and
.IR simple . now .
The namespace for these metrics is defined in
.IR $PCP_PMDAS_DIR /simple/pmns
and is installed as:
.PP
.nf
.ft CW
.in +0.5in
simple {
    numfetch    253:0:0
    color       253:0:1
    time
    now         253:2:4
}

simple.time {
    user        253:1:2
    sys         253:1:3
}
.in
.fi
.PP
The domain number of
.I 253
is obtained from
.IR $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
.IR $PCP_VAR_DIR /pmns/stdpmid.
.PP
The
.I simple.time
and
.I 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 
.B simple PMDA 
continues to increment the item numbers to permit direct mapping (see
.BR pmdaInit (3)).
.PP
The namespace file should be installed and removed with the agent using 
.BR pmnsadd (1)
and
.BR pmnsdel (1).
See the later sections on INSTALLATION and REMOVAL.
.PP
A simple ASCII namespace can be constructed by creating a file similar to
.IR $PCP_PMDAS_DIR /simple/root:
.PP
.nf
.ft CW
.in +0.5i
/*
 * fake "root" for validating the local PMNS subtree
 */

#include "$PCP_VAR_DIR/pmns/stdpmid"

root { simple }

#include "pmns"

.in
.fi
.PP
and can be referred to with the
.B \-n
option in most PCP tools.
.SH METRIC DESCRIPTIONS
Each metric requires a description
.RB ( pmDesc ), 
which contains its
Performance Metric Identifier (PMID),
data type specification, instance domain, semantics 
and units (see 
.BR pmLookupDesc (3)).
A handle is also provided for application specific information in the
.B pmdaMetric
structure:
.PP
.nf
.ft CW
.in +0.5i
/*
 * Metric description: handle for extending description, 
 * and the description.
 */

typedef struct {
    void*       m_user;         /* for users external use */
    pmDesc      m_desc;         /* metric description */
} pmdaMetric;
.in
.fi
.PP
The 
.B simple PMDA
defines the metrics as:
.PP
.nf
.ft CW
.in +0.5i
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 } }, },
};
.in
.fi
.PP
The macro
.B PMDA_PMID
(defined in
.IR /usr/include/pcp/pmda.h )
is used to specify each metric's
.I cluster
and
.I item 
fields of the associated
.BR pmID .
As with instance domains, the
.I domain
field is set by
.BR pmdaInit (3)
at run-time, however, the default domain is assumed to be defined by the
PMDA 
in the macro
.BR MYDOMAIN .
.PP
The metric table shown above which is usually passed to 
.BR pmdaInit (3)
does not need to be created 
if one wants to write one's own Fetch and Descriptor functions.
See 
.BR pmdaInit (3)
for more details.
.SH DSO PMDA
A 
PMDA
that is run as a DSO is opened by 
.BR pmcd (1)
with
.BR dlopen (3).
.BR pmcd (1)
will call the PMDA's
initialization function that is specified in
.IR $PCP_PMCDCONF_PATH .
This function is passed a pointer to a
.B pmdaInterface 
structure which must be completed.  Any callbacks which are
.I not
the default 
PMDA
support library callbacks must be specified in the
.B pmdaInterface
structure. 
.PP
The
.B simple PMDA 
uses its own store and fetch callback.  
.BR simple_fetch ()
calls 
.BR pmdaFetch (3)
which requires a callback to be set with
.BR pmdaSetFetchCallBack (3)
as can be seen in
.IR $PCP_PMDAS_DIR /simple/simple.c.
.PP
The flag
.B _isDSO
is used to determine if the 
PMDA
is a daemon or a DSO so that the correct initialization
routine,
.BR pmdaDaemon (3)
or
.BR pmdaDSO (3),
is called.
.SH DAEMON PMDA
A 
PMDA
that is run as a daemon is forked and executed by 
.BR pmcd (1).
Therefore, unlike a DSO PMDA,
the starting point for a daemon PMDA is
.BR main ().
The agent should parse the command line arguments, create
a log file and initialize some data structures that 
.BR pmcd (1)
would initialize for a DSO agent.
.PP
The
.B pmdaInterface
structure must be completely defined by the daemon PMDA.
The function
.BR pmdaDaemon (3)
can be called at the start of 
.BR main ()
to set most of these fields.  Command line parsing can be simplified by using
.BR pmdaGetOpt (3),
which is similar to 
.BR getopt (2),
but extracts a common set of options into the 
.B pmdaInterface
structure.
.I stderr 
can be mapped to a log file using 
.BR pmdaOpenLog (3)
to simplify debugging and error messages.  The connection to 
.BR pmcd (1)
can be made with
.BR pmdaConnect (3)
and the loop which handles the incoming PDUs,
.BR pmdaMain (3),
should be the last function called.  This can be seen in
.IR $PCP_PMDAS_DIR /simple/simple.c.
.PP
The
.BR simple_init ()
routine is common to an agent that can be run as both a Daemon and DSO
PMDA.
.SH HELP TEXT
Each PMDA must be able to provide 
.BR pmcd (1)
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 
.BR newhelp (1).
.SH INSTALLATION AND REMOVAL
A series of shell procedures are defined in 
.IR $PCP_SHARE_DIR /lib/pmdaproc.sh 
which greatly simplify the installation and removal of a PMDA.
.PP
The
.I Install
scripts for most PMDAs
should only need to specify the name of the PMDA in
.BR iam ,
call
.B 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/\fI$iam\fP), 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
.B pmdaInstall
to do all the work of updating the PMNS, updating the
.BR pmcd (1)
control file, notifying or restarting
.BR pmcd (1),
.PP
Beyond
.B pmdaSetup
and
.BR pmdaInstall ,
another optional helper routines is
.B pmdaChooseConfigFile
that may be used to interactively select or create a PMDA-specific
configuration file,
e.g. \c
.BR pmdalogger (1).
.PP
The 
.I Remove
scripts are even simpler as setting up the communication protocols
are not required, so set the name of the PMDA in
.IR iam ,
then call
.B pmdaSetup
followed by a call to
.BR pmdaRemove .
.PP
Further information is contained in the
.IR $PCP_SHARE_DIR /lib/pmdaproc.sh
file and the following section.
.PP
Optionally, a PMDA may provide an
.I Upgrade
script alongside
.I Install
and
.IR Remove .
If present this script will be used by the
.B pmcd
startup process to ensure corrections to an installation
have been made before starting the PMDA.
Examples of such corrections include: updates to
.I 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
.B notready
keyword in
.IR pmcd.conf ,
as described below).
.SH INSTALLATION REFINEMENTS
As outlined below
there are a number of variables that can be set in a PMDA's
.I Install
script to influence the behaviour of the installation procedures.
These would typically need to be set before the call to
.BR pmdaInstall ,
but in some instances (like
.I $iam
and the cases specifically noted below),
before the call to
.BR pmdaSetup .
.PP
The following variables control the communication options between the PMDA
and
.BR pmcd (1).
At least one of
.IR $daemon_opt ,
.IR $dso_opt ,
.I $perl_opt
or
.I $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
.I Install
script is run.
.TP 16n
.I daemon_opt
We are willing to install the PMDA as a daemon.
.br
Default: true
.TP
.I dso_opt
We are willing to install the PMDA as a DSO, so
.BR pmcd (1)
will use
the dynamic linking loader to attach the PMDA's DSO at run-time and
communication from
.BR pmcd (1)
to the PMDA and back uses procedure calls, not an IPC channel.
.br
Default: false
.TP
.I dso_entry
For a DSO PMDA, this is the name of the PMDA's initialization routine.
.br
Default: \fI${iam}\fP_init
.TP
.I dso_name
For a DSO PMDA, this is the full pathanme of the PMDA's DSO file.
.br
Default: \fI$PCP_PMDAS_DIR\fP/\fI$iam\fP/pmda_\fI$iam\fP.\fI$dso_suffix\fP
.TP
.I pipe_opt
For a daemon PMDA, is the default IPC channel via a
.BR pipe (2)?
.br
Default: Platform-specific, so \fBtrue\fP for most, but \fBfalse\fP for Windows
.TP
.I perl_opt
We are willing to install the PMDA as a Perl script and
.BR pmcd (1)
will use the
.BR perl (1)
interpreter to run the PMDA.
.br
Default: false
.TP
.I 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.
.br
Default: output from pwd(1)
.RS 16n
.PP
If set, must be done before the call to
.BR pmdaSetup .
.RE
.TP
.I pmda_name
For a daemon PMDA, this is the name of the PMDA's executable
binary relative to the 
.I $pmda_dir
directory.
.br
Default: pmda\fI$iam\fP
.TP
.I python_opt
We are willing to install the PMDA as a Python script and
.BR pmcd (1)
will use the
.BR python (1)
interpreter to run the PMDA.
.br
Default: false
.TP
.I ipc_prot
For a daemon PMDA, this can be set to either
.B binary
or
.BR text .
The default is
.B binary
and
.B text
is rarely used.
In addition, an optional IPC parameter
.B notready
can be used to signify that the PMDA will start up in the
.B notready
state, e.g. \fBipc_prot="binary notready"\fP.
Note that the quotes are required.
The IPC parameters for a PMDA appear in
.B pmcd.conf
in the
.B "IPC Params"
column.
For further details, see
.BR pmcd (1)
but basically
.B pmcd
will not issue any requests to a PMDA that has started in the
.B notready
state until the PMDA sends a
.B PM_ERR_PMDAREADY
PDU.
This allows PMDAs with long startup times to initialize correctly
without timing out.
For details, see
.BR pmdaSendError (3)
and
.BR pmcd (1).
When a PMDA is in the
.B notready
state, any client requests sent to
.B pmcd
for the PMDA domain will return with the
.BR PM_ERR_PMDANOTREADY
error.
.TP
.I socket_inet_def
For a daemon PMDA using a
.BR socket (2)
as the IPC channel
the default Internet port number or service name (if known).
.br
Default: ""
.TP
.I socket_opt
For a daemon PMDA, is the default IPC channel via a
.BR socket (2)?
.br
Default: Platform-specific, so \fBfalse\fP for most, but \fBtrue\fP for Windows
.PP
The following variables control the PMNS options.
.TP 16n
.I pmns_dupok
Most PMDAs do not have duplicate names for the same PMID in their PMNS.
But if this is not the case,
.I pmns_dupok
should be set to
.BR true .
.br
Default: false
.TP
.I 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
.IR $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,
.I pmns_name
needs to be set to the list of node names (separated by white space),
e.g. for
.BR pmdaproc (1)
.I pmns_name
is set to "proc cgroup hotproc".
.br
Default: \fI$iam\fP
.RS 16n
.PP
It is most important that if
.I pmns_name
is set to a non-default value in the
.I Install
script then it must also be set to the same value in the
.I Remove
script.
.RE
.TP
.I pmns_source
The name of the PMDA's PMNS source file.
By default, the name is interpreted as a relative pathname from
the
.I $pmda_dir
directory.
.br
Default: pmns
.PP
The following variables provide assorted additional options associated with
the installation of a PMDA.
.TP 16n
.I args
Additional command line args for the PMDA.  These will be appended to the
PMDA's control line in
.IR $PCP_PMCDCONF_PATH .
.br
Default: ""
.TP
.I 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.
.br
Default: 0.3
.TP
.I signal_delay
Delay (in seconds) after notifying
.BR pmcd (1)
with a signal.  Required to allow
.BR pmcd (1)
to complete processing before proceeding to the next step of the
installation (or removal).
.br
Default: 1
.TP
.I configdir
Determines the directory in which a PMDA's configuration file will be
stored.  Used by
.B pmdaChooseConfigFile
so should be set before calling that procedure.
.br
Default: \fI$PCP_VAR_DIR\fP/config/\fI$iam\fP
.TP
.I configfile
Preferred configuration file for the PMDA.
Used by
.B pmdaChooseConfigFile
so should be set before calling that procedure.
.br
Default: ""
.TP
.I default_configfile
Default configuration file for the PMDA.
Used by
.B pmdaChooseConfigFile
so should be set before calling that procedure.
.br
Default: ""
.TP
.I dso_suffix
Standard suffix for a DSO.  Should not need to be changed under
normal circumstances.
.br
Default: Platform-specific, so 'so' for Linux, 'dylib' for Mac OS X, 'dll' for Windows, etc.
.RS 16n
.PP
If set, must be done before the call to
.BR pmdaSetup .
.RE
.TP
.I help_source
The name of the help text source file that should be used as input to
.BR pmnewhelp (1).
By default, the name is interpreted as a relative pathname from
the
.I $pmda_dir
directory.
.br
Default: help
.TP
.I python_name
Full pathname of the Python script for a Python PMDA.
.br
Default: \fI$pmda_dir\fP/pmda\fI$iam\fP.python or \fI$pmda_dir\fP/pmda\fI$iam\fP.py
.PP
The shell procedures in 
.IR $PCP_SHARE_DIR /lib/pmdaproc.sh 
manipulate a number of temporary files using the variable
.I $tmp
as the prefix for the name of the temporary files.
.I $tmp
is a directory that is created, used and removed
internally within the procedures of
.IR $PCP_SHARE_DIR /lib/pmdaproc.sh 
but can also be used as the prefix for temporary files needed by 
a PMDA's
.I Install
or
.I Remove
scripts.
When used in this way, 
.I $tmp
should be followed by a ``/'' and then a suffix, e.g. \c
.IR $tmp /myfoo.
The
.I Install
and
.I Remove
scripts should not use
other temporary file name prefixes nor use
.BR sh (1)
.B trap
statements to clean up temporary files as this is all done within
.IR $PCP_SHARE_DIR /lib/pmdaproc.sh.
.SH DIAGNOSTICS
Any 
PMDA
which uses this library can set
.BR PMAPI (3)
debugging control option
.B libpmda
(with
.B \-Dlibpmda
on the command line or via
.BR 3 pmSetDebug (3))
to 
to enable the display of debugging information which may be useful during
development
(see
.BR pmdbg (1)).
.PP
The
.I status 
field of the 
.B pmdaInterface
structure should be zero after 
.BR pmdaDaemon ,
.BR pmdaDSO ,
.BR pmdaGetOpt ,
.BR pmdaConnect
and
.B pmdaInit
are called.  A value less than zero indicates that initialization has failed.
.PP
Some error messages that are common to most functions in this library are:
.TP 15
.BI "PMDA interface version " interface " not supported"
Most of the functions require that the
.I comm.version
field of the
.B pmdaInterface
structure be set to
.B PMDA_INTERFACE_2
or later.
.B PMDA_INTERFACE_2
or
.B PMDA_INTERFACE_3
implies that the 
.I version.two
fields are correctly initialized,
while
.B PMDA_INTERFACE_4
implies that the 
.I version.four
fields are correctly initialized
(see
.BR pmdaDaemon (3)
and
.BR pmdaDSO (3)).
.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.
.PP
Due to changes to the
.BR PMAPI (3)
and
.BR PMDA (3)
API in the PCP 2.0 release, as described in the product release notes, 
PMDAs built using PCP 2.0 must specify 
.B PMDA_INTERFACE_2
or later and link with
.I libpcp_pmda.so.2
and
.IR libpcp.so.2 .
Pre-existing Daemon PMDAs specifying 
.B PMDA_PROTOCOL_1
will continue to function using the backwards compatible 
.I libpcp_pmda.so.1
and
.I libpcp.so.1
libraries and may be recompiled using the headers installed in
.I "/usr/include/pcp1.x/"
without any modification.  These backwards compatible headers and libraries
are contained in the
.I pcp.sw.compat
subsystem.
.SH FILES
.TP 10
.I /usr/include/pcp/pmda.h
Header file for the 
PMDA
support library.
.TP
.I /usr/lib/libpcp_pmda.so
Dynamic library containing 
PMDA 
support library routines.
.TP
.IR $PCP_PMDAS_DIR /trivial
The source of the
.BR "trivial PMDA" .
.TP
.IR $PCP_PMDAS_DIR /simple
The source of the
.BR "simple PMDA" .
.TP
.IR $PCP_PMDAS_DIR /txmon
The source of the
.BR "txmon PMDA" .
.TP
.I $PCP_PMCDCONF_PATH
Configuration file for
.BR pmcd (1).
.TP
.IR $PCP_VAR_DIR /pmns
Location of namespace descriptions for every PMDA.
.TP
.IR $PCP_VAR_DIR /pmns/stdpmid
The unique domain identifiers for each PMDA.
.TP
.IR $PCP_SHARE_DIR /lib/pmdaproc.sh
Shell procedures for installing and removing a PMDA.
.SH "PCP ENVIRONMENT"
Environment variables with the prefix
.B PCP_
are used to parameterize the file and directory names
used by PCP.
On each installation, the file
.I /etc/pcp.conf
contains the local values for these variables.
The
.I $PCP_CONF
variable may be used to specify an alternative
configuration file,
as described in
.BR pcp.conf (5).
Values for these variables may be obtained programmatically
using the
.IR pmGetConfig (3)
function.
.SH SEE ALSO
.BR dbpmda (1),
.BR newhelp (1),
.BR pmcd (1),
.BR pmnsadd (1),
.BR pmnsdel (1),
.BR PMAPI (3),
.BR pmdaConnect (3),
.BR pmdaDaemon (3),
.BR pmdaDesc (3),
.BR pmdaDSO (3),
.BR pmdaFetch (3),
.BR pmdaGetOpt (3),
.BR pmdaInit (3),
.BR pmdaInstance (3),
.BR pmdaMain (3),
.BR pmdaOpenLog (3),
.BR pmdaProfile (3),
.BR pmdaStore (3),
.BR pmdaText (3),
.BR pmLookupDesc (3)
and
.BR pmns (5).
.PP
For a complete description of the
.I pcp_pmda
library and the PMDA development process, refer to the Insight book
.IR "Performance Co-Pilot Programmer's Guide" .