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.
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
__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
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
__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.
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.
This page is part of the PCP (Performance Co-Pilot) project.
Information about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
firstname.lastname@example.org. This page was obtained from the project's upstream
Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
2020-06-09. (At that time, the date of the most recent commit that
was found in the repository was 2020-06-09.) If you discover any
rendering problems in this HTML version of the page, or you believe
there is a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
Performance Co-Pilot PCP PMLOOKUPIPC(3)