PMCONNECTLOGGER(3)

💖 PMCONNECTLOGGER 💖

okay bestie, welcome to the Library Functions Manual page for __pmConnectLogger — yes it's a C function, yes it's in the libpcp zone, and yes we're gonna get through it together. grab a strawberry 🍓

---

✨ NAME ✨

__pmConnectLogger — connect to a performance metrics logger control port 🎀

---

🌸 C SYNOPSIS 🌸

like literally just this:

#include "pmapi.h"
#include "libpcp.h"

int __pmConnectLogger(const char *hostname, int pid);

cc ... -lpcp

no cap, that's the whole signature 💅

---

⚠️ CAVEAT ⚠️

bestie. listen. this documentation is intended for internal Performance Co-Pilot (PCP) developer use. it's giving backstage-pass energy, not public-API energy. 🙈

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. so like… don't build your whole personality on them, fr fr. 😭

---

🦋 DESCRIPTION 🦋

so every single instance of the Performance Co-Pilot (PCP) archive creation program pmlogger(1) supports a control port, right? and on that control port, __pmControlLog(3) requests come in and responses go out. it's giving customer service desk. 👑

and optionally, a pmlogger(1) instance may be designated the ``primary'' logger. main character energy, honestly. ⭐

__pmConnectLogger is the function you use to establish a control port connection to the pmlogger(1) instance identified by process id pid on the host hostname. that's the whole vibe check. ✨

and there's one special case that's supported, lowkey iconic: for the reserved pid value of PM_LOG_PRIMARY_PORT, the requested connection is to the control port for the ``primary'' logger — whatever its process id might be. you don't have to know who it is. it just knows. 💅

on success, __pmConnectLogger returns a non-negative integer, which is a file descriptor that may be used in subsequent communication with the pmlogger(1) instance, e.g. for __pmControlLog(3). slay. 🎀

⚠️ important!! as the control port to pmlogger(1) is not multiplexed, applications using __pmConnectLogger should use close(2) to terminate the connection to pmlogger(1) as soon as they have finished communicating. like, hang up the phone when you're done talking, bestie. 📞

and if the application connects, and the pmlogger(1) instance subsequently terminates — e.g. because the associated pmcd(1) instance is terminated — the application will have to explicitly re-establish connection to a restarted pmlogger(1) instance by calling __pmConnectLogger again. no auto-reconnect, no safety net, it's giving you-have-to-text-first. 😭

---

💀 DIAGNOSTICS 💀

here's what it yells at you when things go sideways:

• PM_ERR_PERMISSION — no permission to connect to the specified pmlogger(1) instance. it's giving bouncer-at-the-club. 🚫
• -ECONNREFUSED — the designated pmlogger(1) instance does not exist. ghosted, literally. 👻
• -EADDRINUSE — the requested control port is already in use. somebody's already in that seat bestie, sit somewhere else. 🙈

---

👀 SEE ALSO 👀

pmcd(1), pmlc(1), pmlogger(1), PMAPI(3) and __pmControlLog(3).

go read those too, iykyk 💜

---

and that's the whole page!! brought to you by the good people of Performance Co-Pilot / PCP — the collection itself, the whole source-and-version moment, wrapped up with a lil bow. 🎀 no date stamp to shout about here, just vibes and a manpage that lives in the PCP house. mwah, bye bestie 💖✨