PMGETCONTEXTHOSTNAME(3)

💖 PMGETCONTEXTHOSTNAME 💖

okay bestie, so this is from the Library Functions Manual of Performance Co-Pilot, and it's literally just "hey, what's the hostname for this PCP context?" energy. Three little functions, all vibing around the same question. Let's go 🦋

---

✨ NAME ✨

pmGetHostName, pmGetContextHostName, pmGetContextHostName_r — the trio that returns the hostname associated with a Performance Co-Pilot context. yes, all three, they're a package deal 💅

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmapi.h>

int pmGetHostName(int id, char *buf, int buflen);
const char *pmGetContextHostName(int id);
char *pmGetContextHostName_r(int id, char *buf, int buflen);

cc ... -lpcp

note the -lpcp at the end, you have to link it, don't forget, it's giving "I forgot the linker flag" and we don't want that 😭

---

🎀 DESCRIPTION 🎀

So you've got a valid PCP context identifier — one you made earlier with pmNewContext(3) or pmDupContext(3) — and you want to know which host it's about. That's the whole plot.

pmGetContextHostName takes that id and hands you back the hostname associated with it. Simple. Iconic.

pmGetContextHostName_r does the exact same thing, but it stores the result in a user-supplied buffer — that's your buf, of length buflen — and honestly buflen should have room for at least MAXHOSTNAMELEN bytes. like, at minimum. give the girl some space 🫶

pmGetHostName behaves similarly again, but it returns a status code</> to tell you success or failure instead of just yeeting the string at you.

---

okay now the part where it gets smart ✨

If the context id is associated with an archive source of data, then the hostname you get back is extracted from the archive label using pmGetArchiveLabel(3). cute, it read the label 📝

For live contexts, it will first try to grab the hostname from the PCP collector system using pmFetch(3) with the pmcd.hostname metric. and this is the good part: this is what lets client tools using this interface get an accurate host identifier even when there's port forwarding and tunnelled connections happening. no cap, tunnels would normally ruin the vibe but this handles it 🔥

Should that not succeed, there's a fallback method. For local contexts — and "local" here means any of DSO, ``localhost'', or a Unix domain socket connection — a hostname will be sought via gethostname(3). For other contexts, the hostname extracted from the initial context host specification will be used instead. fallback queen 💅

---

💀 RETURN VALUE 💀

If id is not a valid PCP context identifier, the returned hostname is a zero length string. empty. nothing. ghosted. 🙈

On failure, the return code of pmGetHostName is a negative PMAPI error code, which you can run through pmErrStr_r(3) for diagnostics about why it couldn't get the context hostname. that's your "what went wrong" translator, use it.

---

⚠️ NOTES ⚠️

pmGetContextHostName returns a pointer to a static buffer, so the returned value is only valid until the next call to pmGetContextHostName. and therefore it is not thread-safe. bestie. be careful.

Multi-threaded applications should use pmGetHostName or pmGetContextHostName_r instead. those are the safe ones. pick them, protect your peace 🧚

---

🌈 PCP ENVIRONMENT 🌈

Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the file /etc/pcp.conf contains the local values for these variables.

The $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

Values for these variables may be obtained programmatically using the pmGetConfig(3) function. iykyk 🌟

---

👑 SEE ALSO 👑

• PCPIntro(1)
• PMAPI(3)
• gethostname(3)
• pmDupContext(3)
• pmErrStr_r(3)
• pmFetch(3)
• pmGetArchiveLabel(3)
• pmNewContext(3)
• pcp.conf(5)
• pcp.env(5)

---

and that's the whole page, bestie, you ate it 💅✨

Performance Co-Pilot · PCP · PMGETCONTEXTHOSTNAME(3) — mwah, go get those hostnames 🎀🦋💖