NAME¶
pmdaConnect - establish a connection between a daemon PMDA and PMCD
C SYNOPSIS¶
#include <pcp/pmapi.h>
#include <pcp/impl.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).
DIAGNOSTICS¶
pmdaConnect will log the type of connection made to
pmcd(1) if the
PMAPI(3) debug control variable (
pmDebug) has the
DBG_TRACE_LIBPMDA flag set.
If an error occurs that is unrecoverable,
dispatch->status is set to a
value less than 0, otherwise it is zero or positive.
CAVEAT¶
The PMDA must be using
PMDA_INTERFACE_2 or later, as specified in the
call to
pmdaDaemon(3).
SEE ALSO¶
pmcd(1),
pipe(2),
socket(2),
PMAPI(3),
PMDA(3),
pmdaDaemon(3),
pmdaGetOpt(3),
pmdaGetOptions(3) and
pmdaInit(3).
