ioctl_pagemap_scan(2) System Calls Manual ioctl_pagemap_scan(2)

ioctl_pagemap_scan - get and/or clear page flags

Standard C library (libc, -lc)

#include <linux/fs.h>  /* Definition of struct pm_scan_arg,
                          struct page_region, and PAGE_IS_* constants */
#include <sys/ioctl.h>
int ioctl(int pagemap_fd, PAGEMAP_SCAN, struct pm_scan_arg *arg);

This ioctl(2) is used to get and optionally clear some specific flags from page table entries. The information is returned with PAGE_SIZE granularity.

To start tracking the written state (flag) of a page or range of memory, the UFFD_FEATURE_WP_ASYNC must be enabled by UFFDIO_API ioctl(2) on userfaultfd and memory range must be registered with UFFDIO_REGISTER ioctl(2) in UFFDIO_REGISTER_MODE_WP mode.

The following page table entry flags are supported:

The page has asynchronous write-protection enabled.
The page has been written to from the time it was write protected.
The page is file backed.
The page is present in the memory.
The page is swapped.
The page has zero PFN.
The page is THP or Hugetlb backed.

The get operation is always performed if the output buffer is specified. The other operations are as following:

Write protect the matched pages.
Abort the scan when a page is found which doesn't have the Userfaultfd Asynchronous Write protection enabled.

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;
};
This field should be set to the size of the structure in bytes, as in sizeof(struct pm_scan_arg).
The operations to be performed are specified in it.
The starting address of the scan is specified in it.
The ending address of the scan is specified in it.
The kernel returns the scan's ending address in it. The walk_end equal to end means that scan has completed on the entire range.
The address of page_region array for output.

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

The length of the page_region struct array.
It is the optional limit for the number of output pages required.
PAGE_IS_* categories which values match if 0 instead of 1.
Skip pages for which any PAGE_IS_* category doesn't match.
Skip pages for which no PAGE_IS_* category matches.
PAGE_IS_* categories that are to be reported in page_region.

On error, -1 is returned, and errno is set to indicate the error.

Error codes can be one of, but are not limited to, the following:

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.
Invalid arg pointer, invalid vec pointer, or invalid address range specified by start and end.
No memory is available.
Fetal signal is pending.

Linux.

Linux 6.7.

ioctl(2)

2024-01-28 Linux man-pages 6.7