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/pmda.h>
11
12       void pmdaConnect(pmdaInterface *dispatch);
13
14       cc ... -lpcp_pmda -lpcp
15

DESCRIPTION

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

CAVEAT

59       The PMDA must be using PMDA_INTERFACE_2 or later, as specified  in  the
60       call to pmdaDaemon(3).
61

DIAGNOSTICS

63       pmdaConnect  will  log  the  type  of connection made to pmcd(1) if the
64       PMAPI(3) debugging option libpmda has been set in the global  debugging
65       specification, as described in pmSetDebug(3).
66
67       If  an error occurs that is unrecoverable, dispatch->status is set to a
68       value less than 0, otherwise it is zero or positive.
69

SEE ALSO

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