man2/userfaultfd.2

   1 .\" Copyright (c) 2016, IBM Corporation.
   2 .\" Written by Mike Rapoport <rppt@linux.vnet.ibm.com>
   3 .\" and Copyright (C) 2017 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 .TH USERFAULTFD 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  28 .SH NAME
  29 userfaultfd \- create a file descriptor for handling page faults in user space
  30 .SH SYNOPSIS
  31 .nf
  32 .BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
  33 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
  34 .B #include <unistd.h>
  35 .PP
  36 .BI "int syscall(SYS_userfaultfd, int " flags );
  37 .fi
  38 .PP
  39 .IR Note :
  40 glibc provides no wrapper for
  41 .BR userfaultfd (),
  42 necessitating the use of
  43 .BR syscall (2).
  44 .SH DESCRIPTION
  45 .BR userfaultfd ()
  46 creates a new userfaultfd object that can be used for delegation of page-fault
  47 handling to a user-space application,
  48 and returns a file descriptor that refers to the new object.
  49 The new userfaultfd object is configured using
  50 .BR ioctl (2).
  51 .PP
  52 Once the userfaultfd object is configured, the application can use
  53 .BR read (2)
  54 to receive userfaultfd notifications.
  55 The reads from userfaultfd may be blocking or non-blocking,
  56 depending on the value of
  57 .I flags
  58 used for the creation of the userfaultfd or subsequent calls to
  59 .BR fcntl (2).
  60 .PP
  61 The following values may be bitwise ORed in
  62 .IR flags
  63 to change the behavior of
  64 .BR userfaultfd ():
  65 .TP
  66 .BR O_CLOEXEC
  67 Enable the close-on-exec flag for the new userfaultfd file descriptor.
  68 See the description of the
  69 .B O_CLOEXEC
  70 flag in
  71 .BR open (2).
  72 .TP
  73 .BR O_NONBLOCK
  74 Enables non-blocking operation for the userfaultfd object.
  75 See the description of the
  76 .BR O_NONBLOCK
  77 flag in
  78 .BR open (2).
  79 .PP
  80 When the last file descriptor referring to a userfaultfd object is closed,
  81 all memory ranges that were registered with the object are unregistered
  82 and unread events are flushed.
  83 .\"
  84 .PP
  85 Userfaultfd supports two modes of registration:
  86 .TP
  87 .BR UFFDIO_REGISTER_MODE_MISSING " (since 4.10)"
  88 When registered with
  89 .B UFFDIO_REGISTER_MODE_MISSING
  90 mode, user-space will receive a page-fault notification
  91 when a missing page is accessed.
  92 The faulted thread will be stopped from execution until the page fault is
  93 resolved from user-space by either an
  94 .B UFFDIO_COPY
  95 or an
  96 .B UFFDIO_ZEROPAGE
  97 ioctl.
  98 .TP
  99 .BR UFFDIO_REGISTER_MODE_WP " (since 5.7)"
 100 When registered with
 101 .B UFFDIO_REGISTER_MODE_WP
 102 mode, user-space will receive a page-fault notification
 103 when a write-protected page is written.
 104 The faulted thread will be stopped from execution
 105 until user-space write-unprotects the page using an
 106 .B UFFDIO_WRITEPROTECT
 107 ioctl.
 108 .PP
 109 Multiple modes can be enabled at the same time for the same memory range.
 110 .PP
 111 Since Linux 4.14, a userfaultfd page-fault notification can selectively embed
 112 faulting thread ID information into the notification.
 113 One needs to enable this feature explicitly using the
 114 .B UFFD_FEATURE_THREAD_ID
 115 feature bit when initializing the userfaultfd context.
 116 By default, thread ID reporting is disabled.
 117 .SS Usage
 118 The userfaultfd mechanism is designed to allow a thread in a multithreaded
 119 program to perform user-space paging for the other threads in the process.
 120 When a page fault occurs for one of the regions registered
 121 to the userfaultfd object,
 122 the faulting thread is put to sleep and
 123 an event is generated that can be read via the userfaultfd file descriptor.
 124 The fault-handling thread reads events from this file descriptor and services
 125 them using the operations described in
 126 .BR ioctl_userfaultfd (2).
 127 When servicing the page fault events,
 128 the fault-handling thread can trigger a wake-up for the sleeping thread.
 129 .PP
 130 It is possible for the faulting threads and the fault-handling threads
 131 to run in the context of different processes.
 132 In this case, these threads may belong to different programs,
 133 and the program that executes the faulting threads
 134 will not necessarily cooperate with the program that handles the page faults.
 135 In such non-cooperative mode,
 136 the process that monitors userfaultfd and handles page faults
 137 needs to be aware of the changes in the virtual memory layout
 138 of the faulting process to avoid memory corruption.
 139 .PP
 140 Since Linux 4.11,
 141 userfaultfd can also notify the fault-handling threads about changes
 142 in the virtual memory layout of the faulting process.
 143 In addition, if the faulting process invokes
 144 .BR fork (2),
 145 the userfaultfd objects associated with the parent may be duplicated
 146 into the child process and the userfaultfd monitor will be notified
 147 (via the
 148 .B UFFD_EVENT_FORK
 149 described below)
 150 about the file descriptor associated with the userfault objects
 151 created for the child process,
 152 which allows the userfaultfd monitor to perform user-space paging
 153 for the child process.
 154 Unlike page faults which have to be synchronous and require an
 155 explicit or implicit wakeup,
 156 all other events are delivered asynchronously and
 157 the non-cooperative process resumes execution as
 158 soon as the userfaultfd manager executes
 159 .BR read (2).
 160 The userfaultfd manager should carefully synchronize calls to
 161 .B UFFDIO_COPY
 162 with the processing of events.
 163 .PP
 164 The current asynchronous model of the event delivery is optimal for
 165 single threaded non-cooperative userfaultfd manager implementations.
 166 .\" Regarding the preceding sentence, Mike Rapoport says:
 167 .\"     The major point here is that current events delivery model could be
 168 .\"     problematic for multi-threaded monitor. I even suspect that it would be
 169 .\"     impossible to ensure synchronization between page faults and non-page
 170 .\"     fault events in multi-threaded monitor.
 171 .\" .PP
 172 .\" FIXME elaborate about non-cooperating mode, describe its limitations
 173 .\" for kernels before 4.11, features added in 4.11
 174 .\" and limitations remaining in 4.11
 175 .\" Maybe it's worth adding a dedicated sub-section...
 176 .\"
 177 .PP
 178 Since Linux 5.7, userfaultfd is able to do
 179 synchronous page dirty tracking using the new write-protect register mode.
 180 One should check against the feature bit
 181 .B UFFD_FEATURE_PAGEFAULT_FLAG_WP
 182 before using this feature.
 183 Similar to the original userfaultfd missing mode, the write-protect mode will
 184 generate a userfaultfd notification when the protected page is written.
 185 The user needs to resolve the page fault by unprotecting the faulted page and
 186 kicking the faulted thread to continue.
 187 For more information,
 188 please refer to the "Userfaultfd write-protect mode" section.
 189 .\"
 190 .SS Userfaultfd operation
 191 After the userfaultfd object is created with
 192 .BR userfaultfd (),
 193 the application must enable it using the
 194 .B UFFDIO_API
 195 .BR ioctl (2)
 196 operation.
 197 This operation allows a handshake between the kernel and user space
 198 to determine the API version and supported features.
 199 This operation must be performed before any of the other
 200 .BR ioctl (2)
 201 operations described below (or those operations fail with the
 202 .BR EINVAL
 203 error).
 204 .PP
 205 After a successful
 206 .B UFFDIO_API
 207 operation,
 208 the application then registers memory address ranges using the
 209 .B UFFDIO_REGISTER
 210 .BR ioctl (2)
 211 operation.
 212 After successful completion of a
 213 .B UFFDIO_REGISTER
 214 operation,
 215 a page fault occurring in the requested memory range, and satisfying
 216 the mode defined at the registration time, will be forwarded by the kernel to
 217 the user-space application.
 218 The application can then use the
 219 .B UFFDIO_COPY
 220 or
 221 .B UFFDIO_ZEROPAGE
 222 .BR ioctl (2)
 223 operations to resolve the page fault.
 224 .PP
 225 Since Linux 4.14, if the application sets the
 226 .B UFFD_FEATURE_SIGBUS
 227 feature bit using the
 228 .B UFFDIO_API
 229 .BR ioctl (2),
 230 no page-fault notification will be forwarded to user space.
 231 Instead a
 232 .B SIGBUS
 233 signal is delivered to the faulting process.
 234 With this feature,
 235 userfaultfd can be used for robustness purposes to simply catch
 236 any access to areas within the registered address range that do not
 237 have pages allocated, without having to listen to userfaultfd events.
 238 No userfaultfd monitor will be required for dealing with such memory
 239 accesses.
 240 For example, this feature can be useful for applications that
 241 want to prevent the kernel from automatically allocating pages and filling
 242 holes in sparse files when the hole is accessed through a memory mapping.
 243 .PP
 244 The
 245 .B UFFD_FEATURE_SIGBUS
 246 feature is implicitly inherited through
 247 .BR fork (2)
 248 if used in combination with
 249 .BR UFFD_FEATURE_FORK .
 250 .PP
 251 Details of the various
 252 .BR ioctl (2)
 253 operations can be found in
 254 .BR ioctl_userfaultfd (2).
 255 .PP
 256 Since Linux 4.11, events other than page-fault may enabled during
 257 .B UFFDIO_API
 258 operation.
 259 .PP
 260 Up to Linux 4.11,
 261 userfaultfd can be used only with anonymous private memory mappings.
 262 Since Linux 4.11,
 263 userfaultfd can be also used with hugetlbfs and shared memory mappings.
 264 .\"
 265 .SS Userfaultfd write-protect mode (since 5.7)
 266 Since Linux 5.7, userfaultfd supports write-protect mode.
 267 The user needs to first check availability of this feature using
 268 .B UFFDIO_API
 269 ioctl against the feature bit
 270 .B UFFD_FEATURE_PAGEFAULT_FLAG_WP
 271 before using this feature.
 272 .PP
 273 To register with userfaultfd write-protect mode, the user needs to initiate the
 274 .B UFFDIO_REGISTER
 275 ioctl with mode
 276 .B UFFDIO_REGISTER_MODE_WP
 277 set.
 278 Note that it is legal to monitor the same memory range with multiple modes.
 279 For example, the user can do
 280 .B UFFDIO_REGISTER
 281 with the mode set to
 282 .BR "UFFDIO_REGISTER_MODE_MISSING | UFFDIO_REGISTER_MODE_WP" .
 283 When there is only
 284 .B UFFDIO_REGISTER_MODE_WP
 285 registered, user-space will
 286 .I not
 287 receive any notification when a missing page is written.
 288 Instead, user-space will receive a write-protect page-fault notification
 289 only when an existing but write-protected page got written.
 290 .PP
 291 After the
 292 .B UFFDIO_REGISTER
 293 ioctl completed with
 294 .B UFFDIO_REGISTER_MODE_WP
 295 mode set,
 296 the user can write-protect any existing memory within the range using the ioctl
 297 .B UFFDIO_WRITEPROTECT
 298 where
 299 .I uffdio_writeprotect.mode
 300 should be set to
 301 .BR UFFDIO_WRITEPROTECT_MODE_WP .
 302 .PP
 303 When a write-protect event happens,
 304 user-space will receive a page-fault notification whose
 305 .I uffd_msg.pagefault.flags
 306 will be with
 307 .B UFFD_PAGEFAULT_FLAG_WP
 308 flag set.
 309 Note: since only writes can trigger this kind of fault,
 310 write-protect notifications will always have the
 311 .B UFFD_PAGEFAULT_FLAG_WRITE
 312 bit set along with the
 313 .BR UFFD_PAGEFAULT_FLAG_WP
 314 bit.
 315 .PP
 316 To resolve a write-protection page fault, the user should initiate another
 317 .B UFFDIO_WRITEPROTECT
 318 ioctl, whose
 319 .I uffd_msg.pagefault.flags
 320 should have the flag
 321 .B UFFDIO_WRITEPROTECT_MODE_WP
 322 cleared upon the faulted page or range.
 323 .PP
 324 Write-protect mode supports only private anonymous memory.
 325 .SS Reading from the userfaultfd structure
 326 Each
 327 .BR read (2)
 328 from the userfaultfd file descriptor returns one or more
 329 .I uffd_msg
 330 structures, each of which describes a page-fault event
 331 or an event required for the non-cooperative userfaultfd usage:
 332 .PP
 333 .in +4n
 334 .EX
 335 struct uffd_msg {
 336     __u8  event;            /* Type of event */
 337     ...
 338     union {
 339         struct {
 340             __u64 flags;    /* Flags describing fault */
 341             __u64 address;  /* Faulting address */
 342             union {
 343                 __u32 ptid; /* Thread ID of the fault */
 344             } feat;
 345         } pagefault;
 346
 347         struct {            /* Since Linux 4.11 */
 348             __u32 ufd;      /* Userfault file descriptor
 349                                of the child process */
 350         } fork;
 351
 352         struct {            /* Since Linux 4.11 */
 353             __u64 from;     /* Old address of remapped area */
 354             __u64 to;       /* New address of remapped area */
 355             __u64 len;      /* Original mapping length */
 356         } remap;
 357
 358         struct {            /* Since Linux 4.11 */
 359             __u64 start;    /* Start address of removed area */
 360             __u64 end;      /* End address of removed area */
 361         } remove;
 362         ...
 363     } arg;
 364
 365     /* Padding fields omitted */
 366 } __packed;
 367 .EE
 368 .in
 369 .PP
 370 If multiple events are available and the supplied buffer is large enough,
 371 .BR read (2)
 372 returns as many events as will fit in the supplied buffer.
 373 If the buffer supplied to
 374 .BR read (2)
 375 is smaller than the size of the
 376 .I uffd_msg
 377 structure, the
 378 .BR read (2)
 379 fails with the error
 380 .BR EINVAL .
 381 .PP
 382 The fields set in the
 383 .I uffd_msg
 384 structure are as follows:
 385 .TP
 386 .I event
 387 The type of event.
 388 Depending of the event type,
 389 different fields of the
 390 .I arg
 391 union represent details required for the event processing.
 392 The non-page-fault events are generated only when appropriate feature
 393 is enabled during API handshake with
 394 .B UFFDIO_API
 395 .BR ioctl (2).
 396 .IP
 397 The following values can appear in the
 398 .I event
 399 field:
 400 .RS
 401 .TP
 402 .BR UFFD_EVENT_PAGEFAULT " (since Linux 4.3)"
 403 A page-fault event.
 404 The page-fault details are available in the
 405 .I pagefault
 406 field.
 407 .TP
 408 .BR UFFD_EVENT_FORK " (since Linux 4.11)"
 409 Generated when the faulting process invokes
 410 .BR fork (2)
 411 (or
 412 .BR clone (2)
 413 without the
 414 .BR CLONE_VM
 415 flag).
 416 The event details are available in the
 417 .I fork
 418 field.
 419 .\" FIXME describe duplication of userfault file descriptor during fork
 420 .TP
 421 .BR UFFD_EVENT_REMAP " (since Linux 4.11)"
 422 Generated when the faulting process invokes
 423 .BR mremap (2).
 424 The event details are available in the
 425 .I remap
 426 field.
 427 .TP
 428 .BR UFFD_EVENT_REMOVE " (since Linux 4.11)"
 429 Generated when the faulting process invokes
 430 .BR madvise (2)
 431 with
 432 .BR MADV_DONTNEED
 433 or
 434 .BR MADV_REMOVE
 435 advice.
 436 The event details are available in the
 437 .I remove
 438 field.
 439 .TP
 440 .BR UFFD_EVENT_UNMAP " (since Linux 4.11)"
 441 Generated when the faulting process unmaps a memory range,
 442 either explicitly using
 443 .BR munmap (2)
 444 or implicitly during
 445 .BR mmap (2)
 446 or
 447 .BR mremap (2).
 448 The event details are available in the
 449 .I remove
 450 field.
 451 .RE
 452 .TP
 453 .I pagefault.address
 454 The address that triggered the page fault.
 455 .TP
 456 .I pagefault.flags
 457 A bit mask of flags that describe the event.
 458 For
 459 .BR UFFD_EVENT_PAGEFAULT ,
 460 the following flag may appear:
 461 .RS
 462 .TP
 463 .B UFFD_PAGEFAULT_FLAG_WRITE
 464 If the address is in a range that was registered with the
 465 .B UFFDIO_REGISTER_MODE_MISSING
 466 flag (see
 467 .BR ioctl_userfaultfd (2))
 468 and this flag is set, this a write fault;
 469 otherwise it is a read fault.
 470 .TP
 471 .B UFFD_PAGEFAULT_FLAG_WP
 472 If the address is in a range that was registered with the
 473 .B UFFDIO_REGISTER_MODE_WP
 474 flag, when this bit is set, it means it is a write-protect fault.
 475 Otherwise it is a page-missing fault.
 476 .RE
 477 .TP
 478 .I pagefault.feat.pid
 479 The thread ID that triggered the page fault.
 480 .TP
 481 .I fork.ufd
 482 The file descriptor associated with the userfault object
 483 created for the child created by
 484 .BR fork (2).
 485 .TP
 486 .I remap.from
 487 The original address of the memory range that was remapped using
 488 .BR mremap (2).
 489 .TP
 490 .I remap.to
 491 The new address of the memory range that was remapped using
 492 .BR mremap (2).
 493 .TP
 494 .I remap.len
 495 The original length of the memory range that was remapped using
 496 .BR mremap (2).
 497 .TP
 498 .I remove.start
 499 The start address of the memory range that was freed using
 500 .BR madvise (2)
 501 or unmapped
 502 .TP
 503 .I remove.end
 504 The end address of the memory range that was freed using
 505 .BR madvise (2)
 506 or unmapped
 507 .PP
 508 A
 509 .BR read (2)
 510 on a userfaultfd file descriptor can fail with the following errors:
 511 .TP
 512 .B EINVAL
 513 The userfaultfd object has not yet been enabled using the
 514 .BR UFFDIO_API
 515 .BR ioctl (2)
 516 operation
 517 .PP
 518 If the
 519 .B O_NONBLOCK
 520 flag is enabled in the associated open file description,
 521 the userfaultfd file descriptor can be monitored with
 522 .BR poll (2),
 523 .BR select (2),
 524 and
 525 .BR epoll (7).
 526 When events are available, the file descriptor indicates as readable.
 527 If the
 528 .B O_NONBLOCK
 529 flag is not enabled, then
 530 .BR poll (2)
 531 (always) indicates the file as having a
 532 .BR POLLERR
 533 condition, and
 534 .BR select (2)
 535 indicates the file descriptor as both readable and writable.
 536 .\" FIXME What is the reason for this seemingly odd behavior with respect
 537 .\" to the O_NONBLOCK flag? (see userfaultfd_poll() in fs/userfaultfd.c).
 538 .\" Something needs to be said about this.
 539 .SH RETURN VALUE
 540 On success,
 541 .BR userfaultfd ()
 542 returns a new file descriptor that refers to the userfaultfd object.
 543 On error, \-1 is returned, and
 544 .I errno
 545 is set to indicate the error.
 546 .SH ERRORS
 547 .TP
 548 .B EINVAL
 549 An unsupported value was specified in
 550 .IR flags .
 551 .TP
 552 .BR EMFILE
 553 The per-process limit on the number of open file descriptors has been
 554 reached
 555 .TP
 556 .B ENFILE
 557 The system-wide limit on the total number of open files has been
 558 reached.
 559 .TP
 560 .B ENOMEM
 561 Insufficient kernel memory was available.
 562 .TP
 563 .BR EPERM " (since Linux 5.2)"
 564 .\" cefdca0a86be517bc390fc4541e3674b8e7803b0
 565 The caller is not privileged (does not have the
 566 .B CAP_SYS_PTRACE
 567 capability in the initial user namespace), and
 568 .I /proc/sys/vm/unprivileged_userfaultfd
 569 has the value 0.
 570 .SH VERSIONS
 571 The
 572 .BR userfaultfd ()
 573 system call first appeared in Linux 4.3.
 574 .PP
 575 The support for hugetlbfs and shared memory areas and
 576 non-page-fault events was added in Linux 4.11
 577 .SH CONFORMING TO
 578 .BR userfaultfd ()
 579 is Linux-specific and should not be used in programs intended to be
 580 portable.
 581 .SH NOTES
 582 The userfaultfd mechanism can be used as an alternative to
 583 traditional user-space paging techniques based on the use of the
 584 .BR SIGSEGV
 585 signal and
 586 .BR mmap (2).
 587 It can also be used to implement lazy restore
 588 for checkpoint/restore mechanisms,
 589 as well as post-copy migration to allow (nearly) uninterrupted execution
 590 when transferring virtual machines and Linux containers
 591 from one host to another.
 592 .SH BUGS
 593 If the
 594 .B UFFD_FEATURE_EVENT_FORK
 595 is enabled and a system call from the
 596 .BR fork (2)
 597 family is interrupted by a signal or failed, a stale userfaultfd descriptor
 598 might be created.
 599 In this case, a spurious
 600 .B UFFD_EVENT_FORK
 601 will be delivered to the userfaultfd monitor.
 602 .SH EXAMPLES
 603 The program below demonstrates the use of the userfaultfd mechanism.
 604 The program creates two threads, one of which acts as the
 605 page-fault handler for the process, for the pages in a demand-page zero
 606 region created using
 607 .BR mmap (2).
 608 .PP
 609 The program takes one command-line argument,
 610 which is the number of pages that will be created in a mapping
 611 whose page faults will be handled via userfaultfd.
 612 After creating a userfaultfd object,
 613 the program then creates an anonymous private mapping of the specified size
 614 and registers the address range of that mapping using the
 615 .B UFFDIO_REGISTER
 616 .BR ioctl (2)
 617 operation.
 618 The program then creates a second thread that will perform the
 619 task of handling page faults.
 620 .PP
 621 The main thread then walks through the pages of the mapping fetching
 622 bytes from successive pages.
 623 Because the pages have not yet been accessed,
 624 the first access of a byte in each page will trigger a page-fault event
 625 on the userfaultfd file descriptor.
 626 .PP
 627 Each of the page-fault events is handled by the second thread,
 628 which sits in a loop processing input from the userfaultfd file descriptor.
 629 In each loop iteration, the second thread first calls
 630 .BR poll (2)
 631 to check the state of the file descriptor,
 632 and then reads an event from the file descriptor.
 633 All such events should be
 634 .B UFFD_EVENT_PAGEFAULT
 635 events,
 636 which the thread handles by copying a page of data into
 637 the faulting region using the
 638 .B UFFDIO_COPY
 639 .BR ioctl (2)
 640 operation.
 641 .PP
 642 The following is an example of what we see when running the program:
 643 .PP
 644 .in +4n
 645 .EX
 646 $ \fB./userfaultfd_demo 3\fP
 647 Address returned by mmap() = 0x7fd30106c000
 648
 649 fault_handler_thread():
 650     poll() returns: nready = 1; POLLIN = 1; POLLERR = 0
 651     UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106c00f
 652         (uffdio_copy.copy returned 4096)
 653 Read address 0x7fd30106c00f in main(): A
 654 Read address 0x7fd30106c40f in main(): A
 655 Read address 0x7fd30106c80f in main(): A
 656 Read address 0x7fd30106cc0f in main(): A
 657
 658 fault_handler_thread():
 659     poll() returns: nready = 1; POLLIN = 1; POLLERR = 0
 660     UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106d00f
 661         (uffdio_copy.copy returned 4096)
 662 Read address 0x7fd30106d00f in main(): B
 663 Read address 0x7fd30106d40f in main(): B
 664 Read address 0x7fd30106d80f in main(): B
 665 Read address 0x7fd30106dc0f in main(): B
 666
 667 fault_handler_thread():
 668     poll() returns: nready = 1; POLLIN = 1; POLLERR = 0
 669     UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106e00f
 670         (uffdio_copy.copy returned 4096)
 671 Read address 0x7fd30106e00f in main(): C
 672 Read address 0x7fd30106e40f in main(): C
 673 Read address 0x7fd30106e80f in main(): C
 674 Read address 0x7fd30106ec0f in main(): C
 675 .EE
 676 .in
 677 .SS Program source
 678 \&
 679 .EX
 680 /* userfaultfd_demo.c
 681
 682    Licensed under the GNU General Public License version 2 or later.
 683 */
 684 #define _GNU_SOURCE
 685 #include <inttypes.h>
 686 #include <sys/types.h>
 687 #include <stdio.h>
 688 #include <linux/userfaultfd.h>
 689 #include <pthread.h>
 690 #include <errno.h>
 691 #include <unistd.h>
 692 #include <stdlib.h>
 693 #include <fcntl.h>
 694 #include <signal.h>
 695 #include <poll.h>
 696 #include <string.h>
 697 #include <sys/mman.h>
 698 #include <sys/syscall.h>
 699 #include <sys/ioctl.h>
 700 #include <poll.h>
 701
 702 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 703                         } while (0)
 704
 705 static int page_size;
 706
 707 static void *
 708 fault_handler_thread(void *arg)
 709 {
 710     static struct uffd_msg msg;   /* Data read from userfaultfd */
 711     static int fault_cnt = 0;     /* Number of faults so far handled */
 712     long uffd;                    /* userfaultfd file descriptor */
 713     static char *page = NULL;
 714     struct uffdio_copy uffdio_copy;
 715     ssize_t nread;
 716
 717     uffd = (long) arg;
 718
 719     /* Create a page that will be copied into the faulting region. */
 720
 721     if (page == NULL) {
 722         page = mmap(NULL, page_size, PROT_READ | PROT_WRITE,
 723                     MAP_PRIVATE | MAP_ANONYMOUS, \-1, 0);
 724         if (page == MAP_FAILED)
 725             errExit("mmap");
 726     }
 727
 728     /* Loop, handling incoming events on the userfaultfd
 729        file descriptor. */
 730
 731     for (;;) {
 732
 733         /* See what poll() tells us about the userfaultfd. */
 734
 735         struct pollfd pollfd;
 736         int nready;
 737         pollfd.fd = uffd;
 738         pollfd.events = POLLIN;
 739         nready = poll(&pollfd, 1, \-1);
 740         if (nready == \-1)
 741             errExit("poll");
 742
 743         printf("\enfault_handler_thread():\en");
 744         printf("    poll() returns: nready = %d; "
 745                 "POLLIN = %d; POLLERR = %d\en", nready,
 746                 (pollfd.revents & POLLIN) != 0,
 747                 (pollfd.revents & POLLERR) != 0);
 748
 749         /* Read an event from the userfaultfd. */
 750
 751         nread = read(uffd, &msg, sizeof(msg));
 752         if (nread == 0) {
 753             printf("EOF on userfaultfd!\en");
 754             exit(EXIT_FAILURE);
 755         }
 756
 757         if (nread == \-1)
 758             errExit("read");
 759
 760         /* We expect only one kind of event; verify that assumption. */
 761
 762         if (msg.event != UFFD_EVENT_PAGEFAULT) {
 763             fprintf(stderr, "Unexpected event on userfaultfd\en");
 764             exit(EXIT_FAILURE);
 765         }
 766
 767         /* Display info about the page\-fault event. */
 768
 769         printf("    UFFD_EVENT_PAGEFAULT event: ");
 770         printf("flags = %"PRIx64"; ", msg.arg.pagefault.flags);
 771         printf("address = %"PRIx64"\en", msg.arg.pagefault.address);
 772
 773         /* Copy the page pointed to by \(aqpage\(aq into the faulting
 774            region. Vary the contents that are copied in, so that it
 775            is more obvious that each fault is handled separately. */
 776
 777         memset(page, \(aqA\(aq + fault_cnt % 20, page_size);
 778         fault_cnt++;
 779
 780         uffdio_copy.src = (unsigned long) page;
 781
 782         /* We need to handle page faults in units of pages(!).
 783            So, round faulting address down to page boundary. */
 784
 785         uffdio_copy.dst = (unsigned long) msg.arg.pagefault.address &
 786                                            \(ti(page_size \- 1);
 787         uffdio_copy.len = page_size;
 788         uffdio_copy.mode = 0;
 789         uffdio_copy.copy = 0;
 790         if (ioctl(uffd, UFFDIO_COPY, &uffdio_copy) == \-1)
 791             errExit("ioctl\-UFFDIO_COPY");
 792
 793         printf("        (uffdio_copy.copy returned %"PRId64")\en",
 794                 uffdio_copy.copy);
 795     }
 796 }
 797
 798 int
 799 main(int argc, char *argv[])
 800 {
 801     long uffd;          /* userfaultfd file descriptor */
 802     char *addr;         /* Start of region handled by userfaultfd */
 803     uint64_t len;       /* Length of region handled by userfaultfd */
 804     pthread_t thr;      /* ID of thread that handles page faults */
 805     struct uffdio_api uffdio_api;
 806     struct uffdio_register uffdio_register;
 807     int s;
 808
 809     if (argc != 2) {
 810         fprintf(stderr, "Usage: %s num\-pages\en", argv[0]);
 811         exit(EXIT_FAILURE);
 812     }
 813
 814     page_size = sysconf(_SC_PAGE_SIZE);
 815     len = strtoull(argv[1], NULL, 0) * page_size;
 816
 817     /* Create and enable userfaultfd object. */
 818
 819     uffd = syscall(__NR_userfaultfd, O_CLOEXEC | O_NONBLOCK);
 820     if (uffd == \-1)
 821         errExit("userfaultfd");
 822
 823     uffdio_api.api = UFFD_API;
 824     uffdio_api.features = 0;
 825     if (ioctl(uffd, UFFDIO_API, &uffdio_api) == \-1)
 826         errExit("ioctl\-UFFDIO_API");
 827
 828     /* Create a private anonymous mapping. The memory will be
 829        demand\-zero paged\-\-that is, not yet allocated. When we
 830        actually touch the memory, it will be allocated via
 831        the userfaultfd. */
 832
 833     addr = mmap(NULL, len, PROT_READ | PROT_WRITE,
 834                 MAP_PRIVATE | MAP_ANONYMOUS, \-1, 0);
 835     if (addr == MAP_FAILED)
 836         errExit("mmap");
 837
 838     printf("Address returned by mmap() = %p\en", addr);
 839
 840     /* Register the memory range of the mapping we just created for
 841        handling by the userfaultfd object. In mode, we request to track
 842        missing pages (i.e., pages that have not yet been faulted in). */
 843
 844     uffdio_register.range.start = (unsigned long) addr;
 845     uffdio_register.range.len = len;
 846     uffdio_register.mode = UFFDIO_REGISTER_MODE_MISSING;
 847     if (ioctl(uffd, UFFDIO_REGISTER, &uffdio_register) == \-1)
 848         errExit("ioctl\-UFFDIO_REGISTER");
 849
 850     /* Create a thread that will process the userfaultfd events. */
 851
 852     s = pthread_create(&thr, NULL, fault_handler_thread, (void *) uffd);
 853     if (s != 0) {
 854         errno = s;
 855         errExit("pthread_create");
 856     }
 857
 858     /* Main thread now touches memory in the mapping, touching
 859        locations 1024 bytes apart. This will trigger userfaultfd
 860        events for all pages in the region. */
 861
 862     int l;
 863     l = 0xf;    /* Ensure that faulting address is not on a page
 864                    boundary, in order to test that we correctly
 865                    handle that case in fault_handling_thread(). */
 866     while (l < len) {
 867         char c = addr[l];
 868         printf("Read address %p in main(): ", addr + l);
 869         printf("%c\en", c);
 870         l += 1024;
 871         usleep(100000);         /* Slow things down a little */
 872     }
 873
 874     exit(EXIT_SUCCESS);
 875 }
 876 .EE
 877 .SH SEE ALSO
 878 .BR fcntl (2),
 879 .BR ioctl (2),
 880 .BR ioctl_userfaultfd (2),
 881 .BR madvise (2),
 882 .BR mmap (2)
 883 .PP
 884 .IR Documentation/admin\-guide/mm/userfaultfd.rst
 885 in the Linux kernel source tree