1IOCTL_USERFAULTFD(2) Linux Programmer's Manual IOCTL_USERFAULTFD(2)
2
6 ioctl_userfaultfd - create a file descriptor for handling page faults
7 in user space
8
10 #include <linux/userfaultfd.h> /* Definition of UFFD* constants */
11 #include <sys/ioctl.h>
12 int ioctl(int fd, int cmd, ...);
14
16 Various ioctl(2) operations can be performed on a userfaultfd object
17 (created by a call to userfaultfd(2)) using calls of the form:
18 ioctl(fd, cmd, argp);
20 In the above, fd is a file descriptor referring to a userfaultfd ob‐
21 ject, cmd is one of the commands listed below, and argp is a pointer to
22 a data structure that is specific to cmd.
23 The various ioctl(2) operations are described below. The UFFDIO_API,
25 UFFDIO_REGISTER, and UFFDIO_UNREGISTER operations are used to configure
26 userfaultfd behavior. These operations allow the caller to choose what
27 features will be enabled and what kinds of events will be delivered to
28 the application. The remaining operations are range operations. These
29 operations enable the calling application to resolve page-fault events.
30 UFFDIO_API
32 (Since Linux 4.3.) Enable operation of the userfaultfd and perform API
33 handshake.
34 The argp argument is a pointer to a uffdio_api structure, defined as:
36 struct uffdio_api {
38 __u64 api; /* Requested API version (input) */
39 __u64 features; /* Requested features (input/output) */
40 __u64 ioctls; /* Available ioctl() operations (output) */
41 };
42 The api field denotes the API version requested by the application.
44 The kernel verifies that it can support the requested API version, and
46 sets the features and ioctls fields to bit masks representing all the
47 available features and the generic ioctl(2) operations available.
48 For Linux kernel versions before 4.11, the features field must be ini‐
50 tialized to zero before the call to UFFDIO_API, and zero (i.e., no fea‐
51 ture bits) is placed in the features field by the kernel upon return
52 from ioctl(2).
53 Starting from Linux 4.11, the features field can be used to ask whether
55 particular features are supported and explicitly enable userfaultfd
56 features that are disabled by default. The kernel always reports all
57 the available features in the features field.
58 To enable userfaultfd features the application should set a bit corre‐
60 sponding to each feature it wants to enable in the features field. If
61 the kernel supports all the requested features it will enable them.
62 Otherwise it will zero out the returned uffdio_api structure and return
63 EINVAL.
64 The following feature bits may be set:
66 UFFD_FEATURE_EVENT_FORK (since Linux 4.11)
68 When this feature is enabled, the userfaultfd objects associated
69 with a parent process are duplicated into the child process dur‐
70 ing fork(2) and a UFFD_EVENT_FORK event is delivered to the
71 userfaultfd monitor
72 UFFD_FEATURE_EVENT_REMAP (since Linux 4.11)
74 If this feature is enabled, when the faulting process invokes
75 mremap(2), the userfaultfd monitor will receive an event of type
76 UFFD_EVENT_REMAP.
77 UFFD_FEATURE_EVENT_REMOVE (since Linux 4.11)
79 If this feature is enabled, when the faulting process calls mad‐
80 vise(2) with the MADV_DONTNEED or MADV_REMOVE advice value to
81 free a virtual memory area the userfaultfd monitor will receive
82 an event of type UFFD_EVENT_REMOVE.
83 UFFD_FEATURE_EVENT_UNMAP (since Linux 4.11)
85 If this feature is enabled, when the faulting process unmaps
86 virtual memory either explicitly with munmap(2), or implicitly
87 during either mmap(2) or mremap(2), the userfaultfd monitor will
88 receive an event of type UFFD_EVENT_UNMAP.
89 UFFD_FEATURE_MISSING_HUGETLBFS (since Linux 4.11)
91 If this feature bit is set, the kernel supports registering
92 userfaultfd ranges on hugetlbfs virtual memory areas
93 UFFD_FEATURE_MISSING_SHMEM (since Linux 4.11)
95 If this feature bit is set, the kernel supports registering
96 userfaultfd ranges on shared memory areas. This includes all
97 kernel shared memory APIs: System V shared memory, tmpfs(5),
98 shared mappings of /dev/zero, mmap(2) with the MAP_SHARED flag
99 set, memfd_create(2), and so on.
100 UFFD_FEATURE_SIGBUS (since Linux 4.14)
102 If this feature bit is set, no page-fault events
103 (UFFD_EVENT_PAGEFAULT) will be delivered. Instead, a SIGBUS
104 signal will be sent to the faulting process. Applications using
105 this feature will not require the use of a userfaultfd monitor
106 for processing memory accesses to the regions registered with
107 userfaultfd.
108 UFFD_FEATURE_THREAD_ID (since Linux 4.14)
110 If this feature bit is set, uffd_msg.pagefault.feat.ptid will be
111 set to the faulted thread ID for each page-fault message.
112 The returned ioctls field can contain the following bits:
114 1 << _UFFDIO_API
116 The UFFDIO_API operation is supported.
117 1 << _UFFDIO_REGISTER
119 The UFFDIO_REGISTER operation is supported.
120 1 << _UFFDIO_UNREGISTER
122 The UFFDIO_UNREGISTER operation is supported.
123 1 << _UFFDIO_WRITEPROTECT
125 The UFFDIO_WRITEPROTECT operation is supported.
126 This ioctl(2) operation returns 0 on success. On error, -1 is returned
128 and errno is set to indicate the error. Possible errors include:
129 EFAULT argp refers to an address that is outside the calling process's
131 accessible address space.
132 EINVAL The userfaultfd has already been enabled by a previous UFF‐
134 DIO_API operation.
135 EINVAL The API version requested in the api field is not supported by
137 this kernel, or the features field passed to the kernel includes
138 feature bits that are not supported by the current kernel ver‐
139 sion.
140 UFFDIO_REGISTER
142 (Since Linux 4.3.) Register a memory address range with the user‐
143 faultfd object. The pages in the range must be "compatible".
144 Up to Linux kernel 4.11, only private anonymous ranges are compatible
146 for registering with UFFDIO_REGISTER.
147 Since Linux 4.11, hugetlbfs and shared memory ranges are also compati‐
149 ble with UFFDIO_REGISTER.
150 The argp argument is a pointer to a uffdio_register structure, defined
152 as:
153 struct uffdio_range {
155 __u64 start; /* Start of range */
156 __u64 len; /* Length of range (bytes) */
157 };
158 struct uffdio_register {
160 struct uffdio_range range;
161 __u64 mode; /* Desired mode of operation (input) */
162 __u64 ioctls; /* Available ioctl() operations (output) */
163 };
164 The range field defines a memory range starting at start and continuing
166 for len bytes that should be handled by the userfaultfd.
167 The mode field defines the mode of operation desired for this memory
169 region. The following values may be bitwise ORed to set the user‐
170 faultfd mode for the specified range:
171 UFFDIO_REGISTER_MODE_MISSING
173 Track page faults on missing pages.
174 UFFDIO_REGISTER_MODE_WP
176 Track page faults on write-protected pages.
177 If the operation is successful, the kernel modifies the ioctls bit-mask
179 field to indicate which ioctl(2) operations are available for the spec‐
180 ified range. This returned bit mask is as for UFFDIO_API.
181 This ioctl(2) operation returns 0 on success. On error, -1 is returned
183 and errno is set to indicate the error. Possible errors include:
184 EBUSY A mapping in the specified range is registered with another
186 userfaultfd object.
187 EFAULT argp refers to an address that is outside the calling process's
189 accessible address space.
190 EINVAL An invalid or unsupported bit was specified in the mode field;
192 or the mode field was zero.
193 EINVAL There is no mapping in the specified address range.
195 EINVAL range.start or range.len is not a multiple of the system page
197 size; or, range.len is zero; or these fields are otherwise in‐
198 valid.
199 EINVAL There as an incompatible mapping in the specified address range.
201 UFFDIO_UNREGISTER
203 (Since Linux 4.3.) Unregister a memory address range from userfaultfd.
204 The pages in the range must be "compatible" (see the description of
205 UFFDIO_REGISTER.)
206 The address range to unregister is specified in the uffdio_range struc‐
208 ture pointed to by argp.
209 This ioctl(2) operation returns 0 on success. On error, -1 is returned
211 and errno is set to indicate the error. Possible errors include:
212 EINVAL Either the start or the len field of the ufdio_range structure
214 was not a multiple of the system page size; or the len field was
215 zero; or these fields were otherwise invalid.
216 EINVAL There as an incompatible mapping in the specified address range.
218 EINVAL There was no mapping in the specified address range.
220 UFFDIO_COPY
222 (Since Linux 4.3.) Atomically copy a continuous memory chunk into the
223 userfault registered range and optionally wake up the blocked thread.
224 The source and destination addresses and the number of bytes to copy
225 are specified by the src, dst, and len fields of the uffdio_copy struc‐
226 ture pointed to by argp:
227 struct uffdio_copy {
229 __u64 dst; /* Destination of copy */
230 __u64 src; /* Source of copy */
231 __u64 len; /* Number of bytes to copy */
232 __u64 mode; /* Flags controlling behavior of copy */
233 __s64 copy; /* Number of bytes copied, or negated error */
234 };
235 The following value may be bitwise ORed in mode to change the behavior
237 of the UFFDIO_COPY operation:
238 UFFDIO_COPY_MODE_DONTWAKE
240 Do not wake up the thread that waits for page-fault resolution
241 UFFDIO_COPY_MODE_WP
243 Copy the page with read-only permission. This allows the user
244 to trap the next write to the page, which will block and gener‐
245 ate another write-protect userfault message. This is used only
246 when both UFFDIO_REGISTER_MODE_MISSING and UFFDIO_REGIS‐
247 TER_MODE_WP modes are enabled for the registered range.
248 The copy field is used by the kernel to return the number of bytes that
250 was actually copied, or an error (a negated errno-style value). If the
251 value returned in copy doesn't match the value that was specified in
252 len, the operation fails with the error EAGAIN. The copy field is out‐
253 put-only; it is not read by the UFFDIO_COPY operation.
254 This ioctl(2) operation returns 0 on success. In this case, the entire
256 area was copied. On error, -1 is returned and errno is set to indicate
257 the error. Possible errors include:
258 EAGAIN The number of bytes copied (i.e., the value returned in the copy
260 field) does not equal the value that was specified in the len
261 field.
262 EINVAL Either dst or len was not a multiple of the system page size, or
264 the range specified by src and len or dst and len was invalid.
265 EINVAL An invalid bit was specified in the mode field.
267 ENOENT (since Linux 4.11)
269 The faulting process has changed its virtual memory layout si‐
270 multaneously with an outstanding UFFDIO_COPY operation.
271 ENOSPC (from Linux 4.11 until Linux 4.13)
273 The faulting process has exited at the time of a UFFDIO_COPY op‐
274 eration.
275 ESRCH (since Linux 4.13)
277 The faulting process has exited at the time of a UFFDIO_COPY op‐
278 eration.
279 UFFDIO_ZEROPAGE
281 (Since Linux 4.3.) Zero out a memory range registered with user‐
282 faultfd.
283 The requested range is specified by the range field of the uffdio_ze‐
285 ropage structure pointed to by argp:
286 struct uffdio_zeropage {
288 struct uffdio_range range;
289 __u64 mode; /* Flags controlling behavior of copy */
290 __s64 zeropage; /* Number of bytes zeroed, or negated error */
291 };
292 The following value may be bitwise ORed in mode to change the behavior
294 of the UFFDIO_ZEROPAGE operation:
295 UFFDIO_ZEROPAGE_MODE_DONTWAKE
297 Do not wake up the thread that waits for page-fault resolution.
298 The zeropage field is used by the kernel to return the number of bytes
300 that was actually zeroed, or an error in the same manner as UFF‐
301 DIO_COPY. If the value returned in the zeropage field doesn't match
302 the value that was specified in range.len, the operation fails with the
303 error EAGAIN. The zeropage field is output-only; it is not read by the
304 UFFDIO_ZEROPAGE operation.
305 This ioctl(2) operation returns 0 on success. In this case, the entire
307 area was zeroed. On error, -1 is returned and errno is set to indicate
308 the error. Possible errors include:
309 EAGAIN The number of bytes zeroed (i.e., the value returned in the ze‐
311 ropage field) does not equal the value that was specified in the
312 range.len field.
313 EINVAL Either range.start or range.len was not a multiple of the system
315 page size; or range.len was zero; or the range specified was in‐
316 valid.
317 EINVAL An invalid bit was specified in the mode field.
319 ESRCH (since Linux 4.13)
321 The faulting process has exited at the time of a UFFDIO_ZEROPAGE
322 operation.
323 UFFDIO_WAKE
325 (Since Linux 4.3.) Wake up the thread waiting for page-fault resolu‐
326 tion on a specified memory address range.
327 The UFFDIO_WAKE operation is used in conjunction with UFFDIO_COPY and
329 UFFDIO_ZEROPAGE operations that have the UFFDIO_COPY_MODE_DONTWAKE or
330 UFFDIO_ZEROPAGE_MODE_DONTWAKE bit set in the mode field. The userfault
331 monitor can perform several UFFDIO_COPY and UFFDIO_ZEROPAGE operations
332 in a batch and then explicitly wake up the faulting thread using UFF‐
333 DIO_WAKE.
334 The argp argument is a pointer to a uffdio_range structure (shown
336 above) that specifies the address range.
337 This ioctl(2) operation returns 0 on success. On error, -1 is returned
339 and errno is set to indicate the error. Possible errors include:
340 EINVAL The start or the len field of the ufdio_range structure was not
342 a multiple of the system page size; or len was zero; or the
343 specified range was otherwise invalid.
344 UFFDIO_WRITEPROTECT (Since Linux 5.7)
346 Write-protect or write-unprotect a userfaultfd-registered memory range
347 registered with mode UFFDIO_REGISTER_MODE_WP.
348 The argp argument is a pointer to a uffdio_range structure as shown be‐
350 low:
351 struct uffdio_writeprotect {
353 struct uffdio_range range; /* Range to change write permission*/
354 __u64 mode; /* Mode to change write permission */
355 };
356 There are two mode bits that are supported in this structure:
358 UFFDIO_WRITEPROTECT_MODE_WP
360 When this mode bit is set, the ioctl will be a write-protect op‐
361 eration upon the memory range specified by range. Otherwise it
362 will be a write-unprotect operation upon the specified range,
363 which can be used to resolve a userfaultfd write-protect page
364 fault.
365 UFFDIO_WRITEPROTECT_MODE_DONTWAKE
367 When this mode bit is set, do not wake up any thread that waits
368 for page-fault resolution after the operation. This can be
369 specified only if UFFDIO_WRITEPROTECT_MODE_WP is not specified.
370 This ioctl(2) operation returns 0 on success. On error, -1 is returned
372 and errno is set to indicate the error. Possible errors include:
373 EINVAL The start or the len field of the ufdio_range structure was not
375 a multiple of the system page size; or len was zero; or the
376 specified range was otherwise invalid.
377 EAGAIN The process was interrupted; retry this call.
379 ENOENT The range specified in range is not valid. For example, the
381 virtual address does not exist, or not registered with user‐
382 faultfd write-protect mode.
383 EFAULT Encountered a generic fault during processing.
385
387 See descriptions of the individual operations, above.
388
390 See descriptions of the individual operations, above. In addition, the
391 following general errors can occur for all of the operations described
392 above:
393 EFAULT argp does not point to a valid memory address.
395 EINVAL (For all operations except UFFDIO_API.) The userfaultfd object
397 has not yet been enabled (via the UFFDIO_API operation).
398
400 These ioctl(2) operations are Linux-specific.
401
403 In order to detect available userfault features and enable some subset
404 of those features the userfaultfd file descriptor must be closed after
405 the first UFFDIO_API operation that queries features availability and
406 reopened before the second UFFDIO_API operation that actually enables
407 the desired features.
408
410 See userfaultfd(2).
411
413 ioctl(2), mmap(2), userfaultfd(2)
414 Documentation/admin-guide/mm/userfaultfd.rst in the Linux kernel source
416 tree
417
419 This page is part of release 5.13 of the Linux man-pages project. A
420 description of the project, information about reporting bugs, and the
421 latest version of this page, can be found at
422 https://www.kernel.org/doc/man-pages/.
423Linux 2021-03-22 IOCTL_USERFAULTFD(2)