man2/ioctl_userfaultfd.2

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