NAME

       pmdaConnect - establish a connection between a daemon PMDA and PMCD

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/pmda.h>

       void pmdaConnect(pmdaInterface *dispatch);

       cc ... -lpcp_pmda -lpcp

DESCRIPTION

       pmdaConnect  initializes an IPC channel between a PMDA(3) and the pmcd(1) process on the local host.  The
       type of the connection is dependent on the e_io field of the pmdaExt structure:

       pmdaPipe       Use stdin/stdout to communicate; assumes this is a pipe created by pmcd before the PMDA(3)
                      was launched.

       pmdaInet       Assume pmcd(1) will establish a connection to an IPv4 internet domain socket set up by the
                      PMDA(3).  The name or number of the port must be specified in  the  e_sockname  or  e_port
                      fields of the pmdaExt structure, respectively.

       pmdaIPv6       Assume pmcd(1) will establish a connection to an IPv6 internet domain socket set up by the
                      PMDA(3).   The  name  or  number of the port must be specified in the e_sockname or e_port
                      fields of the pmdaExt structure, respectively.

       pmdaUnix       Assume pmcd(1) will establish a connection to a unix domain socket set up by the  PMDA(3).
                      The port number must be specified in the e_port field of the pmdaExt structure.

       pmdaUnknown    The initial value of e_io which defaults to using stdin/stdout.

       The  relevant  pmdaExt  fields  are  initialized  by pmdaDaemon(3) and set by pmdaGetOpt(3) or pmdaGetOp‐
       tions(3) so most PMDAs should not need to access or modify them.

       Traditionally most PMDAs have called pmdaConnect after  calls  to  pmdaDaemon(3),  pmdaGetOptions(3)  (or
       pmdaGetOpt(3))  and  pmdaInit(3).  If the PMDA requires significant processing at startup to identify the
       available metrics and/or instance domains before pmdaInit(3) can be called, then it risks timing out dur‐
       ing the handshake protocol that starts as soon as pmcd(1) launches the PMDA and does not  conclude  until
       pmdaConnect  is called.  In this case, it is advisable to move the pmdaConnect call, so that it comes af‐
       ter the call to pmdaGetOptions(3) (or pmdaGetOpt(3)) and before the call to pmdaInit(3).

CAVEAT

       The PMDA must be using PMDA_INTERFACE_2 or later, as specified in the call to pmdaDaemon(3).

DIAGNOSTICS

       pmdaConnect will log the type of connection made to pmcd(1) if the PMAPI(3) debugging option libpmda  has
       been set in the global debugging specification, as described in pmSetDebug(3).

       If an error occurs that is unrecoverable, dispatch->status is set to a value less than 0, otherwise it is
       zero or positive.

SEE ALSO

       pmcd(1),  pipe(2),  socket(2), PMAPI(3), PMDA(3), pmdaDaemon(3), pmdaGetOpt(3), pmdaGetOptions(3) and pm‐
       daInit(3).

Performance Co-Pilot                                   PCP                                        PMDACONNECT(3)