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
19       dependent 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
37                      domain  socket  set  up by the PMDA(3).  The port number
38                      must be specified in the e_port  field  of  the  pmdaExt
39                      structure.
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
46       access or modify them.
47
48       Traditionally  most  PMDAs  have  called  pmdaConnect  after  calls  to
49       pmdaDaemon(3),  pmdaGetOptions(3)  (or  pmdaGetOpt(3)) and pmdaInit(3).
50       If 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

DIAGNOSTICS

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

CAVEAT

67       The  PMDA  must be using PMDA_INTERFACE_2 or later, as specified in the
68       call to pmdaDaemon(3).
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