Debian Codegraph @

upstream/debian-trixie/man2/PAGEMAP_SCAN.2const

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