PMGETCONFIG(3)

💖 PMGETCONFIG(3) — bestie edition 💖

okay so real talk, this is a page from the Library Functions Manual of Performance Co-Pilot (PCP), and it's all about three little functions that go dig up your config values for you. no cap, they're iconic. let's get into it 🫶

---

✨ NAME ✨

pmGetConfig, pmGetOptionalConfig, pmGetAPIConfig — they hand you back values for Performance Co-Pilot configuration variables. that's the whole job bestie 💅

---

🌸 C SYNOPSIS 🌸

include the header like so:

#include <pcp/pmapi.h>

and here are your three girls, exact signatures, don't @ me:

char *pmGetConfig(const char *variable);
char *pmGetOptionalConfig(const char *variable);
char *pmGetAPIConfig(const char *feature);

and when you compile, you link it up like this:

cc ... -lpcp

---

🦋 DESCRIPTION 🦋

okay so pmGetConfig and pmGetOptionalConfig both go hunting for variable. first stop: the environment. and if it's not there? they check the Performance Co-Pilot (PCP) configuration file. then they hand you back the string result, slay. 💅

and here's the little extra: if variable was not already in the environment, it gets added — with a call to setenv(3) — before the function returns. so it's like, once you ask, it's just there now. main character energy fr.

now, pmGetOptionalConfig is the chill one. it's totally fine with failure — whether that's variable not being set at all, or the config file straight-up being missing. she's unbothered. 💅

pmGetConfig though? she is NOT chill. a missing configuration file is treated as a critical PCP installation failure. that's serious. go read the RETURN VALUE section below for the full tea.

the default location of the PCP configuration file is /etc/pcp.conf 📁 but you can change it by setting PCP_CONF in the environment to a new location — all the details live in pcp.conf(5).

then there's pmGetAPIConfig, which is the one who reports on features of the PCP library. she's your girl for querying support for multi-threading, security extensions, and other features. vibe check on the library itself, basically.

and pssst — the pmconfig(1) utility gives you command line access to both of these interfaces 👑 and it also has a mechanism for listing all available variables and features that are valid arguments to these routines. so if you're ever like "wait what can I even pass in here??" — that's your answer, iykyk.

---

💀 RETURN VALUE 💀

let's get into the consequences, bestie:

• if variable is not found in either the environment or the PCP configuration file, or if the configuration file is inaccessible → pmGetOptionalConfig returns NULL. she's fine, she's just empty handed. 🙈
• if variable is found in neither the environment nor the PCP configuration file → pmGetConfig returns an empty string.
• but if the PCP configuration file is not found → a fatal error message is printed and the process will exit(2). 😭

okay yes that sounds drastic. and it IS. but the page is very clear that it's the only course of action available, because the PCP configuration/installation is deemed fatally flawed. nothing else to do. periodt.

• pmGetAPIConfig returns NULL on failure to look up the requested feature. it does not modify the environment, and it returns a pointer to a static read-only string.

and for all three of these routines — the value you get back is either a static pointer or a pointer into the environment. so changing it is a bad idea. do not touch. hands off. 💅

---

🌈 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? everything connects. 🫶

---

👑 SEE ALSO 👑

go read these too, bestie, they're all part of the lore:

PCPIntro(1), pmconfig(1), pmGetVersion(3), exit(2), PMAPI(3), getenv(3), setenv(3), pcp.conf(5), pcp.env(5) and environ(7).

---

and that's the whole page!! mwah 💋

this lil masterpiece came to you courtesy of Performance Co-Pilot — that's the source, and PCP is the version, so jot that down — and it's the PMGETCONFIG(3) page, which we already knew because it's literally the title. slay, stan, and remember to link with -lpcp ✨💖