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).