follow_pfnmap_start(9)

📦 version 7.3.1, in nixpkgs unstable

🌸 follow_pfnmap_start — NAME 🌸

okay so bestie, listen: follow_pfnmap_start is the function that ~looks up a pfn mapping at a user virtual address~ ✨ that's the whole vibe. It's from the Kernel API Manual (yes, that's the manual name, we're fancy here 💅).

✨ SYNOPSIS ✨

int follow_pfnmap_start (struct follow_pfnmap_args *args );

🎀 ARGUMENTS 🎀

  • args — a pointer to struct follow_pfnmap_args. That's it. That's the whole argument list. She's lowkey minimal, we respect it 🫶

💖 DESCRIPTION 💖

okay so here's the tea ☕ — before you call this, you (the caller, bestie, that's you) need to set up args->vma and args->address so they point at the virtual address you want looked up. Do that, and on a successful return the results get dropped into the other output fields. slay ✨

But here's the part people forget and it's giving major red flag energy: after you're done using those fields, you must call follow_pfnmap_end — that's what properly releases the locks and resources of this lookup request. No leaving it hanging, okay? 🙈

So during the start and end calls, the stuff in args is valid because the proper locks are held for you. But after end is called? Every field in follow_pfnmap_args is INVALID and you cannot touch it, periodt. If you keep using that info after end, you need to do proper synchronizations yourself against page table updates — otherwise congrats, you just created a security bug 😭💀

And if the PTE maps a refcounted page? That's on the caller too — you're responsible for protecting against invalidation with MMU notifiers. Skip that and accessing the PFN later in time can trigger a use-after-free. not cute. not the vibe. 🚩

Also important, iykyk:

Only IO mappings and raw PFN mappings are allowed. The mmap semaphore should be taken for read, and the mmap semaphore cannot be released before end is invoked.

And one more, because people keep trying it: this function must not be used to modify PTE content. She looks, she does not touch. 🧚

⭐ RETURN ⭐

  • zero on success 🎉
  • negative otherwise 😔

🦋 SEE ALSO 🦋

All of these are defined in the kernel file ./mm/memory.c, and honestly? The whole friend group showed up for this one:

and that's the whole page, bestie 💜 this one's sourced from ./mm and dated October 2026 — go forth, take your mmap semaphore for read, and remember to call follow_pfnmap_end. mwah 🫶🎀

📦 where this page comes from