NAME | C SYNOPSIS | DESCRIPTION | DIAGNOSTICS | CAVEAT | SEE ALSO | COLOPHON

PMDACONNECT(3)            Library Functions Manual            PMDACONNECT(3)

NAME         top

       pmdaConnect - establish a connection between a daemon PMDA and PMCD

C SYNOPSIS         top

       #include <pcp/pmapi.h>
       #include <pcp/pmda.h>

       void pmdaConnect(pmdaInterface *dispatch);

       cc ... -lpcp_pmda -lpcp

DESCRIPTION         top

       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         top

       pmdaConnect will log the type of connection made to pmcd(1) if the
       PMAPI(3) debugging option libpmda has been set in the global
       debugging 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.

CAVEAT         top

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

SEE ALSO         top

       pmcd(1), pipe(2), socket(2), PMAPI(3), PMDA(3), pmdaDaemon(3),
       pmdaGetOpt(3), pmdaGetOptions(3) and pmdaInit(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@groups.io.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2018-04-30.  (At that time, the date of the most recent commit that
       was found in the repository was 2018-04-30.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Performance Co-Pilot                 PCP                      PMDACONNECT(3)

Pages that refer to this page: pmda(3)