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.

SEE ALSO

       PMAPI(3)

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.