STRUCT AUXTRACE_BUFFER(9)

💖 struct auxtrace_buffer(9) 💖

okay so bestie, welcome to the Kernel API Manual ✨ and today's main character is struct auxtrace_buffer — literally the container that holds AUX area tracing data. yes, that AUX area. she's iconic, she's in ./tools/perf/util, and she's about to be explained in full. buckle up 🎀

---

🌸 NAME 🌸

struct auxtrace_buffer — a buffer containing AUX area tracing data. that's it, that's the vibe 💅

---

✨ SYNOPSIS ✨

struct auxtrace_buffer {
    struct list_head        list;
    size_t size;
    pid_t pid;
    pid_t tid;
    struct perf_cpu         cpu;
    void *data;
    off_t data_offset;
    void *mmap_addr;
    size_t mmap_size;
    bool data_needs_freeing;
    bool consecutive;
    u64 offset;
    u64 reference;
    u64 buffer_nr;
    size_t use_size;
    void *use_data;
 };

look at her. sixteen fields. all of them important. no cap 🔥

---

🦋 Members 🦋

time for the roll call, and every single one of them is getting their moment, periodt:

• list — buffers get queued up in a list, and that list is held by struct auxtrace_queue. it's giving group chat energy tbh 💬
• size — the size of the buffer, in bytes. yes, bytes. keep up 🍓
• pid — in per-thread mode, the pid this buffer is associated with
• tid — in per-thread mode, the tid this buffer is associated with. (yes, they're a package deal, iykyk)
• cpu — in per-cpu mode, the cpu this buffer is associated with
• data — the actual buffer data. and listen: it can be null if the data has not been loaded yet 🙈 don't panic, that's legal
• data_offset — the file offset at which the buffer can be read
• mmap_addr — the mmap address at which the buffer can be read
• mmap_size — the size of the mmap at mmap_addr. they match, bestie, it's a set 💜
• data_needs_freeing — the data was malloc'd, so free it when it is no longer needed. this is your reminder, don't ghost it 😭
• consecutive — the original data was split up, and this buffer is consecutive to the previous buffer. so she's a sequel ✨
• offset — the offset as determined by the aux_head / aux_tail members of struct perf_event_mmap_page
• reference — an implementation-specific reference determined when the data is recorded. implementation-specific means it's giving mysterious. don't ask, she won't tell 🫶
• buffer_nr — used to number each buffer. everyone gets a number, no queue-jumping 😌
• use_size — the implementation actually only uses this number of bytes
• use_data — the implementation actually only uses data starting at this address

girlie, note the pattern on the last two: use_size and use_data are the actual slice being used. the full buffer is bigger. don't get caught out 💀

---

🌈 SEE ALSO 🌈

Kernel file ./tools/perf/util/auxtrace.h

• struct itrace_synth_opts(9)
• struct auxtrace_index_entry(9)
• struct auxtrace_index(9)
• struct auxtrace(9)
• struct auxtrace_queue(9)
• struct auxtrace_queues(9)
• struct auxtrace_heap_item(9)
• struct auxtrace_heap(9)
• struct auxtrace_mmap(9)
• struct auxtrace_mmap_params(9)
• struct auxtrace_record(9)
• struct addr_filter(9)
• struct addr_filters(9)

read them all, they're the extended universe 🧚‍♀️

---

okay and that's the whole page, bestie! this one came from ./tools/perf/util, October 2026, and it's filed under struct auxtrace_buffer(9) — go forth and trace your AUX areas responsibly 👑💖