PMC_ATTACH(3)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💖 PMC_ATTACH(3) — bestie edition 💖

ok so this one is pmc_attach and pmc_detach, straight out of the Performance Counters Library (libpmc, link it with -lpmc), and it's the manual page for the PMC_ATTACH(3) family of functions. it's giving "let me introduce my little counters to your processes" energy and honestly? iconic. 🎀

✨ SYNOPSIS ✨

#include <pmc.h>

int
pmc_attach(pmc_id_t pmcid, pid_t pid);

int
pmc_detach(pmc_id_t pmcid, pid_t pid);

that's the whole vibe. two functions, two ints, one header. slay. 💅

🌸 DESCRIPTION 🌸

okay so these two functions are literally the bouncers for the set of target processes that a process scope PMC keeps track of. like, who's allowed in the club, who's getting kicked out. 🫶

Function pmc_attach() attaches a process scope PMC — the one you name with argument pmcid — to a target process — the one you name with argument pid. and here's a cute little detail: pid can be zero, and zero means "the current process," i.e. you. self-love, periodt. 💖

if the PMC was allocated with the modifier PMC_F_DESCENDANTS, then it will additionally attach to the current and future descendents of the target process you specified. the whole family tree gets tracked, no cap. 🌈

real talk though: the PMC should be in a quiescent state — meaning not running. don't try to attach a live one, it will not go well for you, bestie. 💀

Function pmc_detach() does the opposite: it detaches a process scope PMC specified by argument pmcid from a process specified by argument pid. and again, pid may be zero to denote the current process. bye bestie, you're uninvited. 👋

⭐ RETURN VALUES ⭐

upon successful completion, the value 0 is returned. and when it's not a slay? the value -1 is returned and the global variable errno gets set to indicate the error. so check your errno, it's literally telling you what went wrong. 🦋

🔥 ERRORS 🔥

💜 a call to pmc_attach() may fail with these:

  • [EBUSY] — argument pmcid specified a PMC that was not in a quiescent state. it's busy, it's booked, it's not taking visitors rn. 😭
  • [EBUSY] — the target process specified by function pmc_attach is already being tracked by another process scope PMC that uses the same PMC hardware resources. two PMCs fighting over the same hardware, not the vibe check we wanted.
  • [EEXIST] — the target process is already being tracked by the specified PMC. bestie it's already in the group chat, stop re-adding it. 🙈
  • [EINVAL] — argument pmcid specified a PMC with system scope. wrong scope, wrong party. ✨
  • [EINVAL] — argument pid specified an illegal process id. that's not a real pid, girl.
  • [EINVAL] — the current process does not own a PMC with the handle specified in argument pmcid. not yours, don't touch. 💅
  • [EPERM] — the caller lacked the privilege needed to attach PMCs to the specified target process. permissions said no. 💀
  • [EPERM] — (i386 and amd64 architectures) the PMC specified by argument pmcid has been setup to allow the use of the RDPMC instruction for self measurement. yeah, that setup doesn't allow this. nope. 🙅
  • [ESRCH] — the current process does not own any PMCs. zero PMCs, zero chill.
  • [ESRCH] — the process specified by argument pid did not exist. ghost process. it's giving nothing because it's not there. 👻

🦋 a call to pmc_detach() may fail with these:

  • [EINVAL] — argument pmcid specified a PMC with system scope. again. wrong scope. periodt. ✨
  • [EINVAL] — argument pid specified an illegal process id. same energy, still illegal.
  • [EINVAL] — the current process does not own a PMC with the handle specified in argument pmcid. not your PMC, not your problem, but also: EINVAL. 💅
  • [EINVAL] — the specified PMC was not attached to the target process. you can't detach what was never attached, bestie, that's not how this works. 😭
  • [ESRCH] — the current process does not own any PMCs. empty hands, empty PMC list.
  • [ESRCH] — the process specified by argument pid is not being monitored by hwpmc(4). nobody's watching that one.
  • [ESRCH] — the process specified by argument pid did not exist. still a ghost. still ESRCH. 👻

🌟 SEE ALSO 🌟

go read them, iykyk. 📚✨

and that's the whole page, bestie!! 💖 this little masterpiece came from Debian, dated November 25, 2007 — vintage but still absolutely serving. mwah, go attach some PMCs responsibly 🫶🎀

📦 where this page comes from