PMC_CAPABILITIES(3)

💅 PMC_CAPABILITIES(3) — your little info-gathering era

okay bestie so this is a libpmc page from the Library Functions Manual — that's the Performance Counters Library, aka libpmc (link it with -lpmc). these functions are all about asking the hardware questions. no cap, they're the "tell me everything" friend of the PMC world. 👑

---

✨ NAME ✨

pmc_capabilities, pmc_cpuinfo, pmc_ncpu, pmc_npmc, pmc_pmcinfo, pmc_width — retrieve information about performance monitoring counters 🎀

📚 LIBRARY 📚

Performance Counters Library (libpmc, -lpmc) 🫶

💻 SYNOPSIS 💻

#include <pmc.h>

int
pmc_capabilities(pmc_id_t pmc, uint32_t *caps);

int
pmc_cpuinfo(const struct pmc_cpuinfo **cpu_info);

int
pmc_ncpu(void);

int
pmc_npmc(int cpu);

int
pmc_pmcinfo(int cpu, struct pmc_pmcinfo **pmc_info);

int
pmc_width(pmc_id_t pmc, uint32_t *width);

🌸 DESCRIPTION 🌸

these functions retrieve information about performance monitoring hardware. it's giving "let me introduce you to your own CPU" energy, honestly. 💖

🦋 the individual girlies 🦋

pmc_capabilities() retrieves the hardware capabilities of a PMC. argument pmc is a PMC handle obtained by a prior call to pmc_allocate(). this function sets argument caps to a bit mask of capabilities supported by the PMC denoted by argument pmc. PMC capabilities are described in pmc(3). slay, capabilities. ✨

pmc_cpuinfo() retrieves information about the CPUs in the system. argument cpu_info will be set to point to an internal structure with information about the system's CPUs.

⚠️ bestie, listen — the caller should not free this pointer value. it's not yours. hands off. 🙈

this structure has the following fields:

• pm_cputype — specifies the CPU type.
• pm_ncpu — specifies the number of CPUs in the system.
• pm_npmc — specifies the number of PMC rows per CPU.
• pm_nclass — specifies the number of distinct classes of PMCs in the system.
• pm_classes — contains an array of struct pmc_classinfo descriptors describing the properties of each class of PMCs in the system.

pmc_ncpu() is a convenience function that returns the maximum CPU number in the system. here's the plot twist 😭 — on systems that support sparsely numbered CPUs, not all CPUs may be physically present. so applications need to be prepared to deal with nonexistent CPUs. ghost CPUs, literally. 👻

pmc_npmc() is a convenience function that returns the number of PMCs available in the CPU specified by argument cpu.

pmc_pmcinfo() returns information about the current state of the PMC hardware in the CPU specified by argument cpu. the location specified by argument pmc_info is set to point an array of struct pmc_info structures, each describing the state of one PMC in the CPU. these structures contain the following fields:

• pm_name — a human readable name for the PMC.
• pm_class — the PMC class for the PMC.
• pm_enabled — non-zero if the PMC is enabled.
• pm_rowdisp — the disposition of the PMC row for this PMC. row dispositions are documented in hwpmc(4).
• pm_ownerpid — if the hardware is in use, the process id of the owner of the PMC.
• pm_mode — the PMC mode as described in pmc(3).
• pm_event — if the hardware is in use, the PMC event being measured.
• pm_flags — if the hardware is in use, the flags associated with the PMC.
• pm_reloadcount — for sampling PMCs, the reload count associated with the PMC.

pmc_width() is used to retrieve the width in bits of the hardware counters associated with a PMC. argument pmc is a PMC handle obtained by a prior call to pmc_allocate(). the function sets the location pointed to by argument width to the width of the physical counters associated with PMC pmc. width = how thicc your counter is, basically. 📏

---

🔥 RETURN VALUES 🔥

functions pmc_ncpu() and pmc_npmc() returns a positive integer if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. 💀

functions pmc_capabilities(), pmc_cpuinfo(), pmc_pmcinfo() and pmc_width() return 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

🫶 friendly reminder: -1 is the villain era signal. always check errno after.

💀 ERRORS 💀

a call to function pmc_capabilities() may fail with the following errors:

• [EINVAL] — the argument to the function was invalid.

calls to functions pmc_cpuinfo(), pmc_ncpu() and pmc_npmc() may fail with the following errors:

• [ENXIO] — a prior call to pmc_init() to initialize the PMC library had failed.

a call to function pmc_pmcinfo() may fail with the following errors:

• [EINVAL] — the argument cpu was invalid.
• [ENXIO] — the argument cpu specified a disabled or absent CPU.

a call to function pmc_width() may fail with the following errors:

• [EINVAL] — the argument to the function was invalid.

---

👀 SEE ALSO 👀

pmc(3), pmc_allocate(3), pmc_get_driver_stats(3), pmc_name_of_capability(3), pmc_name_of_class(3), pmc_name_of_cputype(3), pmc_name_of_event(3), pmc_name_of_mode(3), hwpmc(4)

go read all of them, iykwim. it's giving study group. 📖✨

---

mwah 💋 this one's from Debian, dated September 22, 2008 — yeah she's an older icon but she still ate, and the whole page is filed under PMC_CAPABILITIES(3). periodt. 🎀