PMC_READ(3)

💅 PMC_READ(3) — bestie's guide to the library functions manual

okay so this is pmc_read(3), straight out of the Library Functions Manual, and no cap it's the whole trio: pmc_read, pmc_rw, and pmc_write. three icons, one page. let's get into it 🎀

---

✨ NAME ✨

pmc_read, pmc_rw, pmc_write — read and write hardware performance counters

like literally, that's the whole gig. reading counters, writing counters, and one very special atomic combo move 💫

---

📚 LIBRARY 📚

Performance Counters Library (libpmc, -lpmc)

yes bestie you gotta link the library, don't forget the -lpmc or the linker will be like "who?" 😭

---

🌸 SYNOPSIS 🌸

#include <pmc.h>

int
pmc_read(pmc_id_t pmc, pmc_value_t *value);

int
pmc_rw(pmc_id_t pmc, pmc_value_t newvalue, pmc_value_t *oldvaluep);

int
pmc_write(pmc_id_t pmc, pmc_value_t value);

three little functions, all return int, all living their best lives in <pmc.h> 🫶

---

🦋 DESCRIPTION 🦋

so these functions read and write the current value of a PMC. that's the vibe check. 📖✍️

• function pmc_read() will read the current value of the PMC specified by argument pmc and write it to the location specified by argument value. it's giving "just peek at it, don't touch" 👀
• function pmc_write() will set the current value of the PMC specified by argument pmc to the value specified by argument value. full send, we're overwriting ✏️
• function pmc_rw() combines a read and a write into a single atomic operation. iconic behavior actually — one move, no in-between, nobody can sneak in the middle 💅✨

⚠️ important lil note: for write operations the PMC should be a quiescent state. like, be QUIET please, the counter is busy 🫥

---

💀 RETURN VALUES 💀

upon successful completion, the value 0 is returned — slay, we love a zero 🎉

otherwise the value -1 is returned and the global variable errno is set to indicate the error. so if you see -1, go check errno, it's literally telling you what went wrong 🙈

---

🔥 ERRORS 🔥

a call to these functions may fail with the following errors:

• [EBUSY] — a write operation specified a currently running PMC. bestie it's BUSY, stop trying to write to it while it's working 😤
• [EINVAL] — argument pmc specified a PMC not in a readable state. can't read it, it's not in its readable era rn 💔
• [EINVAL] — the PMC specified by argument pmc was not owned by the current process. not yours, not your counter, no cap 🚫👑

(note that EINVAL shows up twice with two different meanings — she's versatile, she contains multitudes 🧚)

---

👀 SEE ALSO 👀

pmc(3), hwpmc(4)

go read those too, iykyk 📚💜

---

and that's the whole page!! this beauty came from Debian, dated November 25, 2007 — a vintage, an absolute classic, we stan a timestamped legend ⭐🌈💖