PMGETINDOMARCHIVE(3)

✨ pmGetInDomArchive(3) — the vibe ✨

okay so bestie, this is a page from the Library Functions Manual for pmGetInDomArchive, and it's genuinely one of the good ones. grab a strawberry 🍓 and let's get into it.

---

💖 NAME 💖

pmGetInDomArchive — get instance identifiers for a performance metrics instance domain. that's the whole gig. it's giving "i fetch the receipts" energy 🧾✨

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmapi.h>

int pmGetInDomArchive(pmInDom indom, int **instlist, char ***namelist);

cc ... -lpcp

yes you need that -lpcp at link time, don't skip it, it's not optional and the linker will simply end you 💀

---

🎀 DESCRIPTION 🎀

so here's the tea ☕. as long as your current Performance Metrics Application Programming Interface (PMAPI) context is associated with a set of archives, pmGetInDomArchive will scan the union of all the instance domain metadata for the instance domain indom, and then hand you back:

• via instlist — the internal instance identifiers for all instances 🔢
• via namelist — the full external identifiers for all instances 🏷️

it's a specialized version of the more general PMAPI routine pmGetInDom, iykyk. like, pmGetInDom is the main character, and this one is the spinoff that only does archives.

the number of instances found comes back as the function value (and if it's less than zero, that's an error, no cap 😭).

where does indom come from? typically you extract the value for the instance domain indom from a pmDesc structure, right after you've called pmLookupDesc(3) for a particular performance metric. so the pipeline is: look up the metric desc → steal the indom out of it → come back here. 💅

🫶 about the memory (this part matters) 🫶

the resulting lists of instance identifiers (instlist and namelist), and the names that the elements of namelist point to, will have been allocated by pmGetInDomArchive with two calls to malloc(3). so it's on you, the caller, to free(instlist) and free(namelist) to release that space when you no longer need it. please. for the love of everything. 🌈

⚠️ when the result of pmGetInDomArchive is less than one, both instlist and namelist are undefined — no space will have been allocated, and so calling free(3) is a singularly bad idea. like, genuinely cursed behaviour. do not. 🙈

---

👑 DIAGNOSTICS 👑

• PM_ERR_NOTARCHIVE — the current PMAPI context is not associated with a set of archives. wrong context, bestie, this function only does archives.
• PM_ERR_INDOM_LOG — indom is not a defined instance domain identifier for the set of archives. that indom? not in this archive's record. 💀

---

🌟 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. it's giving "configception" but make it functional ✨

---

🦋 SEE ALSO 🦋

PMAPI(3), pmGetConfig(3), pmGetInDom(3), pmLookupDesc(3), pmLookupInDomArchive(3), pmNameInDomArchive(3), pcp.conf(5) and pcp.env(5).

---

and that's the whole page, periodt. this one came out of Performance Co-Pilot (PCP), filed under PMGETINDOMARCHIVE(3) — go free your mallocs and stan a well-behaved instance domain, you absolute icon 💜🎀