NAME

       __pmConnectLogger - connect to a performance metrics logger control port

C SYNOPSIS

       #include "pmapi.h"
       #include "libpcp.h"

       int __pmConnectLogger(const char *hostname, int pid);

       cc ... -lpcp

CAVEAT

       This documentation is intended for internal Performance Co-Pilot (PCP) developer use.

       These  interfaces  are not part of the PCP APIs that are guaranteed to remain fixed across
       releases, and they may not work, or may provide different semantics at some point  in  the
       future.

DESCRIPTION

       Each  instance  of  the  Performance  Co-Pilot  (PCP)  archive  logger program pmlogger(1)
       supports a control port on which __pmControlLog(3) requests are  received,  and  responses
       sent.  Optionally, the pmlogger(1) instance may be designated the ``primary'' logger.

       __pmConnectLogger  may  be  used to establish a control port connection to the pmlogger(1)
       instance identified by process id pid on the host hostname.

       One special case is supported; for the  reserved  pid  value  of  PM_LOG_CONTROL_PORT  the
       requested  connection  is  to  the  control  port for the ``primary'' logger, whatever its
       process id might be.

       On success, __pmConnectLogger returns a non-negative integer, that is  a  file  descriptor
       that  may  be  used  in  subsequent  communication with the pmlogger(1) instance, e.g. for
       __pmControlLog(3).

       As  the  control  port   to   pmlogger(1)   is   not   mulitplexed,   applications   using
       __pmConnectLogger  should  use close(2) to terminate the connection to pmlogger(1) as soon
       as they have finished communicating.

       If the application connects, and the pmlogger(1) instance  subsequently  terminates,  e.g.
       because  the  associated  pmcd(1)  instance  is  terminated,  the application will have to
       explicitly re-establish  connection  to  a  re-started  pmlogger(1)  instance  by  calling
       __pmConnectLogger again.

DIAGNOSTICS

       PM_ERR_PERMISSION
              no permission to connect to the specified pmlogger(1) instance

       -ECONNREFUSED
              the designated pmlogger(1) instance does not exist

       -EEADDRINUSE
              the requested control port is already in use

SEE ALSO

       pmcd(1), pmlc(1), pmlogger(1), PMAPI(3) and __pmControlLog(3).