PMGETCHILDREN(3)

💖 PMGETCHILDREN(3) — like, the manual page, but make it make sense 💖

okay bestie, sit down, we're learning pmGetChildren from the Library Functions Manual and honestly? it's giving family tree energy 🌳✨

---

✨ NAME ✨

pmGetChildren — return the descendent nodes of a PMNS node 🧬

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmapi.h>

int pmGetChildren(const char *name, char ***offspring);

cc ... -lpcp

---

🦋 DESCRIPTION 🦋

so. you hand it a fully qualified pathname to a node in the current Performance Metrics Name Space (aka the PMNS, iykyk), and that pathname is the name argument. then pmGetChildren hands you back — via offspring — a list of the relative names of all the immediate descendent nodes of name in the current PMNS. immediate, bestie. not the grandkids, not the whole bloodline. just the direct children 👑

and there's a lil special case for you: if name is an empty string (like, literally ""), then you get the immediate descendants of the root node of the PMNS. main character root node energy 💅

normally, pmGetChildren returns the number of descendent names discovered. otherwise it returns a value less than zero to signal an error. and if it returns zero? that means name is a valid metric name — as in, it's associated with a leaf node in the PMNS. so it's valid, it just has no children. it's an only child. a leaf. a solo act 🍃

now here's the part where you pay attention 🙈 the resulting list of pointers offspring, and the values (those relative names) that the pointers point at, were both allocated by pmGetChildren using a single call to malloc(3). so it's your job, yes yours, to free(offspring) and release that space once you don't need it anymore. don't ghost your memory, bestie, that's not cute 😭

⚠️ and when an error happens, or name is a leaf node (i.e. the result of pmGetChildren is less than one), then offspring is undefined. like, no space will have been allocated at all. so calling free(3) on it is, and I quote, "a singularly bad idea" 💀 not me warning you twice. just don't. fr fr.

---

🎀 DIAGNOSTICS 🎀

• PM_ERR_NOPMNS — could not access a PMNS for the operation. also, heads up: if the application hasn't a priori called pmLoadNameSpace(3) and wants to use the distributed PMNS, then the call to pmGetChildren has to be made inside a current context. context is everything, periodt ✨
• PM_ERR_NAME — the pathname name is not valid in the current PMNS. it's giving "who is she" 🙈
• PM_ERR_* — the rest of the diagnostics are for protocol failures when accessing the distributed PMNS. networking drama, not your fault, lowkey 🔥

---

🌈 PCP ENVIRONMENT 🌈

environment variables with the prefix PCP_ are what parameterize the file and directory names that PCP uses. 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). and you can get values for these variables programmatically using the pmGetConfig(3) function 🫶

---

⭐ SEE ALSO ⭐

PMAPI(3), pmGetChildrenStatus(3), pmGetConfig(3), pmLoadASCIINameSpace(3), pmLoadNameSpace(3), pmLookupName(3), pmNameID(3), pcp.conf(5), pcp.env(5) and PMNS(5).

---

and that's the whole page, bestie 💖 this was brought to you by Performance Co-Pilot, PCP, and the page PMGETCHILDREN(3) — go forth, walk the tree, and free your pointers 🧚✨