1PMDACONNECT(3)             Library Functions Manual             PMDACONNECT(3)
2
3
4

NAME

6       pmdaConnect - establish a connection between a daemon PMDA and PMCD
7

C SYNOPSIS

9       #include <pcp/pmapi.h>
10       #include <pcp/impl.h>
11       #include <pcp/pmda.h>
12
13       void pmdaConnect(pmdaInterface *dispatch);
14
15       cc ... -lpcp_pmda -lpcp
16

DESCRIPTION

18       pmdaConnect  initializes  an  IPC  channel  between  a  PMDA(3) and the
19       pmcd(1) process on the local host.   The  type  of  the  connection  is
20       dependent on the e_io field of the pmdaExt structure:
21
22       pmdaPipe       Use  stdin/stdout to communicate; assumes this is a pipe
23                      created by pmcd before the PMDA(3) was launched.
24
25       pmdaInet       Assume pmcd(1) will establish a connection  to  an  IPv4
26                      internet  domain socket set up by the PMDA(3).  The name
27                      or number of the port must be specified in  the  e_sock‐
28                      name  or e_port fields of the pmdaExt structure, respec‐
29                      tively.
30
31       pmdaIPv6       Assume pmcd(1) will establish a connection  to  an  IPv6
32                      internet  domain socket set up by the PMDA(3).  The name
33                      or number of the port must be specified in  the  e_sock‐
34                      name  or e_port fields of the pmdaExt structure, respec‐
35                      tively.
36
37       pmdaUnix       Assume pmcd(1) will establish a  connection  to  a  unix
38                      domain  socket  set  up by the PMDA(3).  The port number
39                      must be specified in the e_port  field  of  the  pmdaExt
40                      structure.
41
42       pmdaUnknown    The  initial  value  of  e_io  which  defaults  to using
43                      stdin/stdout.
44
45       The relevant pmdaExt fields are initialized by pmdaDaemon(3) and set by
46       pmdaGetOpt(3)  or  pmdaGetOptions(3)  so  most PMDAs should not need to
47       access or modify them.
48
49       Traditionally  most  PMDAs  have  called  pmdaConnect  after  calls  to
50       pmdaDaemon(3),  pmdaGetOptions(3)  (or  pmdaGetOpt(3)) and pmdaInit(3).
51       If the PMDA requires significant processing at startup to identify  the
52       available  metrics  and/or  instance  domains before pmdaInit(3) can be
53       called, then it risks timing out during  the  handshake  protocol  that
54       starts as soon as pmcd(1) launches the PMDA and does not conclude until
55       pmdaConnect is called.  In this case, it is advisable to move the pmda‐
56       Connect  call, so that it comes after the call to pmdaGetOptions(3) (or
57       pmdaGetOpt(3)) and before the call to pmdaInit(3).
58

DIAGNOSTICS

60       pmdaConnect will log the type of connection  made  to  pmcd(1)  if  the
61       PMAPI(3)  debug  control  variable  (pmDebug) has the DBG_TRACE_LIBPMDA
62       flag set.
63
64       If an error occurs that is unrecoverable, dispatch->status is set to  a
65       value less than 0, otherwise it is zero or positive.
66

CAVEAT

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

SEE ALSO

72       pmcd(1), pipe(2), socket(2), PMAPI(3), PMDA(3), pmdaDaemon(3),  pmdaGe‐
73       tOpt(3), pmdaGetOptions(3) and pmdaInit(3).
74
75
76
77Performance Co-Pilot                  PCP                       PMDACONNECT(3)
Impressum