PMLOOKUPIPC(3)

💖 PMLOOKUPIPC — bestie's guide to the IPC version infrastructure 💖

okay so this is PMLOOKUPIPC(3) from the Library Functions Manual, and it's a whole ✨ internal PCP ✨ situation, so grab a boba and let's go 🧋

---

🌸 NAME 🌸

__pmAddIPC, __pmLookupIPC, __pmFdLookupIPC, __pmOverrideLastFd, __pmPrintIPC, __pmResetIPC — IPC version infrastructure support 🎀

---

✨ C SYNOPSIS ✨

#include "pmapi.h"
#include "libpcp.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);

and to actually link the thing, bestie:

cc ... -lpcp

---

🫶 CAVEAT 🫶

girl. listen. This documentation is for internal Performance Co-Pilot (PCP) developer use only. Like, it's the group chat you're not supposed to screenshot 📸

These interfaces are not part of the PCP APIs that are guaranteed to remain fixed across releases. They may not work, or may provide different semantics at some point in the future. So don't build your whole personality on them, okay? 😭

---

🦋 DESCRIPTION 🦋

okay so, IPC channels all 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 💅

and what even is that data? It consists of:

• a hash table of __pmIPC structures (indexed by file descriptor) 🔑
• a cached, most-recently-used file descriptor ⭐

Newly created IPC channels must be registered with the hash table using __pmAddIPC, so that the PDU sending and decoding routines can figure out whether they need to perform any PDU version translations or not, for backward compatibility with previous the PCP 1.x IPC protocol. it's giving legacy support, and honestly? iconic 👑

__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). no fd? no problem, __pmLookupIPC has you covered 🫶

__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). it's the "trust me bestie, this is the right fd" button 🚨

__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. zero = nobody home, empty, no thoughts head empty 💀

__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. so like, mystery mode activated 🙈

---

🌈 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. not the vibe check you wanted to pass, fr fr 😭

---

👑 SEE ALSO 👑

PMAPI(3)

---

and that's the whole page, bestie 💜 — this gem is from Performance Co-Pilot, PCP, and the page itself is dated PMLOOKUPIPC(3). mwah, slay, periodt 💅✨🎀