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.
