LIBPERF(3)

🌸 NAME 🌸

okay so bestie, welcome to LIBPERF(3) — this is the page for libperf, and it's literally the Linux kernel perf event library. That's the whole vibe. The manual name is libperf and it lives in section 3 of the manual (developer/library stuff, iykyk). 💅

---

✨ SYNOPSIS ✨

Generic API:

#include <perf/core.h>

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

typedef int (*libperf_print_fn_t)(enum libperf_print_level level,
                                  const char *, va_list ap);

void libperf_init(libperf_print_fn_t fn);

API to handle CPU maps:

#include <perf/cpumap.h>

struct perf_cpu_map;

struct perf_cpu_map *perf_cpu_map__new_any_cpu(void);
struct perf_cpu_map *perf_cpu_map__new(const char *cpu_list);
struct perf_cpu_map *perf_cpu_map__get(struct perf_cpu_map *map);
struct perf_cpu_map *perf_cpu_map__merge(struct perf_cpu_map *orig,
                                         struct perf_cpu_map *other);
void perf_cpu_map__put(struct perf_cpu_map *map);
int perf_cpu_map__cpu(const struct perf_cpu_map *cpus, int idx);
int perf_cpu_map__nr(const struct perf_cpu_map *cpus);
bool perf_cpu_map__has_any_cpu_or_is_empty(const struct perf_cpu_map *map);
int perf_cpu_map__max(struct perf_cpu_map *map);
bool perf_cpu_map__has(const struct perf_cpu_map *map, int cpu);

#define perf_cpu_map__for_each_cpu(cpu, idx, cpus)

API to handle thread maps:

#include <perf/threadmap.h>

struct perf_thread_map;

struct perf_thread_map *perf_thread_map__new_dummy(void);
struct perf_thread_map *perf_thread_map__new_array(int nr_threads, pid_t *array);

void perf_thread_map__set_pid(struct perf_thread_map *map, int idx, pid_t pid);
char *perf_thread_map__comm(struct perf_thread_map *map, int idx);
int perf_thread_map__nr(struct perf_thread_map *threads);
pid_t perf_thread_map__pid(struct perf_thread_map *map, int idx);

struct perf_thread_map *perf_thread_map__get(struct perf_thread_map *map);
void perf_thread_map__put(struct perf_thread_map *map);

API to handle event lists:

#include <perf/evlist.h>

struct perf_evlist;

void perf_evlist__add(struct perf_evlist *evlist,
                      struct perf_evsel *evsel);
void perf_evlist__remove(struct perf_evlist *evlist,
                         struct perf_evsel *evsel);
struct perf_evlist *perf_evlist__new(void);
void perf_evlist__delete(struct perf_evlist *evlist);
struct perf_evsel* perf_evlist__next(struct perf_evlist *evlist,
                                     struct perf_evsel *evsel);
int perf_evlist__open(struct perf_evlist *evlist);
void perf_evlist__close(struct perf_evlist *evlist);
void perf_evlist__enable(struct perf_evlist *evlist);
void perf_evlist__disable(struct perf_evlist *evlist);

#define perf_evlist__for_each_evsel(evlist, pos)

void perf_evlist__set_maps(struct perf_evlist *evlist,
                           struct perf_cpu_map *cpus,
                           struct perf_thread_map *threads);
int perf_evlist__poll(struct perf_evlist *evlist, int timeout);
int perf_evlist__filter_pollfd(struct perf_evlist *evlist,
                               short revents_and_mask);

int perf_evlist__mmap(struct perf_evlist *evlist, int pages);
void perf_evlist__munmap(struct perf_evlist *evlist);

struct perf_mmap *perf_evlist__next_mmap(struct perf_evlist *evlist,
                                         struct perf_mmap *map,
                                         bool overwrite);

#define perf_evlist__for_each_mmap(evlist, pos, overwrite)

API to handle events:

#include <perf/evsel.h>*

struct perf_evsel;

struct perf_counts_values {
        union {
                struct {
                        uint64_t val;
                        uint64_t ena;
                        uint64_t run;
                };
                uint64_t values[3];
        };
};

struct perf_evsel *perf_evsel__new(struct perf_event_attr *attr);
void perf_evsel__delete(struct perf_evsel *evsel);
int perf_evsel__open(struct perf_evsel *evsel, struct perf_cpu_map *cpus,
                     struct perf_thread_map *threads);
void perf_evsel__close(struct perf_evsel *evsel);
void perf_evsel__close_cpu(struct perf_evsel *evsel, int cpu_map_idx);
int perf_evsel__mmap(struct perf_evsel *evsel, int pages);
void perf_evsel__munmap(struct perf_evsel *evsel);
void *perf_evsel__mmap_base(struct perf_evsel *evsel, int cpu_map_idx, int thread);
int perf_evsel__read(struct perf_evsel *evsel, int cpu_map_idx, int thread,
                     struct perf_counts_values *count);
int perf_evsel__enable(struct perf_evsel *evsel);
int perf_evsel__enable_cpu(struct perf_evsel *evsel, int cpu_map_idx);
int perf_evsel__disable(struct perf_evsel *evsel);
int perf_evsel__disable_cpu(struct perf_evsel *evsel, int cpu_map_idx);
struct perf_cpu_map *perf_evsel__cpus(struct perf_evsel *evsel);
struct perf_thread_map *perf_evsel__threads(struct perf_evsel *evsel);
struct perf_event_attr *perf_evsel__attr(struct perf_evsel *evsel);

API to handle maps (perf ring buffers):

#include <perf/mmap.h>

struct perf_mmap;

void perf_mmap__consume(struct perf_mmap *map);
int perf_mmap__read_init(struct perf_mmap *map);
void perf_mmap__read_done(struct perf_mmap *map);
union perf_event *perf_mmap__read_event(struct perf_mmap *map);

Structures to access perf API events:

#include <perf/event.h>

struct perf_record_mmap;
struct perf_record_mmap2;
struct perf_record_comm;
struct perf_record_namespaces;
struct perf_record_fork;
struct perf_record_lost;
struct perf_record_lost_samples;
struct perf_record_read;
struct perf_record_throttle;
struct perf_record_ksymbol;
struct perf_record_bpf_event;
struct perf_record_sample;
struct perf_record_switch;
struct perf_record_header_attr;
struct perf_record_record_cpu_map;
struct perf_record_cpu_map_data;
struct perf_record_cpu_map;
struct perf_record_event_update_cpus;
struct perf_record_event_update_scale;
struct perf_record_event_update;
struct perf_trace_event_type;
struct perf_record_header_event_type;
struct perf_record_header_tracing_data;
struct perf_record_header_build_id;
struct perf_record_id_index;
struct perf_record_auxtrace_info;
struct perf_record_auxtrace;
struct perf_record_auxtrace_error;
struct perf_record_aux;
struct perf_record_itrace_start;
struct perf_record_thread_map_entry;
struct perf_record_thread_map;
struct perf_record_stat_config_entry;
struct perf_record_stat_config;
struct perf_record_stat;
struct perf_record_stat_round;
struct perf_record_time_conv;
struct perf_record_header_feature;
struct perf_record_compressed;
struct perf_record_compressed2;
struct perf_record_schedstat_cpu;
struct perf_record_schedstat_domain;

---

🦋 DESCRIPTION 🦋

So like, the libperf library gives you an API to get at the Linux kernel perf events subsystem. That's it, that's the whole purpose, and honestly? iconic. 👑

These objects right here are the main characters of the libperf interface:

• struct perf_cpu_map — gives you a whole CPU list abstraction. one little struct, all the CPUs. slay. ✨
• struct perf_thread_map — same deal but for threads: a thread list abstraction.
• struct perf_evsel — the abstraction for a single perf event. (yes, single, that's the point 🎀)
• struct perf_evlist — this one gathers up several struct perf_evsel objects and then performs functions on all of them at once. group project but it actually works.
• struct perf_mmap — the abstraction for accessing the perf ring buffer. lowkey the coolest one ngl. 💜

And the exported API functions? They're the glue that binds all these objects together. fr fr. 🫶

---

😭 REPORTING BUGS 😭

Found a bug? Do not suffer in silence bestie — report bugs to <linux-perf-users@vger.kernel.org[1]>. 🐛

---

📜 LICENSE 📜

libperf is Free Software licensed under the GNU LGPL 2.1. protect it at all costs. 💖

---

🌈 RESOURCES 🌈

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

that's the link. go touch the source, it's giving main character energy. 🧚

---

👀 SEE ALSO 👀

• libperf-sampling(7)
• libperf-counting(7)

both in section 7, both your new besties. 💅

---

🎀 NOTES 🎀

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

---

okay that's the whole page bestie, you ate that. this was libperf, from the libperf Manual, version/date stamp 11/01/2026, and you can find it filed under LIBPERF(3). mwah. 💋🌸⭐