page_cache_next_miss(9)

📦 version 7.3.1, in nixpkgs unstable

💅 page_cache_next_miss(9) 💅

okay so this is from the Kernel API Manual and bestie, it's literally the "find me a hole" function. no cap, the whole personality is gap hunting 🕵️‍♀️✨

🌸 NAME 🌸

page_cache_next_miss — Find the next gap in the page cache. that's it, that's the whole job 🎀

🦋 SYNOPSIS 🦋

pgoff_t page_cache_next_miss (struct address_space *mapping , pgoff_t
index , unsigned long max_scan );

three args, one return, zero drama (well, mostly) 💜

✨ ARGUMENTS ✨

  • mapping — the Mapping. yes that's the actual description. it's giving "trust me bro" but ok 😭
  • index — the Index. where you're starting your little scavenger hunt 🔍
  • max_scan — Maximum range to search. i.e. how far you're willing to look before you give up and go home 🏃‍♀️💨

🌈 DESCRIPTION 🌈

So what it does: it searches the range [index, min(index + max_scan - 1, ULONG_MAX)] looking for the gap with the lowest index. lowkey obsessed with that formula tbh, max_scan - 1 is doing so much work there 🧚

Now the important caveat, listen up because this is the main character plot twist 👑

This function may be called under the rcu_read_lock. However, that does not mean you get an atomic search of a snapshot of the cache at a single point in time. so like... it's not a frozen-in-amber moment, it's more of a "vibes at the time of asking" situation 🙈

Example time, because examples ate: if a gap is created at index 5, and then subsequently a gap is created at index 10, a page_cache_next_miss covering both indices may return 10 if it's called under the rcu_read_lock. yeah. it might skip past the 5. she's fast, she's not psychic 💀

🔥 RETURN 🔥

  • The index of the gap if found ✅
  • otherwise an index outside the range you specified — in which case 'return - index >= max_scan' will be true. so you can actually check that, iconic behavior honestly 💅
  • and in the rare case of index wrap-around, 0 will be returned. rare but she happens 🌪️

👑 SEE ALSO 👑

Kernel file ./mm/filemap.c, plus the entire extended friend group right here — no gatekeeping, we're tagging everyone 🫶

fr fr read the range formula twice before you file that bug report, bestie 🍓

kay bye, this page came from ./mm and it's dated October 2026 — go find some gaps, slay 🧚‍♀️💖⭐

📦 where this page comes from