ioctl_pagemap_scan - Man Page
get and/or clear page flags
Library
Standard C library (libc, -lc)
Synopsis
#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);Description
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.
Supported page flags
The following page table entry flags are supported:
- PAGE_IS_WPALLOWED
The page has asynchronous write-protection enabled.
- PAGE_IS_WRITTEN
The page has been written to from the time it was write protected.
- PAGE_IS_FILE
The page is file backed.
- PAGE_IS_PRESENT
The page is present in the memory.
- 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.
Supported operations
The get operation is always performed if the output buffer is specified. The other operations are as following:
- 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.
The struct pm_scan_arg argument
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;
};- size
This field should be set to the size of the structure in bytes, as in sizeof(struct pm_scan_arg).
- 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. The walk_end equal to end means that scan has completed on the entire range.
- vec
The address of page_region array for output.
struct page_region { __u64 start; __u64 end; __u64 categories; };- vec_len
The length of the page_region struct array.
- max_pages
It is the optional limit for the number of output pages required.
- category_inverted
PAGE_IS_* categories which values match if 0 instead of 1.
- 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.
Errors
Error codes can be one of, but are not limited to, the following:
- 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.
- EFAULT
Invalid arg pointer, invalid vec pointer, or invalid address range specified by start and end.
- ENOMEM
No memory is available.
- EINTR
Fetal signal is pending.
Standards
Linux.
History
Linux 6.7.