LIBPFM(3)

💖 LIBPFM(3) — Linux Programmer's Manual 💖

okay bestie, sit down, hydrate, because we're talking about libpfm — yes the perfmon library, yes it's iconic, yes it lives in the Linux Programmer's Manual, and yes I'm about to make event iteration sound like the slay that it is. 🎀

✨ NAME ✨

pfm_get_event_next — literally just iterate over events, that's the whole job, she's a one-trick pony and the trick is flawless 🦋

🌸 SYNOPSIS 🌸

#include <perfmon/pfmlib.h>

int pfm_get_event_next(int idx);

💅 DESCRIPTION 💅

okay so here's the tea. Events are uniquely identified with opaque integer identifiers. And the way those identifiers are numbered? There is no guaranteed order within them. None. Zero. Not a vibe you can rely on. 🙈 So if you wanna list all the events, you literally have to use iterators. That's not optional, that's the whole method.

Events are grouped into tables inside the library. A table usually corresponds to one PMU model or family. And because the library supports multiple PMU models, it obviously has multiple tables, like a little closet of tables. 👑

Based on the host hardware and software environments, tables get activated when the library is initialized via pfm_initialize(). So:

• events from activated tables are called active events ✨
• events from non-activated tables are called supported events ✨

Event identifiers are usually retrieved via pfm_find_event() or when encoding events. iykyk.

Now, to iterate over a list of events for a given PMU model, all you need is an initial identifier for that PMU. The first event identifier is usually obtained via pfm_get_pmu_info(). That's your entry point, bestie, your little doorway. 🚪

And pfm_get_event_next()? She returns the identifier of the next supported event after the one you passed in idx. And the iterator stops when the last event for the PMU is passed as the argument — in which case the function returns -1. That's it. That's the finish line. 🏁

void list_pmu_events(pfm_pmu_t pmu)
{
   struct pfm_event_info info;
   struct pfm_pmu_info pinfo;
   int i, ret;

   memset(&info, 0, sizeof(info));
   memset(&pinfo, 0, sizeof(pinfo));

   info.size = sizeof(info);
   pinfo.size = sizeof(pinfo);

   ret = pfm_get_pmu_info(pmu, &pinfo);
   if (ret != PFM_SUCCESS)
      errx(1, "cannot get pmu info");

   for (i = pinfo.first_event; i != -1; i = pfm_get_event_next(i)) {
      ret = pfm_get_event_info(i, &info);
      if (ret != PFM_SUCCESS)
        errx(1, "cannot get event info");

        printf("%s Event: %s::%s\n",
               pinfo.present ? "Active" : "Supported",
               pinfo.name, info.name);
    }
}

look at that loop, she's gorgeous, she ate and left no crumbs. 💅

🫶 RETURN 🫶

The function returns the identifier of the next supported event. And she returns -1 when the argument is already the last event for the PMU. So -1 is not an error here, bestie, it's just the "we're done, go home" signal. 😌

😭 ERRORS 😭

No error code, besides -1, is returned by this function. That's the whole section. Short, sweet, no drama, no extra error codes hiding in the walls. periodt. 💀

🌈 SEE ALSO 🌈

• pfm_find_event(3)

👑 AUTHOR 👑

Stephane Eranian <eranian@gmail.com> — the icon, the legend, the moment. 🎀

quick vibe check reminder: identifiers have no guaranteed order, so don't you dare assume the numbers go up nicely. always iterate, never guess. 🧚

okay that's the whole page, you're officially a pfm_get_event_next() girlie now. 💖

this lil masterpiece comes to you from September, 2009, straight out of the Linux Programmer's Manual, filed under LIBPFM(3) — mwah, bye bestie, go iterate something. 🦋🌸✨