PAGEMAP_SCAN(2const)

✨ NAME ✨

PAGEMAP_SCAN — get and/or clear page flags 💅

So this is a 2const page, bestie — a little const-flavored slice of the ioctl(2) family, living its best life under <pink>PAGEMAP_SCAN(2const)</pink>. It's the one that reads page flags and optionally wipes some of them clean. 🧹

Also, library check: it's the Standard C library (libc, -lc), don't forget to link it. 💖

---

🌈 LIBRARY 🌈

Standard C library (libc, -lc)

---

🦋 SYNOPSIS 🦋

#include <linux/fs.h>  /* Definition of PAGE* and PM_* constants */
#include <sys/ioctl.h>

int ioctl(int pagemap_fd, PAGEMAP_SCAN, struct pm_scan_arg *arg);

#include <linux/fs.h>

struct pm_scan_arg {
    __u64  size;
    __u64  flags;
    __u64  start;
    __u64  end;
    __u64  walk_end;
    __u64  vec;
    __u64  vec_len;
    __u64  max_pages;
    __u64  category_inverted;
    __u64  category_mask;
    __u64  category_anyof_mask;
    __u64  return_mask;
};

struct page_region {
    __u64  start;
    __u64  end;
    __u64  categories;
};

Like. That's the whole vibe. Two headers, one ioctl call, two structs. Clean. Iconic. 🎀

---

💖 DESCRIPTION 💖

Okay so this ioctl(2) is the one that gets and optionally clears some very specific flags from page table entries. And when it reports back? It does it with PAGE_SIZE granularity, no in-between, periodt. ✨

Now here's the setup part that lowkey trips people up — listen:

To start tracking the written state (that's the flag) of a page or a whole range of memory, you need UFFD_FEATURE_WP_ASYNC to be enabled by the UFFDIO_API ioctl(2) on userfaultfd, and the memory range has to be registered with the UFFDIO_REGISTER ioctl(2) in UFFDIO_REGISTER_MODE_WP mode.

Both of those. Not one. Both. 🙈

---

⭐ Supported page flags ⭐

These are the page table entry flags that get support:

• PAGE_IS_WPALLOWED — the page has asynchronous write-protection enabled. It's allowed to be write-protected, basically. 🛡️
• PAGE_IS_WRITTEN — the page has been written to from the time it was write protected. Somebody touched it. 👀
• PAGE_IS_FILE — the page is file backed. 📄
• PAGE_IS_PRESENT — the page is present in the memory. She's here. 💁
• PAGE_IS_SWAPPED — the page is swapped. 🌀
• PAGE_IS_PFNZERO — the page has zero PFN. 🫧
• PAGE_IS_HUGE — the page is THP or Hugetlb backed. Big girl energy. 🐘

---

🔥 Supported operations 🔥

The get operation is always performed if the output buffer is specified — it doesn't ask, it just does it. 💅

The other operations are as follows:

• PM_SCAN_WP_MATCHING — write protect the matched pages. ✍️
• PM_SCAN_CHECK_WPASYNC — abort the scan when a page is found which doesn't have the Userfaultfd Asynchronous Write protection enabled. 🚨 Like, she will stop the whole thing. Dramatic but valid.

---

🎀 The struct pm_scan_arg argument 🎀

Field-by-field, let's go:

• size — this field should be set to the size of the structure in bytes, as in sizeof(struct pm_scan_arg). Measure yourself before you go out, bestie. 📏
• flags — the operations to be performed are specified in it. 🚩
• start — the starting address of the scan is specified in it. 🏁
• end — the ending address of the scan is specified in it. 🏁
• walk_end — the kernel returns the scan's ending address in it. And a walk_end equal to end means that the scan has completed on the entire range. If they match, you're done, slay. ✅
• vec — the address of the page_region array for output. 🗂️
• vec_len — the length of the page_region struct array. 📚
• max_pages — it is the optional limit for the number of output pages required. Capped. 🧢
• category_inverted — PAGE_IS_* categories which values match if 0 instead of 1. Contrarian queen. 🙃
• category_mask — skip pages for which any PAGE_IS_* category doesn't match. ⏭️
• category_anyof_mask — skip pages for which no PAGE_IS_* category matches. ⏭️
• return_mask — PAGE_IS_* categories that are to be reported in page_region. 📢

---

😭 RETURN VALUE 😭

On error, -1 is returned, and errno is set to indicate the error. That's it. That's the whole scene. 💀

---

🚨 ERRORS 🚨

Error codes can be one of, but are not limited to, the following — so don't think this list is the entire lore, iykyk:

• EINVAL — invalid arguments i.e., invalid size of the argument, invalid flags, invalid categories, the start address isn't aligned with PAGE_SIZE, or vec_len is specified when vec is NULL. So many ways to be wrong bestie, align your addresses. 🫠
• EFAULT — invalid arg pointer, invalid vec pointer, or invalid address range specified by start and end. 🧭
• ENOMEM — no memory is available. 💸
• EINTR — fatal signal is pending. ⚡

Fr fr, EINVAL is doing a lot of heavy lifting here. Read your errors, don't guess. 🙏

---

👑 STANDARDS 👑

Linux.

---

🌸 HISTORY 🌸

Linux 6.7. Newer than you think. 🌱

---

🦄 SEE ALSO 🦄

• ioctl(2)

---

💖 Okay that's the whole page, bestie. Go forth and scan those page maps. This little love letter is from Linux man-pages 6.20, dated 2026-05-16 — shoutout to the PAGEMAP_SCAN(2const) girlies, you ate and left no crumbs 👑✨🫶