perfmonctl(2)

💖 perfmonctl(2) — the IA-64 perf monitoring plug, bestie edition 💖

okay so real talk, this is perfmonctl(2), and it lives in the System Calls Manual. it's giving ✨niche✨ but honestly it's iconic, so let's get into it.

---

🌸 NAME 🌸

perfmonctl — your lil' interface to the IA-64 performance monitoring unit 💅

---

✨ SYNOPSIS ✨

#include <syscall.h>
#include <perfmon.h>

long perfmonctl(int narg;
                int fd, int cmd, void arg[narg], int narg);

heads up!! There is no glibc wrapper for this system call; see HISTORY. so like, you're on your own for the actual call, bestie 😭

---

🦋 DESCRIPTION 🦋

The IA-64-specific perfmonctl() system call is basically the VIP pass to the PMU (performance monitoring unit). The PMU is made up of PMD (performance monitoring data) registers and PMC (performance monitoring control) registers, and together they gather hardware statistics. iconic behavior honestly 🎀

So what perfmonctl() actually does: it applies the operation cmd to the input arguments specified by arg. How many arguments? that's what narg is for. And fd? that's the perfmon context you're operating on, the whole vibe check of this call.

Supported values for cmd are, in order:

• PFM_CREATE_CONTEXT

perfmonctl(int fd, PFM_CREATE_CONTEXT, pfarg_context_t *ctxt, 1);

Sets up a context. ✨

The fd parameter is ignored here (lol, it's not the main character in this one). A brand new perfmon context gets created exactly as specified in ctxt, and its file descriptor is returned in ctxt->ctx_fd.

That file descriptor can be used in subsequent calls to perfmonctl(), and you can also use it to read event notifications (type pfm_msg_t) with read(2). It's pollable too, using select(2), poll(2), and epoll(7) — very demure, very mindful 🫶

And when you're done with it? Destroy the context by calling close(2) on the file descriptor. closure, periodt 💅

• PFM_WRITE_PMCS

perfmonctl(int fd, PFM_WRITE_PMCS, pfarg_reg_t *pmcs, n);

Sets PMC registers.

• PFM_WRITE_PMDS

perfmonctl(int fd, PFM_WRITE_PMDS, pfarg_reg_t *pmds, n);

Sets PMD registers.

• PFM_READ_PMDS

perfmonctl(int fd, PFM_READ_PMDS, pfarg_reg_t *pmds, n);

Reads PMD registers.

• PFM_START

perfmonctl(int fd, PFM_START, NULL, 0);

Starts monitoring. we're so back 🔥

• PFM_STOP

perfmonctl(int fd, PFM_STOP, NULL, 0);

Stops monitoring. and we're so done 💀

• PFM_LOAD_CONTEXT

perfmonctl(int fd, PFM_LOAD_CONTEXT, pfarg_load_t *largs, 1);

Attaches the context to a thread. no cap, it's a whole commitment 🫶

• PFM_UNLOAD_CONTEXT

perfmonctl(int fd, PFM_UNLOAD_CONTEXT, NULL, 0);

Detaches the context from a thread.

• PFM_RESTART

perfmonctl(int fd, PFM_RESTART, NULL, 0);

Restarts monitoring after receiving an overflow notification. second chance energy 🌈

• PFM_GET_FEATURES

perfmonctl(int fd, PFM_GET_FEATURES, pfarg_features_t *arg, 1);

• PFM_DEBUG

perfmonctl(int fd, PFM_DEBUG, val, 0);

If val is nonzero, debugging mode is enabled; otherwise it's disabled. toggle slay 💅

• PFM_GET_PMC_RESET_VAL

perfmonctl(int fd, PFM_GET_PMC_RESET_VAL, pfarg_reg_t *req, n);

Resets the PMC registers back to their default values. fresh start, we love to see it 🎀

---

💜 RETURN VALUE 💜

perfmonctl() returns zero when the operation is successful — chef's kiss. 😌

On error, -1 is returned and errno is set to indicate the error. not the vibe, but okay, we move 😭

---

🌟 STANDARDS 🌟

Linux on IA-64.

---

🕰️ HISTORY 🕰️

So, the lore: perfmonctl() showed up in Linux 2.4, and it got removed in Linux 5.10. 💀

Fun fact that's actually kinda sad: this system call was broken for many years, and was ultimately removed in Linux 5.10. rip bozo 🪦✨

And one more time for the people in the back: glibc does not provide a wrapper for this system call. On kernels where it still exists, call it using syscall(2). iykyk 🙂

---

👀 SEE ALSO 👀

• gprof(1)
• The perfmon2 interface specification

---

and that's the whole page bestie, you ate that fr fr 👑 this was from Linux man-pages 6.20, dated 2026-02-22 — mwah, sending you the biggest kiss, go forth and monitor those performance metrics responsibly 💖✨🎀🦋🌸