NAME

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

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/impl.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

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.

Performance Co-Pilot                                   PCP                                        PMLOOKUPIPC(3)