vm_map_pages(9)

💜 vm_map_pages — the vm_map_pages(9) glow-up

okay so bestie, welcome to the Kernel API Manual entry for vm_map_pages, and trust me when I say this little function is doing the most for your mmap handler. grab a strawberry 🍓 and let's get into it.

---

✨ NAME ✨

vm_map_pages — maps a range of kernel pages, and it starts with a non zero offset, which is kind of the whole personality trait here. no cap.

---

🌸 SYNOPSIS 🌸

int vm_map_pages (struct vm_area_struct *vma , struct page **pages ,
unsigned long num );

that's the whole signature, periodt. it returns an int, and it takes exactly three things. slay.

---

🎀 ARGUMENTS 🎀

• vma — the user vma you're mapping into. it's the vibe check of address spaces, and it's the one getting the pages.
• pages — a pointer to an array of source kernel pages. literally the pages. the raw material. 👑
• num — how many pages are in that page array. the count. don't get it wrong bestie, it's unsigned long.

---

🦋 DESCRIPTION 🦋

so what does it actually do? it maps an object made of num pages, and it caters to the user's requested vm_pgoff while doing it. iykyk. ✨

here's the part you actually need to remember, so listen up: if we fail to insert any page into the vma, the function returns immediately — and it leaves any previously inserted pages exactly where they are. it does not clean up after itself. 💀

so what do you do about it? depends on where you're calling from:

• Callers from the mmap handler may immediately return the error — because their caller will destroy the vma, which removes any successfully inserted pages for them. easy. 🫶
• Other callers should make their own arrangements for calling unmap_region. that's on you, bestie. no one's coming to save you. 🙈

fr fr, do not sleep on that cleanup step. the function will not do it for you.

---

🧚 CONTEXT 🧚

process context. called by mmap handlers. that's it, that's the vibe. 🌈

---

⭐ RETURN ⭐

0 on success, and an error code otherwise. iconic behaviour, honestly. 💅

---

🔥 SEE ALSO 🔥

kernel file ./mm/memory.c, plus the whole friend group:

• free_pgd_range(9)
• free_pgtables(9)
• __vm_normal_page(9)
• vm_normal_page(9)
• vm_normal_folio(9)
• vm_normal_page_pmd(9)
• vm_normal_folio_pmd(9)
• vm_normal_page_pud(9)
• restore_exclusive_pte(9)
• cond_install_uffd_wp_ptes(9)
• zap_vma_for_reaping(9)
• unmap_vmas(9)
• zap_vma_range_batched(9)
• zap_vma_range(9)
• zap_special_vma_range(9)
• vm_insert_pages(9)
• vm_insert_page(9)
• vm_map_pages_zero(9)
• vmf_insert_pfn_prot(9)
• vmf_insert_pfn(9)
• remap_pfn_range(9)
• vm_iomap_memory(9)
• __vmf_anon_prepare(9)
• finish_mkwrite_fault(9)
• unmap_mapping_folio(9)
• unmap_mapping_pages(9)
• unmap_mapping_range(9)
• set_pte_range(9)
• finish_fault(9)
• mm_account_fault(9)
• follow_pfnmap_start(9)
• follow_pfnmap_end(9)
• generic_access_phys(9)
• access_remote_vm(9)
• copy_remote_vm_str(9)
• folio_zero_user(9)

---

and that's the page!! 💖 this one lives in ./mm and it's dated October 2026 — go forth and map your pages responsibly, bestie. main character energy only. 🦋✨