block_dirty_folio(9)

📦 version 7.3.1, in nixpkgs unstable

💅 block_dirty_folio(9) — like, the Kernel API Manual, but make it make sense ✨

okay bestie, so you've wandered into the kernel API manual (yes, that one) and you clicked on block_dirty_folio — good choice, this one's actually kind of a baddie. let's get into it 🫶

✨ NAME ✨

block_dirty_folio — mark a folio as dirty. that's it. that's the whole vibe. 💖

🌸 SYNOPSIS 🌸

bool block_dirty_folio (struct address_space *mapping , struct folio
*folio );

🎀 ARGUMENTS 🎀

  • mapping — the address space that's holding this folio, iykyk 💫
  • folio — the actual folio we're marking dirty. sorry bestie, it's getting dirty, no cap 🙈

🔥 DESCRIPTION 🔥

okay so listen — if your filesystem uses buffer_heads, you can literally just use this function as your ->dirty_folio implementation. iconic. 👑

some filesystems need to do a little bit of work before calling this function, and that's valid, we respect the hustle. but if your filesystem does not use buffer_heads? bestie, wrong function — you want filemap_dirty_folio instead. periodt. 💅

now here's where it gets cute. if the folio has buffers, the uptodate buffers get set dirty, and the whole reason is to preserve dirty-state coherency between the folio and the buffers. the way that consistency matters… 🦋

buffers added to a dirty folio are created dirty. born dirty. main character energy from day one, honestly. ⭐

and the order matters, okay? the buffers are dirtied before the folio is dirtied. there's a small race window in which writeback may see the folio cleanness but not the buffer dirtiness. and that's fine! 😌 but if this code were to set the folio dirty before the buffers, writeback could clear the folio dirty flag, see a bunch of clean buffers, and we'd end up with dirty buffers/clean folio on the dirty folio list. and that's giving disaster. 💀 so we don't do that.

we use i_private_lock to lock against try_to_free_buffers while using the folio's buffer list. this also prevents clean buffers being added to the folio after it was set dirty. locked down, protected, safe. 🧚

💜 CONTEXT 💜

may only be called from process context. does not sleep. 😴🚫

and the caller has to make sure that folio cannot be truncated during this call — typically by holding the folio lock or having a page in the folio mapped and holding the page table lock. no truncation, no surprises, we don't do that here. 🌈

⭐ RETURN ⭐

True if the folio was dirtied; false if it was already dirtied. slay either way tbh. 🎀

🌸 SEE ALSO 🌸

Kernel file ./fs/buffer.c — go read it, it's giving lore 👑

and that's the whole page, bestie!! 🫶 this one came from the ./fs corner of the kernel world, dated October 2026 — block_dirty_folio(9), you ate. 💅✨

📦 where this page comes from