PMLOADASCIINAMESPACE(3)

💖 PMLOADASCIINAMESPACE(3) 💖

okay so bestie, welcome to pmLoadASCIINameSpace — the little library function that establishes a local PMNS for an application. she's from the Library Functions Manual section, and she is, lowkey, the moment. 🎀

---

✨ NAME ✨

pmLoadASCIINameSpace — establish a local PMNS for an application 🦋

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmapi.h>

int pmLoadASCIINameSpace(const char *filename, int dupok);

cc ... -lpcp

---

💅 DESCRIPTION 💅

so here's the vibe: if your app wants to force using a local Performance Metrics Name Space (PMNS) instead of a distributed PMNS, then it has to load the PMNS using pmLoadASCIINameSpace or pmLoadNameSpace(3). and if your app wants to use a distributed PMNS? then it should NOT make a call to load the PMNS explicitly. don't do it. hands off the wheel. 🙈

and like, most applications using a Performance Metrics Application Programming Interface (PMAPI) context — of any type, so PM_CONTEXT_HOST or PM_CONTEXT_ARCHIVE or PM_CONTEXT_LOCAL — should not need to call pmLoadASCIINameSpace at all. she's not for everybody, she's for a very specific girlie. 👑

the filename argument designates the PMNS of interest. and for applications that don't require a tailored PMNS, there's a special value PM_NS_DEFAULT you can use for filename, which forces the default local PMNS to be loaded. cute, easy, slay. ✨

so where does that default local PMNS live? it's found in the file $PCP_VAR_DIR/pmns/root — unless the environment variable PMNS_DEFAULT is set, in which case the value is assumed to be the pathname to the file containing the default local PMNS. noted. 📝

now, pmLoadASCIINameSpace is a variant of pmLoadNameSpace(3), and here's where she differs. first: the dupok argument controls the handling of multiple names in the PMNS that may be associated with a single Performance Metric Identifier (PMID). a value of 0 disallows duplicates; any other value allows duplicates — and that permissive behaviour is the default behaviour of pmLoadNameSpace(3) as of Version 3.10.3 of PCP. no cap. 🔥

the other difference: when pmLoadASCIINameSpace is used and filename is not PM_NS_DEFAULT, the PMNS file will always be preprocessed with pmcpp(1) as described in PMNS(5). this is the glow-up that lets a PMNS file containing C-style comments, preprocessor directives or macros be processed correctly before the PMNS is parsed. iconic behaviour honestly. 💅

pmLoadASCIINameSpace returns zero on success. 🫶

---

😭 DIAGNOSTICS 😭

Syntax and other errors in the parsing of the PMNS are reported on stderr, with a message of the form:

Error Parsing ASCII PMNS: ...

• PM_ERR_DUPPMNS — it is an error to try to load more than one PMNS, or to call either pmLoadASCIINameSpace and/or pmLoadNameSpace(3) more than once. like, one and done, bestie. 💀
• PM_ERR_PMNS — syntax error in an ASCII format PMNS.

---

🎀 FILES 🎀

• $PCP_VAR_DIR/pmns/root — the default local PMNS, when the environment variable PMNS_DEFAULT is unset

---

🌈 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. iykyk. 💜

---

👑 SEE ALSO 👑

PMAPI(3), pmGetConfig(3), pmLoadNameSpace(3), pmTrimNameSpace(3), pcp.conf(5), pcp.env(5) and PMNS(5).

---

and that's the whole page, babe — brought to you by the fine folks at Performance Co-Pilot, aka PCP (the version string says PCP, the manual page says PMLOADASCIINAMESPACE(3)), mwah 💋 go forth and load your name space responsibly ✨🦋💖