try_grab_folio(9)

💅 try_grab_folio — a whole manual page, bestie

okay so this is the try_grab_folio(9) page from the Kernel API Manual and honestly? it's short but it matters. buckle up 🎀

---

✨ NAME ✨

try_grab_folio — bump a folio's refcount by an amount that depends on a flag. that's the whole vibe 🦋

---

🌸 SYNOPSIS 🌸

int try_grab_folio (struct folio *folio , int refs , unsigned int flags
);

like, the signature is right there, no cap.

---

🎀 ARGUMENTS 🎀

• folio — the pointer to the folio you wanna grab. she's the main character 💅
• refs — the value to (effectively) add to the folio's refcount. "effectively" doing a lot of heavy lifting there, iykyk.
• flags — the gup flags. these are the FOLL_* flag values. so many little guys.

---

🦋 DESCRIPTION 🦋

bestie, listen — this function might not do anything at all, depending on the flags argument. literally might just be standing there looking pretty 🙈

the "grab" names in this file mean: "look at flags to decide whether to use FOLL_PIN or FOLL_GET behavior, when incrementing the folio's refcount."

either FOLL_PIN or FOLL_GET (or neither) may be set — but not both at the same time. it's giving "pick a lane" energy fr fr. 🔥

• -ENOMEM — FOLL_GET or FOLL_PIN was set, but the folio could not be grabbed. sad girl hours 😭

it gets called when we already have a stable reference for the folio, typically in the GUP slow path. slow path, but make it iconic ⭐

---

👑 RETURN 👑

0 for success, or if no action was required — like, if neither FOLL_PIN nor FOLL_GET was set, nothing is done. she said "not my problem" and left 💀

a negative error code for failure. that's it, that's the whole return contract.

---

🌈 SEE ALSO 🌈

kernel file ./mm/gup.c, plus a whole friend group of related functions:

unpin_user_page(9), unpin_folio(9), folio_add_pin(9), unpin_user_pages_dirty_lock(9), unpin_user_page_range_dirty_lock(9), unpin_user_pages(9), unpin_user_folio(9), unpin_folios(9), try_grab_folio_fast(9), follow_page_mask(9), __get_user_pages(9), fixup_user_fault(9), populate_vma_page_range(9), fault_in_writeable(9), fault_in_subpage_writeable(9), fault_in_readable(9), get_dump_page(9), get_user_pages_remote(9), get_user_pages(9), get_user_pages_fast_only(9), get_user_pages_fast(9), pin_user_pages_fast(9), pin_user_pages_remote(9), pin_user_pages(9), memfd_pin_folios(9), folio_add_pins(9) ✨

like, the whole pin/unpin extended universe. obsessed. 🫶

---

quick reminder bestie: FOLL_PIN and FOLL_GET are mutually exclusive — both at once is a no-go, and that's a fact, not an opinion 💜

---

okay and finally, the cute little sign-off: this page lives in the ./mm part of the kernel source tree (that's the source/version bit 🌸) and it's dated October 2026 — yes, future-coded of her. bye bestie, go grab some folios responsibly 🧚💖