NAME

       __pmAddIPC,  __pmLookupIPC, __pmFdLookupIPC, __pmOverrideLastFd, __pmPrintIPC, __pmResetIPC - IPC version
       infrastructure support

C SYNOPSIS

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

       int __pmAddIPC(int fd, __pmIPC ipc);
       int __pmLookupIPC(__pmIPC **ipcp);
       int __pmFdLookupIPC(int fd, __pmIPC **ipcp);
       void __pmOverrideLastFd(int fd);
       void __pmPrintIPC(void);
       void __pmResetIPC(int fd);

       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

       IPC  channels  throughout  the  distributed  PCP  framework  are  affected by the PCP 2.0 (and later) PDU
       changes.  These functions are the interface to the libpcp IPC connection management  global  data.   This
       data  consists  of  a  hash  table of __pmIPC structures (indexed by file descriptor) and a cached, most-
       recently-used file descriptor.

       Newly created IPC channels must be registered with the hash table using __pmAddIPC,  such  that  the  PDU
       sending  and decoding routines can determine whether they need to perform any PDU version translations or
       not, for backward compatibility with previous the PCP 1.x IPC protocol.

       __pmLookupIPC and __pmFdLookupIPC both provide handles to the __pmIPC structure associated with the given
       file descriptor, as previously established by a call to __pmAddIPC.  The difference between  the  two  is
       that  one  allows  an  explicit file descriptor lookup, and the other uses the cached, most-recently-used
       file descriptor.  So __pmLookupIPC actually calls __pmFdLookupIPC using this cached  file  descriptor  as
       the  argument.   The  justification  for  having  both  is  that in some places it is not possible to use
       __pmFdLookupIPC (which is preferred), since at that particular level of the PMAPI a  file  descriptor  is
       not available (see the __pmDecodeError code for an example).

       The  __pmOverrideLastFd  is  an escape mechanism for use in those situations where the last PDU fetch did
       not go through the usual channels (ie. __pmGetPDU), so as to ensure that the cached  file  descriptor  is
       the  correct file descriptor for the PDU which is currently being processed.  This will typically be used
       for archive PDU processing or where version information is not available for a given file descriptor (eg.
       immediately prior to a PDU version exchange).

       __pmPrintIPC is a useful debugging routine for displaying a table mapping all currently  registered  file
       descriptors  to  their  associated  PDU version numbers.  Unused entries in this table should display the
       value zero in the version column.

       __pmResetIPC resets the version information associated with the  given  file  descriptor  to  some  known
       (invalid)  number.   Subsequent  lookups  on this file descriptor will return an UNKNOWN_VERSION embedded
       within the __pmIPC structure.

DIAGNOSTICS

       A negative return value from __pmLookupIPC indicates that the requested file descriptor is not registered
       in the hash table.  This typically indicates closure of an IPC channel, so PM_ERR_IPC is returned if this
       is the case.

SEE ALSO

       PMAPI(3)

Performance Co-Pilot                                   PCP                                        PMLOOKUPIPC(3)