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