get_user_pages_remote(9)

📦 version 7.3.1, in nixpkgs unstable

✨ get_user_pages_remote(9) ✨

ok okay so we're in the Kernel API Manual bestie, and this one is literally called get_user_pages_remote — it's the "pin user pages in memory" girlie 💅

🌸 SYNOPSIS 🌸

long get_user_pages_remote (struct mm_struct *mm , unsigned long start ,
       unsigned long nr_pages , unsigned int gup_flags , struct page **pages ,
       int *locked );

like, that's the whole signature, no notes 💖

🎀 ARGUMENTS 🎀

  • mm — the mm_struct of the target mm. that's the address space we're snooping around in 👀
  • start — the starting user address. where the lil adventure begins ✨
  • nr_pages — how many pages from start we're pinning. the page count, the vibe count 🦋
  • gup_flags — flags that modify the lookup behaviour. this is where you get to customise 🎨
  • pages — the array that receives pointers to the pages pinned. should be at least nr_pages long. or NULL, if the caller only intends to ensure the pages are faulted in 🫶
  • locked — pointer to the lock flag that says whether the lock is held, and subsequently whether VM_FAULT_RETRY functionality can be utilised. the lock must initially be held — no cap, that's a requirement 😤

💜 DESCRIPTION 💜

so it returns either the number of pages pinned (which may be less than the number requested 😭) or an error. the deets on the return value:

  • if nr_pages is 0, returns 0.
  • if nr_pages is >0 but no pages were pinned, returns -errno.
  • if nr_pages is >0 and some pages were pinned, returns the number of pages pinned. again, this may be less than nr_pages. she's allowed to under-deliver, it's fine 💀

the caller is responsible for releasing the returned pages, via put_page. that's on you, bestie, don't forget 🔥

must be called with mmap_lock held for read or write. periodt.

get_user_pages_remote walks a process's page tables and takes a reference to each struct page that each user address corresponds to at a given instant. like, it takes the page that would be accessed if a user thread accesses the given user virtual address at that instant. a lil snapshot 📸

this does not guarantee that the page exists in the user mappings when get_user_pages_remote returns, and there may even be a completely different page there in some cases (eg. if mmapped pagecache has been invalidated and subsequently re-faulted). however, it does guarantee that the page won't be freed completely. and mostly callers simply care that the page contains data that was valid at some point in time. typically, an IO or similar operation cannot guarantee anything stronger anyway because locks can't be held over the syscall boundary. it's giving "best we can do" energy 🙈

if gup_flags & FOLL_WRITE == 0, the page must not be written to. if the page is written to, set_page_dirty (or set_page_dirty_lock, as appropriate) must be called after the page is finished with, and before put_page is called. write that down 📝

get_user_pages_remote is typically used for fewer-copy IO operations, to get a handle on the memory by some means other than accesses via the user virtual addresses. the pages may be submitted for DMA to devices or accessed via their kernel linear mapping (via the kmap APIs). care should be taken to use the correct cache flushing APIs. 🧚

see also get_user_pages_fast, for performance critical applications ⚡

🌈 big note: get_user_pages_remote should be phased out in favor of get_user_pages_locked|unlocked or get_user_pages_fast. nothing should use get_user_pages_remote because it cannot pass FAULT_FLAG_ALLOW_RETRY to handle_mm_fault. she's deprecated, your honor 💀👑

🦋 SEE ALSO 🦋

kernel file ./mm/gup.c — and the whole friend group:

that's the whole page, bestie, no crumbs left 🍓 this one came from the source dir ./mm and it's dated October 2026 — so like, future vibes only 👑✨ byeee 🫶💖

📦 where this page comes from