Signed-off-by: Muhammad Usama Anjum <usama.anjum@xxxxxxxxxxxxx>
---
man2/ioctl_pagemap_scan.2 | 183 ++++++++++++++++++++++++++++++++++++++
1 file changed, 183 insertions(+)
create mode 100644 man2/ioctl_pagemap_scan.2
diff --git a/man2/ioctl_pagemap_scan.2 b/man2/ioctl_pagemap_scan.2
new file mode 100644
index 000000000..4e096028d
--- /dev/null
+++ b/man2/ioctl_pagemap_scan.2
@@ -0,0 +1,183 @@
+.\" This manpage is Copyright (C) 2023 Collabora;
+.\" Written by Muhammad Usama Anjum <usama.anjum@xxxxxxxxxxxxx>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Commit 84ceddb3c2b0c280936f28f450d65f46cb7411c6
+.\"
+.TH ioctl_pagemap_scan 2 2023-10-17 "Linux man-pages (unreleased)"
+.SH NAME
+ioctl_pagemap_scan \- get and/or clear page flags
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/fs.h>" " /* Definition of " struct " " pm_scan_arg ", " struct " " page_region " and " PAGE_IS_* " constants */"
+.B #include <sys/ioctl.h>
+.PP
+.BI "int ioctl(int " pagemap_fd ", PAGEMAP_SCAN, struct pm_scan_arg *" arg );
+.fi
+.SH DESCRIPTION
+This
+.BR ioctl (2)
+is used to get and optionally clear some specific flags from page table entries.
+
+.SS Supported page flags
+The following page table entry flags are support:
+.TP
+.BR PAGE_IS_WPALLOWED
+Page has async-write-protection enabled
+.TP
+.BR PAGE_IS_WRITTEN
+Page has been written to from the time it was write protected
+.TP
+.BR PAGE_IS_FILE
+Page is file backed
+.TP
+.BR PAGE_IS_PRESENT
+Page is present in the memory
+.TP
+.BR PAGE_IS_SWAPPED
+Page is in swapped
+.TP
+.BR PAGE_IS_PFNZERO
+Page has zero PFN
+.TP
+.BR PAGE_IS_HUGE
+Page is THP or Hugetlb backed
+
+.SS Supported Operations
+The get operation is always performed if the output buffer is specified. The other operations are as following:
+.TP
+.BR PM_SCAN_WP_MATCHING
+Write protect the matched pages
+.TP
+.BR PM_SCAN_CHECK_WPASYNC
+Abort the scan when a page which isn't registered with Userfaultfd Asynchronous Write protect
+
+.SS The struct pm_scan_arg Argument
+.PP
+.in
+.EX
+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;
+};
+.EE
+.in
+
+.TP
+.BR size
+The size of
+.I arg
+is specified in it. It'll help in future if extension is make to
+.I struct pm_scan_arg
+in future.
+.TP
+.BR flags
+The operations to be performed are specified in it.
+.TP
+.BR start
+The starting address of the scan is specified in it.
+.TP
+.BR end
+The ending address of the scan is specified in it.
+.TP
+.BR walk_end
+The kernel returns the scan's ending address in it. The
+.IR walk_end
+equal to
+.IR end
+means that scan has completed on the entire range.
+.TP
+.BR vec
+The address of
+.IR page_region
+array for output
+.PP
+.in +8n
+.EX
+struct page_region {
+ __u64 start;
+ __u64 end;
+ __u64 categories;
+};
+.EE
+.in
+.TP
+.BR vec_len
+The length of the
+.IR page_region
+struct array
+.TP
+.BR max_pages
+Optional limit for number of output pages
+.TP
+.BR category_inverted
+PAGE_IS_* categories which values match if 0 instead of 1
+.TP
+.BR category_mask
+Skip pages for which any category doesn't match
+.TP
+.BR category_anyof_mask
+Skip pages for which no category matches
+.TP
+.BR return_mask
+Page categories that are to be reported in
+.IR page_region
+
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EINVAL
+Invalid arguments i.e., invalid
+.I size
+of the argument, invalid
+.I flags
+, invalid
+.I categories
+, the
+.I start
+address isn't aligned with
+.BR PAGE_SIZE
+or
+.I vec_len
+is specified when
+.I vec
+is
+.BR NULL.
+.TP
+.B EFAULT
+Invalid
+.I arg
+pointer, invalid
+.I vec
+pointer or invalid address range specified by
+.I start
+and
+.I end
+.TP
+.B ENOMEM
+No memory is available
+.TP
+.B EINTR
+Fetal signal pending
+.SH STANDARDS
+Linux.
+.SH SEE ALSO
+.BR ioctl (2)
--
2.40.1
