PMDACHILDREN(3)

💖 PMDACHILDREN(3) 💖

okay bestie, gather round, because this one is a library functions manual page from the PCP girlies and it's lowkey iconic ✨

---

🌸 NAME 🌸

pmdaChildren — the way that you translate a PMID into a whole set of dynamic performance metric names 🦋

---

🎀 C SYNOPSIS 🎀

#include <pcp/pmapi.h>
#include <pcp/pmda.h>

int pmdaChildren(char *name, int traverse, char ***offspring,
                 int **status, pmdaExt *pmda);

cc ... -lpcp_pmda -lpcp

---

✨ DESCRIPTION ✨

so basically, as part of the Performance Metrics Domain Agent (PMDA) API (go peek at PMDA(3) if you haven't, bestie), pmdaChildren is the generic callback for returning dynamic metric names (and their status, obviously) that are descendants of name. periodt 💅

now here's the tea: implementing dynamic performance metrics needs specific PMDA support, and the whole facility is an optional component of a PMDA (most PMDAs simply do not support dynamic performance metrics, sad but true 😭). so pmdaChildren is a skeleton implementation that just returns PM_ERR_NAME. it's giving placeholder energy, ngl.

a PMDA that does support dynamic performance metrics will hand you a private callback that replaces pmdaChildren — you do that by assignment to version.four.children of the pmdaInterface structure 👑 — and that callback takes the initial metric name and returns names via offspring[], plus the leaf or non-leaf status of each one via status[].

okay so the traverse thing, let's break it down:

• if traverse is 0, the behaviour is akin to pmGetChildren(3) and offspring[] contains the relative name component for the immediate descendants of name. just the immediate ones, bestie, no going deeper 🫶
• if traverse is 1, the behaviour is akin to pmTraversePMNS(3) and offspring[] contains the absolute names of all dynamic metrics that are descendants of name. the whole family tree, no cap 🌈

now, memory management, because we love a responsible queen:

the resulting list of pointers offspring and the string values (the names) that the pointers reference will have been allocated by pmdaChildren with a single call to malloc(3), and the caller of pmdaChildren will call free(offspring) to release the space when it is no longer required. same holds true for the status array — namely, the caller of pmdaChildren will call free(status) to release the space when it is no longer required. one malloc, two frees, we stay organized 💖

---

⚠️ CAVEAT ⚠️

the PMDA must be using PMDA_INTERFACE_4 or later, as specified in the call to pmdaDSO(3) or pmdaDaemon(3). not optional, not negotiable, fr fr 💀

---

🔥 DIAGNOSTICS 🔥

pmdaChildren returns PM_ERR_NAME if the name is not recognized or cannot be translated, otherwise it returns the number of descendent metric names found. so like, either a sad little error or a whole count of your metric babies 🌸

---

🦋 SEE ALSO 🦋

PMAPI(3), PMDA(3), pmdaDaemon(3), pmdaDSO(3), pmdaMain(3), pmGetChildren(3) and pmTraversePMNS(3). go read them, iykyk 💜

---

Performance Co-Pilot · PCP · PMDACHILDREN(3)

and that's the whole page, bestie 🎀 mwah, go forth and free your arrays, you absolute main character 💅✨