| blob | 504f61d4b0cdbb35df346b03de9883c260b32b4b |
1 .\" Copyright (c) 2016, IBM Corporation.
2 .\" Written by Mike Rapoport <rppt@linux.vnet.ibm.com>
3 .\" and Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\"
5 .\" %%%LICENSE_START(VERBATIM)
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
9 .\"
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
14 .\"
15 .\" Since the Linux kernel and libraries are constantly changing, this
16 .\" manual page may be incorrect or out-of-date. The author(s) assume no
17 .\" responsibility for errors or omissions, or for damages resulting from
18 .\" the use of the information contained herein. The author(s) may not
19 .\" have taken the same level of care in the production of this manual,
20 .\" which is licensed free of charge, as they might when working
21 .\" professionally.
22 .\"
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" %%%LICENSE_END
26 .\"
27 .\"
28 .TH IOCTL_USERFAULTFD 2 2021-03-22 "Linux" "Linux Programmer's Manual"
29 .SH NAME
30 ioctl_userfaultfd \- create a file descriptor for handling page faults in user
31 space
32 .SH SYNOPSIS
33 .nf
34 .BR "#include <linux/userfaultfd.h>" " /* Definition of " UFFD* " constants */"
35 .B #include <sys/ioctl.h>
36 .PP
37 .BI "int ioctl(int " fd ", int " cmd ", ...);"
38 .fi
39 .SH DESCRIPTION
40 Various
41 .BR ioctl (2)
42 operations can be performed on a userfaultfd object (created by a call to
43 .BR userfaultfd (2))
44 using calls of the form:
45 .PP
46 .in +4n
47 .EX
48 ioctl(fd, cmd, argp);
49 .EE
50 .in
51 In the above,
52 .I fd
53 is a file descriptor referring to a userfaultfd object,
54 .I cmd
55 is one of the commands listed below, and
56 .I argp
57 is a pointer to a data structure that is specific to
58 .IR cmd .
59 .PP
60 The various
61 .BR ioctl (2)
62 operations are described below.
63 The
64 .BR UFFDIO_API ,
65 .BR UFFDIO_REGISTER ,
66 and
67 .BR UFFDIO_UNREGISTER
68 operations are used to
69 .I configure
70 userfaultfd behavior.
71 These operations allow the caller to choose what features will be enabled and
72 what kinds of events will be delivered to the application.
73 The remaining operations are
74 .IR range
75 operations.
76 These operations enable the calling application to resolve page-fault
77 events.
78 .\"
79 .SS UFFDIO_API
80 (Since Linux 4.3.)
81 Enable operation of the userfaultfd and perform API handshake.
82 .PP
83 The
84 .I argp
85 argument is a pointer to a
86 .IR uffdio_api
87 structure, defined as:
88 .PP
89 .in +4n
90 .EX
91 struct uffdio_api {
92 __u64 api; /* Requested API version (input) */
93 __u64 features; /* Requested features (input/output) */
94 __u64 ioctls; /* Available ioctl() operations (output) */
95 };
96 .EE
97 .in
98 .PP
99 The
100 .I api
101 field denotes the API version requested by the application.
102 .PP
103 The kernel verifies that it can support the requested API version,
104 and sets the
105 .I features
106 and
107 .I ioctls
108 fields to bit masks representing all the available features and the generic
109 .BR ioctl (2)
110 operations available.
111 .PP
112 For Linux kernel versions before 4.11, the
113 .I features
114 field must be initialized to zero before the call to
115 .BR UFFDIO_API ,
116 and zero (i.e., no feature bits) is placed in the
117 .I features
118 field by the kernel upon return from
119 .BR ioctl (2).
120 .PP
121 Starting from Linux 4.11, the
122 .I features
123 field can be used to ask whether particular features are supported
124 and explicitly enable userfaultfd features that are disabled by default.
125 The kernel always reports all the available features in the
126 .I features
127 field.
128 .PP
129 To enable userfaultfd features the application should set
130 a bit corresponding to each feature it wants to enable in the
131 .I features
132 field.
133 If the kernel supports all the requested features it will enable them.
134 Otherwise it will zero out the returned
135 .I uffdio_api
136 structure and return
137 .BR EINVAL .
138 .\" FIXME add more details about feature negotiation and enablement
139 .PP
140 The following feature bits may be set:
141 .TP
142 .BR UFFD_FEATURE_EVENT_FORK " (since Linux 4.11)"
143 When this feature is enabled,
144 the userfaultfd objects associated with a parent process are duplicated
145 into the child process during
146 .BR fork (2)
147 and a
148 .B UFFD_EVENT_FORK
149 event is delivered to the userfaultfd monitor
150 .TP
151 .BR UFFD_FEATURE_EVENT_REMAP " (since Linux 4.11)"
152 If this feature is enabled,
153 when the faulting process invokes
154 .BR mremap (2),
155 the userfaultfd monitor will receive an event of type
156 .BR UFFD_EVENT_REMAP .
157 .TP
158 .BR UFFD_FEATURE_EVENT_REMOVE " (since Linux 4.11)"
159 If this feature is enabled,
160 when the faulting process calls
161 .BR madvise (2)
162 with the
163 .B MADV_DONTNEED
164 or
165 .B MADV_REMOVE
166 advice value to free a virtual memory area
167 the userfaultfd monitor will receive an event of type
168 .BR UFFD_EVENT_REMOVE .
169 .TP
170 .BR UFFD_FEATURE_EVENT_UNMAP " (since Linux 4.11)"
171 If this feature is enabled,
172 when the faulting process unmaps virtual memory either explicitly with
173 .BR munmap (2),
174 or implicitly during either
175 .BR mmap (2)
176 or
177 .BR mremap (2),
178 the userfaultfd monitor will receive an event of type
179 .BR UFFD_EVENT_UNMAP .
180 .TP
181 .BR UFFD_FEATURE_MISSING_HUGETLBFS " (since Linux 4.11)"
182 If this feature bit is set,
183 the kernel supports registering userfaultfd ranges on hugetlbfs
184 virtual memory areas
185 .TP
186 .BR UFFD_FEATURE_MISSING_SHMEM " (since Linux 4.11)"
187 If this feature bit is set,
188 the kernel supports registering userfaultfd ranges on shared memory areas.
189 This includes all kernel shared memory APIs:
190 System V shared memory,
191 .BR tmpfs (5),
192 shared mappings of
193 .IR /dev/zero ,
194 .BR mmap (2)
195 with the
196 .B MAP_SHARED
197 flag set,
198 .BR memfd_create (2),
199 and so on.
200 .TP
201 .BR UFFD_FEATURE_SIGBUS " (since Linux 4.14)"
202 .\" commit 2d6d6f5a09a96cc1fec7ed992b825e05f64cb50e
203 If this feature bit is set, no page-fault events
204 .RB ( UFFD_EVENT_PAGEFAULT )
205 will be delivered.
206 Instead, a
207 .B SIGBUS
208 signal will be sent to the faulting process.
209 Applications using this
210 feature will not require the use of a userfaultfd monitor for processing
211 memory accesses to the regions registered with userfaultfd.
212 .TP
213 .BR UFFD_FEATURE_THREAD_ID " (since Linux 4.14)"
214 If this feature bit is set,
215 .I uffd_msg.pagefault.feat.ptid
216 will be set to the faulted thread ID for each page-fault message.
217 .PP
218 The returned
219 .I ioctls
220 field can contain the following bits:
221 .\" FIXME This user-space API seems not fully polished. Why are there
222 .\" not constants defined for each of the bit-mask values listed below?
223 .TP
224 .B 1 << _UFFDIO_API
225 The
226 .B UFFDIO_API
227 operation is supported.
228 .TP
229 .B 1 << _UFFDIO_REGISTER
230 The
231 .B UFFDIO_REGISTER
232 operation is supported.
233 .TP
234 .B 1 << _UFFDIO_UNREGISTER
235 The
236 .B UFFDIO_UNREGISTER
237 operation is supported.
238 .TP
239 .B 1 << _UFFDIO_WRITEPROTECT
240 The
241 .B UFFDIO_WRITEPROTECT
242 operation is supported.
243 .PP
244 This
245 .BR ioctl (2)
246 operation returns 0 on success.
247 On error, \-1 is returned and
248 .I errno
249 is set to indicate the error.
250 Possible errors include:
251 .TP
252 .B EFAULT
253 .I argp
254 refers to an address that is outside the calling process's
255 accessible address space.
256 .TP
257 .B EINVAL
258 The userfaultfd has already been enabled by a previous
259 .BR UFFDIO_API
260 operation.
261 .TP
262 .B EINVAL
263 The API version requested in the
264 .I api
265 field is not supported by this kernel, or the
266 .I features
267 field passed to the kernel includes feature bits that are not supported
268 by the current kernel version.
269 .\" FIXME In the above error case, the returned 'uffdio_api' structure is
270 .\" zeroed out. Why is this done? This should be explained in the manual page.
271 .\"
272 .\" Mike Rapoport:
273 .\" In my understanding the uffdio_api
274 .\" structure is zeroed to allow the caller
275 .\" to distinguish the reasons for -EINVAL.
276 .\"
277 .SS UFFDIO_REGISTER
278 (Since Linux 4.3.)
279 Register a memory address range with the userfaultfd object.
280 The pages in the range must be "compatible".
281 .PP
282 Up to Linux kernel 4.11,
283 only private anonymous ranges are compatible for registering with
284 .BR UFFDIO_REGISTER .
285 .PP
286 Since Linux 4.11,
287 hugetlbfs and shared memory ranges are also compatible with
288 .BR UFFDIO_REGISTER .
289 .PP
290 The
291 .I argp
292 argument is a pointer to a
293 .I uffdio_register
294 structure, defined as:
295 .PP
296 .in +4n
297 .EX
298 struct uffdio_range {
299 __u64 start; /* Start of range */
300 __u64 len; /* Length of range (bytes) */
301 };
303 struct uffdio_register {
304 struct uffdio_range range;
305 __u64 mode; /* Desired mode of operation (input) */
306 __u64 ioctls; /* Available ioctl() operations (output) */
307 };
308 .EE
309 .in
310 .PP
311 The
312 .I range
313 field defines a memory range starting at
314 .I start
315 and continuing for
316 .I len
317 bytes that should be handled by the userfaultfd.
318 .PP
319 The
320 .I mode
321 field defines the mode of operation desired for this memory region.
322 The following values may be bitwise ORed to set the userfaultfd mode for
323 the specified range:
324 .TP
325 .B UFFDIO_REGISTER_MODE_MISSING
326 Track page faults on missing pages.
327 .TP
328 .B UFFDIO_REGISTER_MODE_WP
329 Track page faults on write-protected pages.
330 .PP
331 If the operation is successful, the kernel modifies the
332 .I ioctls
333 bit-mask field to indicate which
334 .BR ioctl (2)
335 operations are available for the specified range.
336 This returned bit mask is as for
337 .BR UFFDIO_API .
338 .PP
339 This
340 .BR ioctl (2)
341 operation returns 0 on success.
342 On error, \-1 is returned and
343 .I errno
344 is set to indicate the error.
345 Possible errors include:
346 .\" FIXME Is the following error list correct?
347 .\"
348 .TP
349 .B EBUSY
350 A mapping in the specified range is registered with another
351 userfaultfd object.
352 .TP
353 .B EFAULT
354 .I argp
355 refers to an address that is outside the calling process's
356 accessible address space.
357 .TP
358 .B EINVAL
359 An invalid or unsupported bit was specified in the
360 .I mode
361 field; or the
362 .I mode
363 field was zero.
364 .TP
365 .B EINVAL
366 There is no mapping in the specified address range.
367 .TP
368 .B EINVAL
369 .I range.start
370 or
371 .I range.len
372 is not a multiple of the system page size; or,
373 .I range.len
374 is zero; or these fields are otherwise invalid.
375 .TP
376 .B EINVAL
377 There as an incompatible mapping in the specified address range.
378 .\" Mike Rapoport:
379 .\" ENOMEM if the process is exiting and the
380 .\" mm_struct has gone by the time userfault grabs it.
381 .SS UFFDIO_UNREGISTER
382 (Since Linux 4.3.)
383 Unregister a memory address range from userfaultfd.
384 The pages in the range must be "compatible" (see the description of
385 .BR UFFDIO_REGISTER .)
386 .PP
387 The address range to unregister is specified in the
388 .IR uffdio_range
389 structure pointed to by
390 .IR argp .
391 .PP
392 This
393 .BR ioctl (2)
394 operation returns 0 on success.
395 On error, \-1 is returned and
396 .I errno
397 is set to indicate the error.
398 Possible errors include:
399 .TP
400 .B EINVAL
401 Either the
402 .I start
403 or the
404 .I len
405 field of the
406 .I ufdio_range
407 structure was not a multiple of the system page size; or the
408 .I len
409 field was zero; or these fields were otherwise invalid.
410 .TP
411 .B EINVAL
412 There as an incompatible mapping in the specified address range.
413 .TP
414 .B EINVAL
415 There was no mapping in the specified address range.
416 .\"
417 .SS UFFDIO_COPY
418 (Since Linux 4.3.)
419 Atomically copy a continuous memory chunk into the userfault registered
420 range and optionally wake up the blocked thread.
421 The source and destination addresses and the number of bytes to copy are
422 specified by the
423 .IR src ", " dst ", and " len
424 fields of the
425 .I uffdio_copy
426 structure pointed to by
427 .IR argp :
428 .PP
429 .in +4n
430 .EX
431 struct uffdio_copy {
432 __u64 dst; /* Destination of copy */
433 __u64 src; /* Source of copy */
434 __u64 len; /* Number of bytes to copy */
435 __u64 mode; /* Flags controlling behavior of copy */
436 __s64 copy; /* Number of bytes copied, or negated error */
437 };
438 .EE
439 .in
440 .PP
441 The following value may be bitwise ORed in
442 .IR mode
443 to change the behavior of the
444 .B UFFDIO_COPY
445 operation:
446 .TP
447 .B UFFDIO_COPY_MODE_DONTWAKE
448 Do not wake up the thread that waits for page-fault resolution
449 .TP
450 .B UFFDIO_COPY_MODE_WP
451 Copy the page with read-only permission.
452 This allows the user to trap the next write to the page,
453 which will block and generate another write-protect userfault message.
454 This is used only when both
455 .B UFFDIO_REGISTER_MODE_MISSING
456 and
457 .B UFFDIO_REGISTER_MODE_WP
458 modes are enabled for the registered range.
459 .PP
460 The
461 .I copy
462 field is used by the kernel to return the number of bytes
463 that was actually copied, or an error (a negated
464 .IR errno -style
465 value).
466 .\" FIXME Above: Why is the 'copy' field used to return error values?
467 .\" This should be explained in the manual page.
468 If the value returned in
469 .I copy
470 doesn't match the value that was specified in
471 .IR len ,
472 the operation fails with the error
473 .BR EAGAIN .
474 The
475 .I copy
476 field is output-only;
477 it is not read by the
478 .B UFFDIO_COPY
479 operation.
480 .PP
481 This
482 .BR ioctl (2)
483 operation returns 0 on success.
484 In this case, the entire area was copied.
485 On error, \-1 is returned and
486 .I errno
487 is set to indicate the error.
488 Possible errors include:
489 .TP
490 .B EAGAIN
491 The number of bytes copied (i.e., the value returned in the
492 .I copy
493 field)
494 does not equal the value that was specified in the
495 .I len
496 field.
497 .TP
498 .B EINVAL
499 Either
500 .I dst
501 or
502 .I len
503 was not a multiple of the system page size, or the range specified by
504 .IR src
505 and
506 .IR len
507 or
508 .IR dst
509 and
510 .IR len
511 was invalid.
512 .TP
513 .B EINVAL
514 An invalid bit was specified in the
515 .IR mode
516 field.
517 .TP
518 .BR ENOENT " (since Linux 4.11)"
519 The faulting process has changed
520 its virtual memory layout simultaneously with an outstanding
521 .B UFFDIO_COPY
522 operation.
523 .TP
524 .BR ENOSPC " (from Linux 4.11 until Linux 4.13)"
525 The faulting process has exited at the time of a
526 .B UFFDIO_COPY
527 operation.
528 .TP
529 .BR ESRCH " (since Linux 4.13)"
530 The faulting process has exited at the time of a
531 .B UFFDIO_COPY
532 operation.
533 .\"
534 .SS UFFDIO_ZEROPAGE
535 (Since Linux 4.3.)
536 Zero out a memory range registered with userfaultfd.
537 .PP
538 The requested range is specified by the
539 .I range
540 field of the
541 .I uffdio_zeropage
542 structure pointed to by
543 .IR argp :
544 .PP
545 .in +4n
546 .EX
547 struct uffdio_zeropage {
548 struct uffdio_range range;
549 __u64 mode; /* Flags controlling behavior of copy */
550 __s64 zeropage; /* Number of bytes zeroed, or negated error */
551 };
552 .EE
553 .in
554 .PP
555 The following value may be bitwise ORed in
556 .IR mode
557 to change the behavior of the
558 .B UFFDIO_ZEROPAGE
559 operation:
560 .TP
561 .B UFFDIO_ZEROPAGE_MODE_DONTWAKE
562 Do not wake up the thread that waits for page-fault resolution.
563 .PP
564 The
565 .I zeropage
566 field is used by the kernel to return the number of bytes
567 that was actually zeroed,
568 or an error in the same manner as
569 .BR UFFDIO_COPY .
570 .\" FIXME Why is the 'zeropage' field used to return error values?
571 .\" This should be explained in the manual page.
572 If the value returned in the
573 .I zeropage
574 field doesn't match the value that was specified in
575 .IR range.len ,
576 the operation fails with the error
577 .BR EAGAIN .
578 The
579 .I zeropage
580 field is output-only;
581 it is not read by the
582 .B UFFDIO_ZEROPAGE
583 operation.
584 .PP
585 This
586 .BR ioctl (2)
587 operation returns 0 on success.
588 In this case, the entire area was zeroed.
589 On error, \-1 is returned and
590 .I errno
591 is set to indicate the error.
592 Possible errors include:
593 .TP
594 .B EAGAIN
595 The number of bytes zeroed (i.e., the value returned in the
596 .I zeropage
597 field)
598 does not equal the value that was specified in the
599 .I range.len
600 field.
601 .TP
602 .B EINVAL
603 Either
604 .I range.start
605 or
606 .I range.len
607 was not a multiple of the system page size; or
608 .I range.len
609 was zero; or the range specified was invalid.
610 .TP
611 .B EINVAL
612 An invalid bit was specified in the
613 .IR mode
614 field.
615 .TP
616 .BR ESRCH " (since Linux 4.13)"
617 The faulting process has exited at the time of a
618 .B UFFDIO_ZEROPAGE
619 operation.
620 .\"
621 .SS UFFDIO_WAKE
622 (Since Linux 4.3.)
623 Wake up the thread waiting for page-fault resolution on
624 a specified memory address range.
625 .PP
626 The
627 .B UFFDIO_WAKE
628 operation is used in conjunction with
629 .BR UFFDIO_COPY
630 and
631 .BR UFFDIO_ZEROPAGE
632 operations that have the
633 .BR UFFDIO_COPY_MODE_DONTWAKE
634 or
635 .BR UFFDIO_ZEROPAGE_MODE_DONTWAKE
636 bit set in the
637 .I mode
638 field.
639 The userfault monitor can perform several
640 .BR UFFDIO_COPY
641 and
642 .BR UFFDIO_ZEROPAGE
643 operations in a batch and then explicitly wake up the faulting thread using
644 .BR UFFDIO_WAKE .
645 .PP
646 The
647 .I argp
648 argument is a pointer to a
649 .I uffdio_range
650 structure (shown above) that specifies the address range.
651 .PP
652 This
653 .BR ioctl (2)
654 operation returns 0 on success.
655 On error, \-1 is returned and
656 .I errno
657 is set to indicate the error.
658 Possible errors include:
659 .TP
660 .B EINVAL
661 The
662 .I start
663 or the
664 .I len
665 field of the
666 .I ufdio_range
667 structure was not a multiple of the system page size; or
668 .I len
669 was zero; or the specified range was otherwise invalid.
670 .SS UFFDIO_WRITEPROTECT (Since Linux 5.7)
671 Write-protect or write-unprotect a userfaultfd-registered memory range
672 registered with mode
673 .BR UFFDIO_REGISTER_MODE_WP .
674 .PP
675 The
676 .I argp
677 argument is a pointer to a
678 .I uffdio_range
679 structure as shown below:
680 .PP
681 .in +4n
682 .EX
683 struct uffdio_writeprotect {
684 struct uffdio_range range; /* Range to change write permission*/
685 __u64 mode; /* Mode to change write permission */
686 };
687 .EE
688 .in
689 .PP
690 There are two mode bits that are supported in this structure:
691 .TP
692 .B UFFDIO_WRITEPROTECT_MODE_WP
693 When this mode bit is set,
694 the ioctl will be a write-protect operation upon the memory range specified by
695 .IR range .
696 Otherwise it will be a write-unprotect operation upon the specified range,
697 which can be used to resolve a userfaultfd write-protect page fault.
698 .TP
699 .B UFFDIO_WRITEPROTECT_MODE_DONTWAKE
700 When this mode bit is set,
701 do not wake up any thread that waits for
702 page-fault resolution after the operation.
703 This can be specified only if
704 .B UFFDIO_WRITEPROTECT_MODE_WP
705 is not specified.
706 .PP
707 This
708 .BR ioctl (2)
709 operation returns 0 on success.
710 On error, \-1 is returned and
711 .I errno
712 is set to indicate the error.
713 Possible errors include:
714 .TP
715 .B EINVAL
716 The
717 .I start
718 or the
719 .I len
720 field of the
721 .I ufdio_range
722 structure was not a multiple of the system page size; or
723 .I len
724 was zero; or the specified range was otherwise invalid.
725 .TP
726 .B EAGAIN
727 The process was interrupted; retry this call.
728 .TP
729 .B ENOENT
730 The range specified in
731 .I range
732 is not valid.
733 For example, the virtual address does not exist,
734 or not registered with userfaultfd write-protect mode.
735 .TP
736 .B EFAULT
737 Encountered a generic fault during processing.
738 .SH RETURN VALUE
739 See descriptions of the individual operations, above.
740 .SH ERRORS
741 See descriptions of the individual operations, above.
742 In addition, the following general errors can occur for all of the
743 operations described above:
744 .TP
745 .B EFAULT
746 .I argp
747 does not point to a valid memory address.
748 .TP
749 .B EINVAL
750 (For all operations except
751 .BR UFFDIO_API .)
752 The userfaultfd object has not yet been enabled (via the
753 .BR UFFDIO_API
754 operation).
755 .SH CONFORMING TO
756 These
757 .BR ioctl (2)
758 operations are Linux-specific.
759 .SH BUGS
760 In order to detect available userfault features and
761 enable some subset of those features
762 the userfaultfd file descriptor must be closed after the first
763 .BR UFFDIO_API
764 operation that queries features availability and reopened before
765 the second
766 .BR UFFDIO_API
767 operation that actually enables the desired features.
768 .SH EXAMPLES
769 See
770 .BR userfaultfd (2).
771 .SH SEE ALSO
772 .BR ioctl (2),
773 .BR mmap (2),
774 .BR userfaultfd (2)
775 .PP
776 .IR Documentation/admin\-guide/mm/userfaultfd.rst
777 in the Linux kernel source tree