# pmdaconnect

## 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 in‐
                  ternet 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 in‐
                  ternet 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 de‐
           bugging 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.
    


* * *