PMGETCHILDRENSTATUS(3)

💖 PMGETCHILDRENSTATUS 💖

okay bestie, so this one lives in the Library Functions Manual section and it's literally called pmGetChildrenStatus 🫶 — say it with me, it's a whole mouthful, but the vibe? immaculate.

---

✨ NAME ✨

pmGetChildrenStatus — returns the descendent nodes of a PMNS node, plus each one's status. yes, both. she's an overachiever 💅

---

✨ C SYNOPSIS ✨

#include <pcp/pmapi.h>

int pmGetChildrenStatus(const char *name, char ***offspring,
                        int **status);

cc ... -lpcp

---

✨ DESCRIPTION ✨

so you hand her a fully qualified pathname to a node in the current Performance Metrics Name Space (PMNS), and that's your name. then pmGetChildrenStatus gives you back — via offspring — a list of the relative names of all the immediate descendent nodes of name in the current PMNS. all of them. no cap. 🌸

and here's the lil special case, the plot twist: if name is an empty string (like, literally ""), she returns the immediate descendants of the root node in the PMNS. main character behaviour honestly 👑

if status isn't NULL, then she'll also hand you the status of each child through status. and that status is either a leaf node (value PMNS_LEAF_STATUS) or a non-leaf node (value PMNS_NONLEAF_STATUS). so you always know what you're dealing with 🦋

normally, pmGetChildrenStatus returns the number of descendent names she found. otherwise she returns a value less than zero for an error, and the value zero means name is a valid metric name — like, it's associated with a leaf node in the PMNS. zero is a real answer here, not a nothing-answer, okay? 💀

now listen, this part matters. the resulting list of pointers offspring and the values (the relative names) that those pointers reference? all allocated by pmGetChildrenStatus in a single call to malloc(3). so it's your job as the caller to free(offspring) and release that space once you don't need it anymore. same deal for the status array. don't leave her hanging 🙈

and when an error happens, or when name is a leaf node (i.e. the result of pmGetChildrenStatus is less than one), then both offspring and status are undefined. no space will have been allocated, and so calling free(3) is a singularly bad idea. like, genuinely cursed. do not. 💀

---

✨ DIAGNOSTICS ✨

• PM_ERR_NOPMNS — failed to access a PMNS for operation. quick note bestie: if the application hasn't a priori called pmLoadNameSpace(3) and wants to use the distributed PMNS, then a call to pmGetChildrenStatus must be made inside a current context. yes, must. 🔥
• PM_ERR_NAME — the pathname name is not valid in the current PMNS. she doesn't know her. 😭
• PM_ERR_* — other diagnostics are for protocol failures when accessing the distributed PMNS.

---

✨ 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). and values for these variables may be obtained programmatically using the pmGetConfig(3) function. cute, right? 🎀

---

✨ SEE ALSO ✨

PMAPI(3), pmGetChildren(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 one's brought to you by Performance Co-Pilot (that's PCP, iykyk) — and if you ever need to find her again in the manual, she's filed right there under PMGETCHILDRENSTATUS(3). slay, go free your pointers. ✨🫶