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
       pmdaGetOptions(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
       during  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 after 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
       pmdaInit(3).

Performance Co-Pilot                                   PCP                                        PMDACONNECT(3)