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 **)
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.