]>
Commit | Line | Data |
---|---|---|
f470ae64 MUA |
1 | .\" This manpage is Copyright (C) 2023 Collabora; |
2 | .\" Written by Muhammad Usama Anjum <usama.anjum@collabora.com> | |
3 | .\" | |
4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft | |
5 | .\" | |
6 | .TH ioctl_pagemap_scan 2 2023-10-17 "Linux man-pages (unreleased)" | |
7 | .SH NAME | |
8 | ioctl_pagemap_scan \- get and/or clear page flags | |
9 | .SH LIBRARY | |
10 | Standard C library | |
11 | .RI ( libc ", " \-lc ) | |
12 | .SH SYNOPSIS | |
13 | .nf | |
14 | .BR "#include <linux/fs.h>" " /* Definition of " "struct pm_scan_arg" , | |
15 | .BR " struct page_region" ", and " PAGE_IS_* " constants */" | |
16 | .B #include <sys/ioctl.h> | |
c6d039a3 | 17 | .P |
f470ae64 MUA |
18 | .BI "int ioctl(int " pagemap_fd ", PAGEMAP_SCAN, struct pm_scan_arg *" arg ); |
19 | .fi | |
20 | .SH DESCRIPTION | |
21 | This | |
22 | .BR ioctl (2) | |
23 | is used to get and optionally clear some specific flags from page table entries. | |
24 | The information is returned with | |
25 | .B PAGE_SIZE | |
26 | granularity. | |
c6d039a3 | 27 | .P |
f470ae64 MUA |
28 | To start tracking the written state (flag) of a page or range of memory, |
29 | the | |
30 | .B UFFD_FEATURE_WP_ASYNC | |
31 | must be enabled by | |
32 | .B UFFDIO_API | |
33 | .BR ioctl (2) | |
34 | on | |
35 | .B userfaultfd | |
36 | and memory range must be registered with | |
37 | .B UFFDIO_REGISTER | |
38 | .BR ioctl (2) | |
39 | in | |
40 | .B UFFDIO_REGISTER_MODE_WP | |
41 | mode. | |
42 | .SS Supported page flags | |
43 | The following page table entry flags are supported: | |
44 | .TP | |
45 | .B PAGE_IS_WPALLOWED | |
46 | The page has asynchronous write-protection enabled. | |
47 | .TP | |
48 | .B PAGE_IS_WRITTEN | |
49 | The page has been written to from the time it was write protected. | |
50 | .TP | |
51 | .B PAGE_IS_FILE | |
52 | The page is file backed. | |
53 | .TP | |
54 | .B PAGE_IS_PRESENT | |
55 | The page is present in the memory. | |
56 | .TP | |
57 | .B PAGE_IS_SWAPPED | |
58 | The page is swapped. | |
59 | .TP | |
60 | .B PAGE_IS_PFNZERO | |
61 | The page has zero PFN. | |
62 | .TP | |
63 | .B PAGE_IS_HUGE | |
64 | The page is THP or Hugetlb backed. | |
65 | .SS Supported operations | |
66 | The get operation is always performed | |
67 | if the output buffer is specified. | |
68 | The other operations are as following: | |
69 | .TP | |
70 | .B PM_SCAN_WP_MATCHING | |
71 | Write protect the matched pages. | |
72 | .TP | |
73 | .B PM_SCAN_CHECK_WPASYNC | |
74 | Abort the scan | |
75 | when a page is found | |
76 | which doesn't have the Userfaultfd Asynchronous Write protection enabled. | |
77 | .SS The \f[I]struct pm_scan_arg\f[] argument | |
78 | .EX | |
79 | struct pm_scan_arg { | |
80 | __u64 size; | |
81 | __u64 flags; | |
82 | __u64 start; | |
83 | __u64 end; | |
84 | __u64 walk_end; | |
85 | __u64 vec; | |
86 | __u64 vec_len; | |
87 | __u64 max_pages | |
88 | __u64 category_inverted; | |
89 | __u64 category_mask; | |
90 | __u64 category_anyof_mask | |
91 | __u64 return_mask; | |
92 | }; | |
93 | .EE | |
94 | .TP | |
95 | .B size | |
96 | This field should be set to the size of the structure in bytes, | |
97 | as in | |
98 | .IR sizeof(struct\~pm_scan_arg) . | |
99 | .TP | |
100 | .B flags | |
101 | The operations to be performed are specified in it. | |
102 | .TP | |
103 | .B start | |
104 | The starting address of the scan is specified in it. | |
105 | .TP | |
106 | .B end | |
107 | The ending address of the scan is specified in it. | |
108 | .TP | |
109 | .B walk_end | |
110 | The kernel returns the scan's ending address in it. | |
111 | The | |
112 | .I walk_end | |
113 | equal to | |
114 | .I end | |
115 | means that scan has completed on the entire range. | |
116 | .TP | |
117 | .B vec | |
118 | The address of | |
119 | .I page_region | |
120 | array for output. | |
121 | .IP | |
122 | .in +4n | |
123 | .EX | |
124 | struct page_region { | |
125 | __u64 start; | |
126 | __u64 end; | |
127 | __u64 categories; | |
128 | }; | |
129 | .EE | |
130 | .in | |
131 | .TP | |
132 | .B vec_len | |
133 | The length of the | |
134 | .I page_region | |
135 | struct array. | |
136 | .TP | |
137 | .B max_pages | |
138 | It is the optional limit for the number of output pages required. | |
139 | .TP | |
140 | .B category_inverted | |
141 | .BI PAGE_IS_ * | |
142 | categories which values match if 0 instead of 1. | |
143 | .TP | |
144 | .B category_mask | |
145 | Skip pages for which any | |
146 | .BI PAGE_IS_ * | |
147 | category doesn't match. | |
148 | .TP | |
149 | .B category_anyof_mask | |
150 | Skip pages for which no | |
151 | .BI PAGE_IS_ * | |
152 | category matches. | |
153 | .TP | |
154 | .B return_mask | |
155 | .BI PAGE_IS_ * | |
156 | categories that are to be reported in | |
157 | .IR page_region . | |
158 | .SH RETURN VALUE | |
159 | On error, \-1 is returned, and | |
160 | .I errno | |
161 | is set to indicate the error. | |
162 | .SH ERRORS | |
163 | Error codes can be one of, but are not limited to, the following: | |
164 | .TP | |
165 | .B EINVAL | |
166 | Invalid arguments i.e., | |
167 | invalid | |
168 | .I size | |
169 | of the argument, | |
170 | invalid | |
171 | .IR flags , | |
172 | invalid | |
173 | .IR categories , | |
174 | the | |
175 | .I start | |
176 | address isn't aligned with | |
177 | .BR PAGE_SIZE , | |
178 | or | |
179 | .I vec_len | |
180 | is specified when | |
181 | .I vec | |
182 | is NULL. | |
183 | .TP | |
184 | .B EFAULT | |
185 | Invalid | |
186 | .I arg | |
187 | pointer, | |
188 | invalid | |
189 | .I vec | |
190 | pointer, | |
191 | or invalid address range specified by | |
192 | .I start | |
193 | and | |
194 | .IR end . | |
195 | .TP | |
196 | .B ENOMEM | |
197 | No memory is available. | |
198 | .TP | |
199 | .B EINTR | |
200 | Fetal signal is pending. | |
201 | .SH STANDARDS | |
202 | Linux. | |
203 | .SH HISTORY | |
204 | Linux 6.7. | |
205 | .SH SEE ALSO | |
206 | .BR ioctl (2) |