PMSETDEBUG(3)

PMSETDEBUG(3) 💖✨

okay bestie, pull up a chair, we're doing the Library Functions Manual edition of the PCP debug saga and honestly? it's giving main character energy. this page is about four little functions — pmSetDebug, pmDebug, pmGetDebug, pmClearDebug — and their whole job is manipulating PCP debugging control options. that's it. that's the vibe. 🎀

---

NAME 🌸

pmSetDebug, pmDebug, pmGetDebug, pmClearDebug — manipulate PCP debugging control options, no cap 💅

---

C SYNOPSIS 🦋

#include <pcp/pmapi.h>

int pmSetDebug(const char *spec);
int pmDebug(const char *spec);
char *pmGetDebug(void);
int pmClearDebug(const char *spec);

cc ... -lpcp

literally just include the header, link the lib, and you're in. periodt. ⭐

---

DESCRIPTION ✨

so within the libraries and applications of the Performance Co-Pilot (PCP) there's a whole extensive set of debugging options, right? and the whole point is you can enable or disable them at run-time. no recompile, no drama, we love that for us. 🔥

pmSetDebug, pmDebug and pmClearDebug all parse spec assuming it to be a comma separated list of PCP debug option names. that's the whole assignment, bestie.

wanna know what option names actually exist? you find those using the -l argument to pmdbg(1). go look, it's right there. 👑

and here's a lil special case for you: the name `all` is treated as a synonym for identifying all option names. so when you say all, you mean ALL. every single one. 💫

• pmSetDebug will set the corresponding options ✨
• pmClearDebug will clear the corresponding options 🧹

pmDebug is the tester girlie — it's used to test if options have been set, and it returns 1 if at least one of the options in spec has been set, else it returns 0. simple as that. 💅

---

the additive thing (iykyk) 🫶

consecutive calls to either pmSetDebug or pmClearDebug will be additive. like, they stack. they build. they don't wipe the slate unless you tell them to.

so for example, these two code fragments are equivalent in terms of the final state of the debug options:

sts = pmClearDebug("all");
sts = pmSetDebug("appl0");
sts = pmSetDebug("pdu,fetch");
sts = pmSetDebug("fetch,profile,context");
sts = pmClearDebug("appl0");

sts = pmClearDebug("all");
sts = pmSetDebug("pdu,fetch,profile,context");

same ending, different journey. both iconic. 🌈

---

the env var shortcut 🌸

for applications that use pmGetOptions(3) to process command line options and arguments, setting the environment variable $PCP_DEBUG gives you an alternative mechanism to set debug flags — as described in PCPIntro(1). so you can just vibe it in from the environment instead. 💜

---

pmGetDebug moment 💖

pmGetDebug returns the current set of enabled debug options as a comma separated list.

• if no options are set, the result is an empty string 🫥
• if every option is set, the result is `all` 👑

⚠️ heads up bestie: the result is allocated by malloc(3) and the caller is responsible for calling free(3) when the result is no longer needed. do not forget. do not leak. the memory is YOURS now. 😭

---

DIAGNOSTICS 💀

if successful, the routines pmSetDebug, pmDebug and pmClearDebug return 0 or 1. otherwise the return is PM_ERR_CONV to indicate an error parsing spec. so if you see that, your spec was messy, not you. 🙈

for pmGetDebug, a return value of NULL indicates a malloc(3) failure. that's the only reason. 😭

---

SEE ALSO 🎀

PCPIntro(1), pmdbg(1), free(3) and malloc(3).

---

okay that's the whole page, you ate, you understood it, you're gonna go set some debug flags responsibly. mwah. 💅✨

with love from the Performance Co-Pilot girlies — this was PCP, page PMSETDEBUG(3), and yeah bestie that's a wrap. 🦋💖🌸