ring_buffer_read_page(9)

📦 version 7.3.1, in nixpkgs unstable

💫 NAME 💫

ring_buffer_read_page — the function that yanks a whole page out of the ring buffer and consumes it, no take-backs 🫶

This lil guy lives in the Kernel API Manual, section 9. Yeah bestie, we're in the kernel now — bring snacks 🍓

✨ SYNOPSIS ✨

int ring_buffer_read_page (struct trace_buffer *buffer , struct
       buffer_data_read_page *data_page , size_t len , int cpu , int full );

That's the whole signature, character for character, don't @ me 💅

🎀 ARGUMENTS 🎀

  • buffer — the buffer we're extracting from. the main character of this whole operation, honestly 👑
  • data_page — the page you're gonna use, and it must be one allocated from ring_buffer_alloc_read_page. no substitutions, no randoms 🙈
  • len — how much you want to extract 🌸
  • cpu — the cpu of the buffer you're extracting from 🦋
  • full — should the extraction only happen when the page is full? that's the vibe check right there ⭐

💖 DESCRIPTION 💖

okay so here's the tea ☕ — this function pulls out a page from the ring buffer and consumes it. Like, it's gone. eaten. ate and left no crumbs 🔥

data_page seriously has to be the address of the variable that was returned from ring_buffer_alloc_read_page. Not a copy, not a cousin of it — the address of the variable itself. Why? because the page might be used to swap with a page in the ring buffer, and if you passed something else it would not slay 💀

for example, literally right here:

rpage = ring_buffer_alloc_read_page(buffer, cpu);
if (IS_ERR(rpage))
       return PTR_ERR(rpage);
ret = ring_buffer_read_page(buffer, rpage, len, cpu, 0);
if (ret >= 0)
       process_page(ring_buffer_read_page_data(rpage), ret);
ring_buffer_free_read_page(buffer, cpu, rpage);

see how rpage gets passed in? yeah. that's the whole point 🫶

when full is set, the function will not return true unless the writer is off the reader page. like, it's picky and it's valid for being picky ✨

🌈 NOTE 🌈

it is up to the calling functions to handle sleeps and wakeups, fr fr 😭 the ring buffer can be used anywhere in the kernel, so it can not blindly call wake_up. the layer that uses the ring buffer must be responsible for that. that's on you bestie, not on the buffer 💅

⭐ RETURN ⭐

  • >=0 — data has been transferred! 🎉 it returns the offset of consumed data.
  • <0 — no data has been transferred 😔 nothing happened, no page for you.

🦋 SEE ALSO 🦋

Kernel file ./kernel/trace/ring_buffer.c — and the whole extended friend group 👑

okay that's the whole page, no cap 💜 this beauty ships out of ./kernel/trace, dated October 2026, and it's manual page ring_buffer_read_page(9) from the Kernel API Manual. go read a ring buffer, bestie — you're gonna eat 🌸✨👑

📦 where this page comes from