Debian Codegraph @

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

raw
1 .\" Copyright 2016, International Business Machines Corp.
2 .\" Copyright 2016, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH UFFDIO_API 2const 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 UFFDIO_API
10 \-
11 enable operation of the userfaultfd and perform API handshake
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .BR "#include <linux/userfaultfd.h>" " /* Definition of " UFFD* " constants */"
18 .B #include <sys/ioctl.h>
19 .P
20 .BI "int ioctl(int " fd ", UFFDIO_API, struct uffdio_api *" argp );
21 .P
22 .B #include <linux/userfaultfd.h>
23 .P
24 .fi
25 .EX
26 .B struct uffdio_api {
27 .BR " __u64 api;" " /* Requested API version (input) */"
28 .BR " __u64 features;" " /* Requested features (input/output) */"
29 .BR " __u64 ioctls;" " /* Available ioctl() operations (output) */"
30 .B };
31 .EE
32 .SH DESCRIPTION
33 Enable operation of the userfaultfd and perform API handshake.
34 .P
35 The
36 .I api
37 field denotes the API version requested by the application.
38 The kernel verifies that it can support the requested API version,
39 and sets the
40 .I features
41 and
42 .I ioctls
43 fields to bit masks representing all the available features and the generic
44 .BR ioctl (2)
45 operations available.
46 .P
47 Before Linux 4.11, the
48 .I features
49 field must be initialized to zero before the call to
50 .BR UFFDIO_API ,
51 and zero (i.e., no feature bits) is placed in the
52 .I features
53 field by the kernel upon return from
54 .BR ioctl (2).
55 .P
56 Since Linux 4.11,
57 userfaultfd supports features that need to be enabled explicitly.
58 To enable any of the features,
59 one needs to set the corresponding feature bits in
60 .I features
61 when issuing the
62 .B UFFDIO_API
63 ioctl.
64 .P
65 For historical reasons,
66 a temporary userfaultfd is needed to probe
67 what userfaultfd features the kernel supports.
68 The application needs to create a temporary userfaultfd,
69 issue an
70 .B UFFDIO_API
71 ioctl with
72 .I features
73 set to zero.
74 After the
75 .B UFFDIO_API
76 ioctl returns successfully,
77 .I features
78 should contain all the userfaultfd features that the kernel supports.
79 The temporary userfaultfd can be safely closed after the probe.
80 .P
81 If the application sets unsupported feature bits,
82 the kernel will zero out the returned
83 .I uffdio_api
84 structure and return
85 .BR EINVAL .
86 .P
87 The following feature bits may be set:
88 .TP
89 .BR UFFD_FEATURE_EVENT_FORK " (since Linux 4.11)"
90 When this feature is enabled,
91 the userfaultfd objects associated with a parent process are duplicated
92 into the child process during
93 .BR fork (2)
94 and a
95 .B UFFD_EVENT_FORK
96 event is delivered to the userfaultfd monitor
97 .TP
98 .BR UFFD_FEATURE_EVENT_REMAP " (since Linux 4.11)"
99 If this feature is enabled,
100 when the faulting process invokes
101 .BR mremap (2),
102 the userfaultfd monitor will receive an event of type
103 .BR UFFD_EVENT_REMAP .
104 .TP
105 .BR UFFD_FEATURE_EVENT_REMOVE " (since Linux 4.11)"
106 If this feature is enabled,
107 when the faulting process calls
108 .BR madvise (2)
109 with the
110 .B MADV_DONTNEED
111 or
112 .B MADV_REMOVE
113 advice value to free a virtual memory area
114 the userfaultfd monitor will receive an event of type
115 .BR UFFD_EVENT_REMOVE .
116 .TP
117 .BR UFFD_FEATURE_EVENT_UNMAP " (since Linux 4.11)"
118 If this feature is enabled,
119 when the faulting process unmaps virtual memory either explicitly with
120 .BR munmap (2),
121 or implicitly during either
122 .BR mmap (2)
123 or
124 .BR mremap (2),
125 the userfaultfd monitor will receive an event of type
126 .BR UFFD_EVENT_UNMAP .
127 .TP
128 .BR UFFD_FEATURE_MISSING_HUGETLBFS " (since Linux 4.11)"
129 If this feature bit is set,
130 the kernel supports registering userfaultfd ranges on hugetlbfs
131 virtual memory areas
132 .TP
133 .BR UFFD_FEATURE_MISSING_SHMEM " (since Linux 4.11)"
134 If this feature bit is set,
135 the kernel supports registering userfaultfd ranges on shared memory areas.
136 This includes all kernel shared memory APIs:
137 System V shared memory,
138 .BR tmpfs (5),
139 shared mappings of
140 .IR /dev/zero ,
141 .BR mmap (2)
142 with the
143 .B MAP_SHARED
144 flag set,
145 .BR memfd_create (2),
146 and so on.
147 .TP
148 .BR UFFD_FEATURE_SIGBUS " (since Linux 4.14)"
149 .\" commit 2d6d6f5a09a96cc1fec7ed992b825e05f64cb50e
150 If this feature bit is set, no page-fault events
151 .RB ( UFFD_EVENT_PAGEFAULT )
152 will be delivered.
153 Instead, a
154 .B SIGBUS
155 signal will be sent to the faulting process.
156 Applications using this
157 feature will not require the use of a userfaultfd monitor for processing
158 memory accesses to the regions registered with userfaultfd.
159 .TP
160 .BR UFFD_FEATURE_THREAD_ID " (since Linux 4.14)"
161 If this feature bit is set,
162 .I uffd_msg.pagefault.feat.ptid
163 will be set to the faulted thread ID for each page-fault message.
164 .TP
165 .BR UFFD_FEATURE_PAGEFAULT_FLAG_WP " (since Linux 5.10)"
166 If this feature bit is set,
167 userfaultfd supports write-protect faults
168 for anonymous memory.
169 (Note that shmem / hugetlbfs support
170 is indicated by a separate feature.)
171 .TP
172 .BR UFFD_FEATURE_MINOR_HUGETLBFS " (since Linux 5.13)"
173 If this feature bit is set,
174 the kernel supports registering userfaultfd ranges
175 in minor mode on hugetlbfs-backed memory areas.
176 .TP
177 .BR UFFD_FEATURE_MINOR_SHMEM " (since Linux 5.14)"
178 If this feature bit is set,
179 the kernel supports registering userfaultfd ranges
180 in minor mode on shmem-backed memory areas.
181 .TP
182 .BR UFFD_FEATURE_EXACT_ADDRESS " (since Linux 5.18)"
183 If this feature bit is set,
184 .I uffd_msg.pagefault.address
185 will be set to the exact page-fault address that was reported by the hardware,
186 and will not mask the offset within the page.
187 Note that old Linux versions might indicate the exact address as well,
188 even though the feature bit is not set.
189 .TP
190 .BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM " (since Linux 5.19)"
191 If this feature bit is set,
192 userfaultfd supports write-protect faults
193 for hugetlbfs and shmem / tmpfs memory.
194 .TP
195 .BR UFFD_FEATURE_WP_UNPOPULATED " (since Linux 6.4)"
196 If this feature bit is set,
197 the kernel will handle anonymous memory the same way as file memory,
198 by allowing the user to write-protect unpopulated page table entries.
199 .TP
200 .BR UFFD_FEATURE_POISON " (since Linux 6.6)"
201 If this feature bit is set,
202 the kernel supports resolving faults with the
203 .B UFFDIO_POISON
204 ioctl.
205 .TP
206 .BR UFFD_FEATURE_WP_ASYNC " (since Linux 6.7)"
207 If this feature bit is set,
208 the write protection faults would be asynchronously resolved
209 by the kernel.
210 .TP
211 .BR UFFD_FEATURE_MOVE " (since Linux 6.8)"
212 If this feature bit is set,
213 the kernel supports resolving faults with the
214 .B UFFDIO_MOVE
215 ioctl.
216 .P
217 The returned
218 .I argp->ioctls
219 field can contain the following bits:
220 .\" FIXME This user-space API seems not fully polished. Why are there
221 .\" not constants defined for each of the bit-mask values listed below?
222 .TP
223 .B 1 << _UFFDIO_API
224 The
225 .B UFFDIO_API
226 operation is supported.
227 .TP
228 .B 1 << _UFFDIO_REGISTER
229 The
230 .B UFFDIO_REGISTER
231 operation is supported.
232 .TP
233 .B 1 << _UFFDIO_UNREGISTER
234 The
235 .B UFFDIO_UNREGISTER
236 operation is supported.
237 .SH RETURN VALUE
238 On success,
239 0 is returned.
240 .P
241 On error, \-1 is returned and
242 .I errno
243 is set to indicate the error.
244 .SH ERRORS
245 .TP
246 .B EFAULT
247 .I argp
248 refers to an address that is outside the calling process's
249 accessible address space.
250 .TP
251 .B EINVAL
252 The API version requested in the
253 .I api
254 field is not supported by this kernel, or the
255 .I features
256 field passed to the kernel includes feature bits that are not supported
257 by the current kernel version.
258 .TP
259 .B EINVAL
260 A previous
261 .B UFFDIO_API
262 call already enabled one or more features for this userfaultfd.
263 Calling
264 .B UFFDIO_API
265 twice,
266 the first time with no features set,
267 is explicitly allowed
268 as per the two-step feature detection handshake.
269 .TP
270 .B EPERM
271 The
272 .B UFFD_FEATURE_EVENT_FORK
273 feature was enabled,
274 but the calling process doesn't have the
275 .B CAP_SYS_PTRACE
276 capability.
277 .SH STANDARDS
278 Linux.
279 .SH HISTORY
280 Linux 4.3.
281 .SH CAVEATS
282 If an error occurs,
283 the kernel may zero the provided
284 .I uffdio_api
285 structure.
286 The caller should treat its contents as unspecified,
287 and reinitialize it before re-attempting another
288 .B UFFDIO_API
289 call.
290 .SH BUGS
291 In order to detect available userfault features and
292 enable some subset of those features
293 the userfaultfd file descriptor must be closed after the first
294 .B UFFDIO_API
295 operation that queries features availability and reopened before
296 the second
297 .B UFFDIO_API
298 operation that actually enables the desired features.
299 .SH EXAMPLES
300 See
301 .BR userfaultfd (2).
302 .SH SEE ALSO
303 .BR ioctl (2),
304 .BR ioctl_userfaultfd (2),
305 .BR mmap (2),
306 .BR userfaultfd (2)
307 .P
308 .I linux.git/\:Documentation/\:admin\-guide/\:mm/\:userfaultfd.rst