LIBPERF-COUNTING(7)

💅 LIBPERF-COUNTING — the counting interface, explained by your resident Unix bestie

okay so this is the libperf manual, page libperf-counting(7) — literally the counting interface, and it's giving tutorial energy today. buckle up, bestie, we're measuring perf events and we're gonna slay it ✨

---

🌸 NAME 🌸

libperf-counting — the counting interface. that's it, that's the vibe 🎀

---

💖 DESCRIPTION 💖

the counting interface hands you an API to measure specific perf events and get their count. no cap.

the test below tries to explain counting on the counting.c example. heads up though — it is by no means a complete guide to counting, it just shows off the basic libperf API for counting. lowkey iconic of it.

counting.c ships with the libperf package and you can compile and run it like this:

$ gcc -o counting counting.c -lperf
$ sudo ./counting
count 176792, enabled 176944, run 176944
count 176242, enabled 176242, run 176242

it requires root access, because of the PERF_COUNT_SW_CPU_CLOCK event, which is available only for root. sorry bestie, sudo or nothing 🔥

counting.c monitors two events on the current process and displays their count. in a nutshell, it:

• creates events
• adds them to the event list
• opens and enables events through the event list
• does some workload
• disables events
• reads and displays event counts
• destroys the event list

---

🦋 step one: init the library 🦋

the first thing you need to do before using libperf is to call the init function:

      8 static int libperf_print(enum libperf_print_level level,
      9                          const char *fmt, va_list ap)
     10 {
     11         return vfprintf(stderr, fmt, ap);
     12 }

     14 int main(int argc, char **argv)
     15 {
     ...
     35         libperf_init(libperf_print);

it will set up the library and set the function for debug output from the library. so thoughtful of it 🫶

the libperf_print callback will receive any message with its debug level, defined as:

enum libperf_print_level {
        LIBPERF_ERR,
        LIBPERF_WARN,
        LIBPERF_INFO,
        LIBPERF_DEBUG,
        LIBPERF_DEBUG2,
        LIBPERF_DEBUG3,
};

🧚 step two: define your events 🧚

once the setup is complete we start by defining specific events using the struct perf_event_attr.

we create software events for cpu and task:

     20         struct perf_event_attr attr1 = {
     21                 .type        = PERF_TYPE_SOFTWARE,
     22                 .config      = PERF_COUNT_SW_CPU_CLOCK,
     23                 .read_format = PERF_FORMAT_TOTAL_TIME_ENABLED|PERF_FORMAT_TOTAL_TIME_RUNNING,
     24                 .disabled    = 1,
     25         };
     26         struct perf_event_attr attr2 = {
     27                 .type        = PERF_TYPE_SOFTWARE,
     28                 .config      = PERF_COUNT_SW_TASK_CLOCK,
     29                 .read_format = PERF_FORMAT_TOTAL_TIME_ENABLED|PERF_FORMAT_TOTAL_TIME_RUNNING,
     30                 .disabled    = 1,
     31         };

the read_format setup tells perf to include timing details together with each count. timing details + count = the full picture, iykyk 💅

🍓 step three: threads map 🍓

next step is to prepare the threads map.

in this case we will monitor the current process, so we create a threads map with a single pid (0):

     37         threads = perf_thread_map__new_dummy();
     38         if (!threads) {
     39                 fprintf(stderr, "failed to create threads\n");
     40                 return -1;
     41         }
     42
     43         perf_thread_map__set_pid(threads, 0, 0);

🌈 step four: the event list 🌈

now we create libperf's event list, which will serve as the holder for the events we want:

     45         evlist = perf_evlist__new();
     46         if (!evlist) {
     47                 fprintf(stderr, "failed to create evlist\n");
     48                 goto out_threads;
     49         }

⭐ step five: make the events, add the events ⭐

we create libperf's events for the attributes we defined earlier and add them to the list:

     51         evsel = perf_evsel__new(&attr1);
     52         if (!evsel) {
     53                 fprintf(stderr, "failed to create evsel1\n");
     54                 goto out_evlist;
     55         }
     56
     57         perf_evlist__add(evlist, evsel);
     58
     59         evsel = perf_evsel__new(&attr2);
     60         if (!evsel) {
     61                 fprintf(stderr, "failed to create evsel2\n");
     62                 goto out_evlist;
     63         }
     64
     65         perf_evlist__add(evlist, evsel);

💜 step six: configure + open 💜

configure the event list with the thread map and open the events:

     67         perf_evlist__set_maps(evlist, NULL, threads);
     68
     69         err = perf_evlist__open(evlist);
     70         if (err) {
     71                 fprintf(stderr, "failed to open evsel\n");
     72                 goto out_evlist;
     73         }

👑 step seven: do the workload 👑

both events are created as disabled (note the disabled = 1 assignment up above), so we need to enable the whole list explicitly — both events, bestie, not just one.

from this moment the events are counting and we can do our workload. main character energy fr fr 💅

when we are done we disable the events list.

     75         perf_evlist__enable(evlist);
     76
     77         while (count--);
     78
     79         perf_evlist__disable(evlist);

🔥 step eight: read the counts 🔥

now we need to get the counts from the events. the following code iterates through the events list and reads the counts:

     81         perf_evlist__for_each_evsel(evlist, evsel) {
     82                 perf_evsel__read(evsel, 0, 0, &counts);
     83                 fprintf(stdout, "count %llu, enabled %llu, run %llu\n",
     84                         counts.val, counts.ena, counts.run);
     85         }

🫶 step nine: and finally, cleanup 🫶

we close the whole events list (both events) and remove it together with the threads map:

     87         perf_evlist__close(evlist);
     88
     89 out_evlist:
     90         perf_evlist__delete(evlist);
     91 out_threads:
     92         perf_thread_map__put(threads);
     93         return err;
     94 }

ate. no crumbs. ✨

---

😭 REPORTING BUGS 😭

report bugs to <linux-perf-users@vger.kernel.org[1]>. they're nice, i promise. 🐛

---

🎀 LICENSE 🎀

libperf is Free Software licensed under the GNU LGPL 2.1. 💖

---

🦋 RESOURCES 🦋

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

---

🌸 SEE ALSO 🌸

• libperf(3)
• libperf-sampling(7)

---

📝 NOTES 📝

1. linux-perf-users@vger.kernel.org — mailto:linux-perf-users@vger.kernel.org

---

and that's the whole page, bestie 🧚 this little beauty is from libperf, dated 11/01/2026, and it's filed under LIBPERF-COUNTING(7). go forth and count. 💜🌈✨