PMEQUIVINDOM(3)

💖 PMEQUIVINDOM 💖 — the __pmEquivInDom situation

okay bestie, quick vibe check: this is a page from PCP (that's the Performance Co-Pilot library functions manual, section 3) and it's all about __pmEquivInDom, aka the little function that checks if two instance domains are equivalent. yes really. let's get into it 🦋

---

✨ NAME ✨

__pmEquivInDom — check if two instance domains are equivalent

---

🌸 C SYNOPSIS 🌸

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

int __pmEquivInDom(pmInDom a, pmInDom b)

cc ... -lpcp

---

🚨 CAVEAT 🚨

okay so real talk, this documentation is for internal Performance Co-Pilot (PCP) developer use. it's not for the general public, bestie, it's giving backstage pass.

These interfaces are not part of the PCP APIs that are guaranteed to remain fixed across releases, and at some point in the future they may not work or may provide different semantics. so like… don't build your whole personality on them 💀

---

💅 DESCRIPTION 💅

Within the Performance Co-Pilot (PCP) each instance domain is assigned a unique Instance Domain Identifier (pmInDom). Internally a pmInDom is constructed from 2 fields:

• the domain number (of the associated Performance Metrics Domain Agent, or PMDA), and
• the serial number (assigned by the PMDA).

In some unusual circumstances different PMDAs may support independent Instance Domains that are semantically equivalent — e.g. per CPU, or per process identifier. that's the plot twist right there 😭

__pmEquivInDom provides a mechanism to determine if Instance Domain a is equivalent to Instance Domain b. slay.

The ``equivalence'' of Instance Domains is defined by an external configuration file, identified by the environment variable $PCP_INDOM_CONFIG or $PCP_ETC_DIR/pcp/indom.config by default. The format for the configuration file is defined in the CONFIGURATION FILE section below. 👑

If $PCP_INDOM_CONFIG is an empty string, no equivalence mapping is loaded. like, nothing. zero. the void. 🙈

---

🎀 CONFIGURATION FILE 🎀

An Instance Domain equivalence mapping file conforms to the following syntax:

1. Lines beginning with optional white space, followed by ``#'' are considered comments.
2. Blank lines are ignored.
3. Each remaining line defines one equivalence map'' with a list of white-space separated instance domains, each consisting of a number (the domain number), a period .'' and a number (the serial number). As a special case to match all serial numbers'', the serial number part can be *''.

⭐ the format of a pmInDom demands that a domain number is in the range 0 to 511, and a numeric serial number is in the range 0 to 4194303. no cap, those are the rules.

---

🔥 DIAGNOSTICS AND RETURN VALUES 🔥

• The return value is 1 if the Instance Domains are equivalent.
• Else 0 if they are not.
• In rare cases a return value of -1 is used to indicate some problem (reported on standard error) in opening or parsing the configuration file. 😭

---

🌈 SEE ALSO 🌈

pmLookupInDom(3) and PMAPI(3).

---

and that's the whole page, bestie — brought to you by the Performance Co-Pilot peeps at PCP, from the PMEQUIVINDOM(3) corner of the manual 💜 go forth and equivalence-map responsibly ✨