PMLOOKUPIPC(3)            Library Functions Manual            PMLOOKUPIPC(3)

NAME         top

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

C SYNOPSIS         top

       #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         top

       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.

SEE ALSO         top


DIAGNOSTICS         top

       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.

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨⟩ on
       2017-09-15.  If you discover any rendering problems in this HTML ver‐
       sion 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 man‐
       ual page), send a mail to

Performance Co-Pilot                 PCP                      PMLOOKUPIPC(3)