PMDACONNECT(3)

✨ NAME ✨

pmdaConnect — the lil function that gets your daemon PMDA and PMCD talking to each other 💖 like setting up the group chat between your agent and the main character (pmcd).

---

🫶 C SYNOPSIS 🫶

#include <pcp/pmapi.h>
#include <pcp/pmda.h>

void pmdaConnect(pmdaInterface *dispatch);

cc ... -lpcp_pmda -lpcp

---

🌸 DESCRIPTION 🌸

okay so bestie, pmdaConnect sets up the whole IPC channel between a PMDA(3) and the pmcd(1) process on the local host. literally it's the moment they finally start texting. 💌

The type of connection you get depends entirely on the e_io field of the pmdaExt structure, and she has OPINIONS:

• pmdaPipe — uses stdin/stdout to communicate; it just assumes this is a pipe that pmcd created before the PMDA(3) was launched. no cap. 🚰
• pmdaInet — assumes pmcd(1) will establish a connection to an IPv4 internet domain socket set up by the PMDA(3). The name or number of the port has to be specified in the e_sockname or e_port fields of the pmdaExt structure, respectively. 👑
• pmdaIPv6 — assumes pmcd(1) will establish a connection to an IPv6 internet domain socket set up by the PMDA(3). And again: the name or number of the port must be specified in the e_sockname or e_port fields of the pmdaExt structure, respectively. slay, but v6 this time 🦋
• pmdaUnix — assumes pmcd(1) will establish a connection to a unix domain socket set up by the PMDA(3). Here the port number must be specified in the e_port field of the pmdaExt structure. 🐚
• pmdaUnknown — this is the initial value of e_io, and it defaults to using stdin/stdout. the factory setting, the default fit, the vibe before you choose 🎀

The relevant pmdaExt fields get initialized by pmdaDaemon(3) and set by pmdaGetOpt(3) or pmdaGetOptions(3), so honestly most PMDAs should not need to access or modify them at all. let the helpers do their thing 💅

Traditionally most PMDAs have called pmdaConnect after calls to pmdaDaemon(3), pmdaGetOptions(3) (or pmdaGetOpt(3)) and pmdaInit(3). cute, classic, works.

BUT — and this is the important part, don't scroll — if the PMDA requires significant processing at startup to identify the available metrics and/or instance domains before pmdaInit(3) can be called, then it risks timing out during the handshake protocol. And that handshake protocol starts as soon as pmcd(1) launches the PMDA and does not conclude until pmdaConnect is called. 😭 so you're just standing there, not texting back, and pmcd is like ???

In this case, it is advisable to move the pmdaConnect call, so that it comes after the call to pmdaGetOptions(3) (or pmdaGetOpt(3)) and before the call to pmdaInit(3). reorder the timeline, main character move, periodt. 🔥

---

⚠️ CAVEAT ⚠️

The PMDA must be using PMDA_INTERFACE_2 or later, as specified in the call to pmdaDaemon(3). no downgrades, no old interfaces, we don't do that here 💀

---

🔍 DIAGNOSTICS 🔍

pmdaConnect will log the type of connection made to pmcd(1) if the PMAPI(3) debugging option libpmda has been set in the global debugging specification, as described in pmSetDebug(3). so you can literally see the receipts 🧾✨

If an error occurs that is unrecoverable, dispatch->status is set to a value less than 0, otherwise it is zero or positive. less than zero = bad vibes, go fix it 🙈

---

💜 SEE ALSO 💜

pmcd(1), pipe(2), socket(2), PMAPI(3), PMDA(3), pmdaDaemon(3), pmdaGetOpt(3), pmdaGetOptions(3) and pmdaInit(3).

go read those too bestie, they're all in the same friend group 🫶

---

that's the whole page, you ate it 💅 this was brought to you by Performance Co-Pilot / PCP, page PMDACONNECT(3) — k byeeee 🌈💖