folio_add_pins(9)

💖 folio_add_pins(9) — Kernel API Manual, bestie edition 💖

Okay so you found yourself in the kernel API manual, section 9, and the star of the show is folio_add_pins. Buckle up, this one's short but it's lowkey important. 🫶

---

✨ NAME ✨

folio_add_pins — literally just: add pins to an already-pinned folio. That's the whole vibe. No cap.

---

🌸 SYNOPSIS 🌸

int folio_add_pins (struct folio *folio , unsigned int pins );

Look at that signature. Clean. Iconic. Two arguments, one int return. She's giving "small function, big responsibilities". 💅

---

🎀 ARGUMENTS 🎀

• folio — the folio you want to add more pins to. Your main character, your chosen one. 👑
• pins — the number of pins you're adding. Yes, you have to say how many. It's not a "just add one" situation, ok?

---

🦋 DESCRIPTION 🦋

So here's the tea ☕: this function tries to add more pins to a folio that is already pinned. Note the "try" — it's an attempt, not a guarantee, bestie.

And listen, the semantics of the pin (think FOLL_WRITE) — those follow whatever the existing pin is doing. You cannot change them. It's not that kind of party. 🙅‍♀️ The existing pin is the blueprint, and this function is just following it.

When is this even useful? Great question, glad you asked. 💖 Picture this: you already grabbed a pin on a large folio using memfd_pin_folios, but later you want to logically unpin parts of it — like individual pages, for example — using unpin_user_page_range_dirty_lock. That's the moment this function shines. It's the setup that lets you tear things down piece by piece later. Chef's kiss. 🤌

🚨 Important vibe check: this is NOT the right interface to initially pin a folio. Do not come here first. This is a second-date function, not a first-date function. Use it to add pins to a folio that already has them, periodt. 💀

---

🌈 SEE ALSO 🌈

The whole friend group, honestly. Go say hi:

Kernel file ./mm/gup.c and then a truly iconic lineup:

• try_grab_folio(9)
• 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)

Fr fr, that's a whole group chat right there. 💜

---

Mwah 💋 — this page lives in ./mm, and the version stamp says October 2026. See you in the kernel, bestie! 🧚✨