Debian Codegraph @

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

raw
1 .\" Copyright 2023, Collabora
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH PAGEMAP_SCAN 2const 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 PAGEMAP_SCAN
9 \-
10 get and/or clear page flags
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .BR "#include <linux/fs.h>" " /* Definition of " PAGE* " and " PM_* " constants */"
17 .B #include <sys/ioctl.h>
18 .P
19 .BI "int ioctl(int " pagemap_fd ", PAGEMAP_SCAN, struct pm_scan_arg *" arg );
20 .P
21 .B #include <linux/fs.h>
22 .P
23 .fi
24 .EX
25 .B struct pm_scan_arg {
26 .B " __u64 size;"
27 .B " __u64 flags;"
28 .B " __u64 start;"
29 .B " __u64 end;"
30 .B " __u64 walk_end;"
31 .B " __u64 vec;"
32 .B " __u64 vec_len;"
33 .B " __u64 max_pages;"
34 .B " __u64 category_inverted;"
35 .B " __u64 category_mask;"
36 .B " __u64 category_anyof_mask;"
37 .B " __u64 return_mask;"
38 .B };
39 .P
40 .B struct page_region {
41 .B " __u64 start;"
42 .B " __u64 end;"
43 .B " __u64 categories;"
44 .B };
45 .EE
46 .SH DESCRIPTION
47 This
48 .BR ioctl (2)
49 is used to get and optionally clear some specific flags from page table entries.
50 The information is returned with
51 .B PAGE_SIZE
52 granularity.
53 .P
54 To start tracking the written state (flag) of a page or range of memory,
55 the
56 .B UFFD_FEATURE_WP_ASYNC
57 must be enabled by
58 .B UFFDIO_API
59 .BR ioctl (2)
60 on
61 .B userfaultfd
62 and memory range must be registered with
63 .B UFFDIO_REGISTER
64 .BR ioctl (2)
65 in
66 .B UFFDIO_REGISTER_MODE_WP
67 mode.
68 .SS Supported page flags
69 The following page table entry flags are supported:
70 .TP
71 .B PAGE_IS_WPALLOWED
72 The page has asynchronous write-protection enabled.
73 .TP
74 .B PAGE_IS_WRITTEN
75 The page has been written to from the time it was write protected.
76 .TP
77 .B PAGE_IS_FILE
78 The page is file backed.
79 .TP
80 .B PAGE_IS_PRESENT
81 The page is present in the memory.
82 .TP
83 .B PAGE_IS_SWAPPED
84 The page is swapped.
85 .TP
86 .B PAGE_IS_PFNZERO
87 The page has zero PFN.
88 .TP
89 .B PAGE_IS_HUGE
90 The page is THP or Hugetlb backed.
91 .SS Supported operations
92 The get operation is always performed
93 if the output buffer is specified.
94 The other operations are as following:
95 .TP
96 .B PM_SCAN_WP_MATCHING
97 Write protect the matched pages.
98 .TP
99 .B PM_SCAN_CHECK_WPASYNC
100 Abort the scan
101 when a page is found
102 which doesn't have the Userfaultfd Asynchronous Write protection enabled.
103 .SS The \f[I]struct pm_scan_arg\f[] argument
104 .TP
105 .B size
106 This field should be set to the size of the structure in bytes,
107 as in
108 .IR sizeof(struct\~pm_scan_arg) .
109 .TP
110 .B flags
111 The operations to be performed are specified in it.
112 .TP
113 .B start
114 The starting address of the scan is specified in it.
115 .TP
116 .B end
117 The ending address of the scan is specified in it.
118 .TP
119 .B walk_end
120 The kernel returns the scan's ending address in it.
121 The
122 .I walk_end
123 equal to
124 .I end
125 means that scan has completed on the entire range.
126 .TP
127 .B vec
128 The address of
129 .I page_region
130 array for output.
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)