summaryrefslogtreecommitdiffstats
path: root/man/man2/userfaultfd.2
diff options
context:
space:
mode:
Diffstat (limited to 'man/man2/userfaultfd.2')
-rw-r--r--man/man2/userfaultfd.2951
1 files changed, 951 insertions, 0 deletions
diff --git a/man/man2/userfaultfd.2 b/man/man2/userfaultfd.2
new file mode 100644
index 0000000..206a8ad
--- /dev/null
+++ b/man/man2/userfaultfd.2
@@ -0,0 +1,951 @@
+.\" Copyright (c) 2016, IBM Corporation.
+.\" Written by Mike Rapoport <rppt@linux.vnet.ibm.com>
+.\" and Copyright (C) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH userfaultfd 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+userfaultfd \- create a file descriptor for handling page faults in user space
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <fcntl.h>" " /* Definition of " O_* " constants */"
+.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
+.BR "#include <linux/userfaultfd.h>" " /* Definition of " UFFD_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "int syscall(SYS_userfaultfd, int " flags );
+.fi
+.P
+.IR Note :
+glibc provides no wrapper for
+.BR userfaultfd (),
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+.BR userfaultfd ()
+creates a new userfaultfd object that can be used for delegation of page-fault
+handling to a user-space application,
+and returns a file descriptor that refers to the new object.
+The new userfaultfd object is configured using
+.BR ioctl (2).
+.P
+Once the userfaultfd object is configured, the application can use
+.BR read (2)
+to receive userfaultfd notifications.
+The reads from userfaultfd may be blocking or non-blocking,
+depending on the value of
+.I flags
+used for the creation of the userfaultfd or subsequent calls to
+.BR fcntl (2).
+.P
+The following values may be bitwise ORed in
+.I flags
+to change the behavior of
+.BR userfaultfd ():
+.TP
+.B O_CLOEXEC
+Enable the close-on-exec flag for the new userfaultfd file descriptor.
+See the description of the
+.B O_CLOEXEC
+flag in
+.BR open (2).
+.TP
+.B O_NONBLOCK
+Enables non-blocking operation for the userfaultfd object.
+See the description of the
+.B O_NONBLOCK
+flag in
+.BR open (2).
+.TP
+.B UFFD_USER_MODE_ONLY
+This is an userfaultfd-specific flag that was introduced in Linux 5.11.
+When set, the userfaultfd object will only be able to handle
+page faults originated from the user space on the registered regions.
+When a kernel-originated fault was triggered
+on the registered range with this userfaultfd, a
+.B SIGBUS
+signal will be delivered.
+.P
+When the last file descriptor referring to a userfaultfd object is closed,
+all memory ranges that were registered with the object are unregistered
+and unread events are flushed.
+.\"
+.P
+Userfaultfd supports three modes of registration:
+.TP
+.BR UFFDIO_REGISTER_MODE_MISSING " (since Linux 4.10)"
+When registered with
+.B UFFDIO_REGISTER_MODE_MISSING
+mode, user-space will receive a page-fault notification
+when a missing page is accessed.
+The faulted thread will be stopped from execution until the page fault is
+resolved from user-space by either an
+.B UFFDIO_COPY
+or an
+.B UFFDIO_ZEROPAGE
+ioctl.
+.TP
+.BR UFFDIO_REGISTER_MODE_MINOR " (since Linux 5.13)"
+When registered with
+.B UFFDIO_REGISTER_MODE_MINOR
+mode, user-space will receive a page-fault notification
+when a minor page fault occurs.
+That is,
+when a backing page is in the page cache,
+but page table entries don't yet exist.
+The faulted thread will be stopped from execution
+until the page fault is resolved from user-space by an
+.B UFFDIO_CONTINUE
+ioctl.
+.TP
+.BR UFFDIO_REGISTER_MODE_WP " (since Linux 5.7)"
+When registered with
+.B UFFDIO_REGISTER_MODE_WP
+mode, user-space will receive a page-fault notification
+when a write-protected page is written.
+The faulted thread will be stopped from execution
+until user-space write-unprotects the page using an
+.B UFFDIO_WRITEPROTECT
+ioctl.
+.P
+Multiple modes can be enabled at the same time for the same memory range.
+.P
+Since Linux 4.14, a userfaultfd page-fault notification can selectively embed
+faulting thread ID information into the notification.
+One needs to enable this feature explicitly using the
+.B UFFD_FEATURE_THREAD_ID
+feature bit when initializing the userfaultfd context.
+By default, thread ID reporting is disabled.
+.SS Usage
+The userfaultfd mechanism is designed to allow a thread in a multithreaded
+program to perform user-space paging for the other threads in the process.
+When a page fault occurs for one of the regions registered
+to the userfaultfd object,
+the faulting thread is put to sleep and
+an event is generated that can be read via the userfaultfd file descriptor.
+The fault-handling thread reads events from this file descriptor and services
+them using the operations described in
+.BR ioctl_userfaultfd (2).
+When servicing the page fault events,
+the fault-handling thread can trigger a wake-up for the sleeping thread.
+.P
+It is possible for the faulting threads and the fault-handling threads
+to run in the context of different processes.
+In this case, these threads may belong to different programs,
+and the program that executes the faulting threads
+will not necessarily cooperate with the program that handles the page faults.
+In such non-cooperative mode,
+the process that monitors userfaultfd and handles page faults
+needs to be aware of the changes in the virtual memory layout
+of the faulting process to avoid memory corruption.
+.P
+Since Linux 4.11,
+userfaultfd can also notify the fault-handling threads about changes
+in the virtual memory layout of the faulting process.
+In addition, if the faulting process invokes
+.BR fork (2),
+the userfaultfd objects associated with the parent may be duplicated
+into the child process and the userfaultfd monitor will be notified
+(via the
+.B UFFD_EVENT_FORK
+described below)
+about the file descriptor associated with the userfault objects
+created for the child process,
+which allows the userfaultfd monitor to perform user-space paging
+for the child process.
+Unlike page faults which have to be synchronous and require an
+explicit or implicit wakeup,
+all other events are delivered asynchronously and
+the non-cooperative process resumes execution as
+soon as the userfaultfd manager executes
+.BR read (2).
+The userfaultfd manager should carefully synchronize calls to
+.B UFFDIO_COPY
+with the processing of events.
+.P
+The current asynchronous model of the event delivery is optimal for
+single threaded non-cooperative userfaultfd manager implementations.
+.\" Regarding the preceding sentence, Mike Rapoport says:
+.\" The major point here is that current events delivery model could be
+.\" problematic for multi-threaded monitor. I even suspect that it would be
+.\" impossible to ensure synchronization between page faults and non-page
+.\" fault events in multi-threaded monitor.
+.\" .P
+.\" FIXME elaborate about non-cooperating mode, describe its limitations
+.\" for kernels before Linux 4.11, features added in Linux 4.11
+.\" and limitations remaining in Linux 4.11
+.\" Maybe it's worth adding a dedicated sub-section...
+.\"
+.P
+Since Linux 5.7, userfaultfd is able to do
+synchronous page dirty tracking using the new write-protect register mode.
+One should check against the feature bit
+.B UFFD_FEATURE_PAGEFAULT_FLAG_WP
+before using this feature.
+Similar to the original userfaultfd missing mode, the write-protect mode will
+generate a userfaultfd notification when the protected page is written.
+The user needs to resolve the page fault by unprotecting the faulted page and
+kicking the faulted thread to continue.
+For more information,
+please refer to the "Userfaultfd write-protect mode" section.
+.\"
+.SS Userfaultfd operation
+After the userfaultfd object is created with
+.BR userfaultfd (),
+the application must enable it using the
+.B UFFDIO_API
+.BR ioctl (2)
+operation.
+This operation allows a two-step handshake between the kernel and user space
+to determine what API version and features the kernel supports,
+and then to enable those features user space wants.
+This operation must be performed before any of the other
+.BR ioctl (2)
+operations described below (or those operations fail with the
+.B EINVAL
+error).
+.P
+After a successful
+.B UFFDIO_API
+operation,
+the application then registers memory address ranges using the
+.B UFFDIO_REGISTER
+.BR ioctl (2)
+operation.
+After successful completion of a
+.B UFFDIO_REGISTER
+operation,
+a page fault occurring in the requested memory range, and satisfying
+the mode defined at the registration time, will be forwarded by the kernel to
+the user-space application.
+The application can then use various (e.g.,
+.BR UFFDIO_COPY ,
+.BR UFFDIO_ZEROPAGE ,
+or
+.BR UFFDIO_CONTINUE )
+.BR ioctl (2)
+operations to resolve the page fault.
+.P
+Since Linux 4.14, if the application sets the
+.B UFFD_FEATURE_SIGBUS
+feature bit using the
+.B UFFDIO_API
+.BR ioctl (2),
+no page-fault notification will be forwarded to user space.
+Instead a
+.B SIGBUS
+signal is delivered to the faulting process.
+With this feature,
+userfaultfd can be used for robustness purposes to simply catch
+any access to areas within the registered address range that do not
+have pages allocated, without having to listen to userfaultfd events.
+No userfaultfd monitor will be required for dealing with such memory
+accesses.
+For example, this feature can be useful for applications that
+want to prevent the kernel from automatically allocating pages and filling
+holes in sparse files when the hole is accessed through a memory mapping.
+.P
+The
+.B UFFD_FEATURE_SIGBUS
+feature is implicitly inherited through
+.BR fork (2)
+if used in combination with
+.BR UFFD_FEATURE_FORK .
+.P
+Details of the various
+.BR ioctl (2)
+operations can be found in
+.BR ioctl_userfaultfd (2).
+.P
+Since Linux 4.11, events other than page-fault may enabled during
+.B UFFDIO_API
+operation.
+.P
+Up to Linux 4.11,
+userfaultfd can be used only with anonymous private memory mappings.
+Since Linux 4.11,
+userfaultfd can be also used with hugetlbfs and shared memory mappings.
+.\"
+.SS Userfaultfd write-protect mode (since Linux 5.7)
+Since Linux 5.7, userfaultfd supports write-protect mode for anonymous memory.
+The user needs to first check availability of this feature using
+.B UFFDIO_API
+ioctl against the feature bit
+.B UFFD_FEATURE_PAGEFAULT_FLAG_WP
+before using this feature.
+.P
+Since Linux 5.19,
+the write-protection mode was also supported on
+shmem and hugetlbfs memory types.
+It can be detected with the feature bit
+.BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM .
+.P
+To register with userfaultfd write-protect mode, the user needs to initiate the
+.B UFFDIO_REGISTER
+ioctl with mode
+.B UFFDIO_REGISTER_MODE_WP
+set.
+Note that it is legal to monitor the same memory range with multiple modes.
+For example, the user can do
+.B UFFDIO_REGISTER
+with the mode set to
+.BR "UFFDIO_REGISTER_MODE_MISSING | UFFDIO_REGISTER_MODE_WP" .
+When there is only
+.B UFFDIO_REGISTER_MODE_WP
+registered, user-space will
+.I not
+receive any notification when a missing page is written.
+Instead, user-space will receive a write-protect page-fault notification
+only when an existing but write-protected page got written.
+.P
+After the
+.B UFFDIO_REGISTER
+ioctl completed with
+.B UFFDIO_REGISTER_MODE_WP
+mode set,
+the user can write-protect any existing memory within the range using the ioctl
+.B UFFDIO_WRITEPROTECT
+where
+.I uffdio_writeprotect.mode
+should be set to
+.BR UFFDIO_WRITEPROTECT_MODE_WP .
+.P
+When a write-protect event happens,
+user-space will receive a page-fault notification whose
+.I uffd_msg.pagefault.flags
+will be with
+.B UFFD_PAGEFAULT_FLAG_WP
+flag set.
+Note: since only writes can trigger this kind of fault,
+write-protect notifications will always have the
+.B UFFD_PAGEFAULT_FLAG_WRITE
+bit set along with the
+.B UFFD_PAGEFAULT_FLAG_WP
+bit.
+.P
+To resolve a write-protection page fault, the user should initiate another
+.B UFFDIO_WRITEPROTECT
+ioctl, whose
+.I uffd_msg.pagefault.flags
+should have the flag
+.B UFFDIO_WRITEPROTECT_MODE_WP
+cleared upon the faulted page or range.
+.\"
+.SS Userfaultfd minor fault mode (since Linux 5.13)
+Since Linux 5.13,
+userfaultfd supports minor fault mode.
+In this mode,
+fault messages are produced not for major faults
+(where the page was missing),
+but rather for minor faults,
+where a page exists in the page cache,
+but the page table entries are not yet present.
+The user needs to first check availability of this feature using the
+.B UFFDIO_API
+ioctl with the appropriate feature bits set before using this feature:
+.B UFFD_FEATURE_MINOR_HUGETLBFS
+since Linux 5.13,
+or
+.B UFFD_FEATURE_MINOR_SHMEM
+since Linux 5.14.
+.P
+To register with userfaultfd minor fault mode,
+the user needs to initiate the
+.B UFFDIO_REGISTER
+ioctl with mode
+.B UFFD_REGISTER_MODE_MINOR
+set.
+.P
+When a minor fault occurs,
+user-space will receive a page-fault notification
+whose
+.I uffd_msg.pagefault.flags
+will have the
+.B UFFD_PAGEFAULT_FLAG_MINOR
+flag set.
+.P
+To resolve a minor page fault,
+the handler should decide whether or not
+the existing page contents need to be modified first.
+If so,
+this should be done in-place via a second,
+non-userfaultfd-registered mapping
+to the same backing page
+(e.g., by mapping the shmem or hugetlbfs file twice).
+Once the page is considered "up to date",
+the fault can be resolved by initiating an
+.B UFFDIO_CONTINUE
+ioctl,
+which installs the page table entries and
+(by default)
+wakes up the faulting thread(s).
+.P
+Minor fault mode supports only hugetlbfs-backed (since Linux 5.13)
+and shmem-backed (since Linux 5.14) memory.
+.\"
+.SS Reading from the userfaultfd structure
+Each
+.BR read (2)
+from the userfaultfd file descriptor returns one or more
+.I uffd_msg
+structures, each of which describes a page-fault event
+or an event required for the non-cooperative userfaultfd usage:
+.P
+.in +4n
+.EX
+struct uffd_msg {
+ __u8 event; /* Type of event */
+ ...
+ union {
+ struct {
+ __u64 flags; /* Flags describing fault */
+ __u64 address; /* Faulting address */
+ union {
+ __u32 ptid; /* Thread ID of the fault */
+ } feat;
+ } pagefault;
+\&
+ struct { /* Since Linux 4.11 */
+ __u32 ufd; /* Userfault file descriptor
+ of the child process */
+ } fork;
+\&
+ struct { /* Since Linux 4.11 */
+ __u64 from; /* Old address of remapped area */
+ __u64 to; /* New address of remapped area */
+ __u64 len; /* Original mapping length */
+ } remap;
+\&
+ struct { /* Since Linux 4.11 */
+ __u64 start; /* Start address of removed area */
+ __u64 end; /* End address of removed area */
+ } remove;
+ ...
+ } arg;
+\&
+ /* Padding fields omitted */
+} __packed;
+.EE
+.in
+.P
+If multiple events are available and the supplied buffer is large enough,
+.BR read (2)
+returns as many events as will fit in the supplied buffer.
+If the buffer supplied to
+.BR read (2)
+is smaller than the size of the
+.I uffd_msg
+structure, the
+.BR read (2)
+fails with the error
+.BR EINVAL .
+.P
+The fields set in the
+.I uffd_msg
+structure are as follows:
+.TP
+.I event
+The type of event.
+Depending of the event type,
+different fields of the
+.I arg
+union represent details required for the event processing.
+The non-page-fault events are generated only when appropriate feature
+is enabled during API handshake with
+.B UFFDIO_API
+.BR ioctl (2).
+.IP
+The following values can appear in the
+.I event
+field:
+.RS
+.TP
+.BR UFFD_EVENT_PAGEFAULT " (since Linux 4.3)"
+A page-fault event.
+The page-fault details are available in the
+.I pagefault
+field.
+.TP
+.BR UFFD_EVENT_FORK " (since Linux 4.11)"
+Generated when the faulting process invokes
+.BR fork (2)
+(or
+.BR clone (2)
+without the
+.B CLONE_VM
+flag).
+The event details are available in the
+.I fork
+field.
+.\" FIXME describe duplication of userfault file descriptor during fork
+.TP
+.BR UFFD_EVENT_REMAP " (since Linux 4.11)"
+Generated when the faulting process invokes
+.BR mremap (2).
+The event details are available in the
+.I remap
+field.
+.TP
+.BR UFFD_EVENT_REMOVE " (since Linux 4.11)"
+Generated when the faulting process invokes
+.BR madvise (2)
+with
+.B MADV_DONTNEED
+or
+.B MADV_REMOVE
+advice.
+The event details are available in the
+.I remove
+field.
+.TP
+.BR UFFD_EVENT_UNMAP " (since Linux 4.11)"
+Generated when the faulting process unmaps a memory range,
+either explicitly using
+.BR munmap (2)
+or implicitly during
+.BR mmap (2)
+or
+.BR mremap (2).
+The event details are available in the
+.I remove
+field.
+.RE
+.TP
+.I pagefault.address
+The address that triggered the page fault.
+.TP
+.I pagefault.flags
+A bit mask of flags that describe the event.
+For
+.BR UFFD_EVENT_PAGEFAULT ,
+the following flag may appear:
+.RS
+.TP
+.B UFFD_PAGEFAULT_FLAG_WP
+If this flag is set, then the fault was a write-protect fault.
+.TP
+.B UFFD_PAGEFAULT_FLAG_MINOR
+If this flag is set, then the fault was a minor fault.
+.TP
+.B UFFD_PAGEFAULT_FLAG_WRITE
+If this flag is set, then the fault was a write fault.
+.P
+If neither
+.B UFFD_PAGEFAULT_FLAG_WP
+nor
+.B UFFD_PAGEFAULT_FLAG_MINOR
+are set, then the fault was a missing fault.
+.RE
+.TP
+.I pagefault.feat.pid
+The thread ID that triggered the page fault.
+.TP
+.I fork.ufd
+The file descriptor associated with the userfault object
+created for the child created by
+.BR fork (2).
+.TP
+.I remap.from
+The original address of the memory range that was remapped using
+.BR mremap (2).
+.TP
+.I remap.to
+The new address of the memory range that was remapped using
+.BR mremap (2).
+.TP
+.I remap.len
+The original length of the memory range that was remapped using
+.BR mremap (2).
+.TP
+.I remove.start
+The start address of the memory range that was freed using
+.BR madvise (2)
+or unmapped
+.TP
+.I remove.end
+The end address of the memory range that was freed using
+.BR madvise (2)
+or unmapped
+.P
+A
+.BR read (2)
+on a userfaultfd file descriptor can fail with the following errors:
+.TP
+.B EINVAL
+The userfaultfd object has not yet been enabled using the
+.B UFFDIO_API
+.BR ioctl (2)
+operation
+.P
+If the
+.B O_NONBLOCK
+flag is enabled in the associated open file description,
+the userfaultfd file descriptor can be monitored with
+.BR poll (2),
+.BR select (2),
+and
+.BR epoll (7).
+When events are available, the file descriptor indicates as readable.
+If the
+.B O_NONBLOCK
+flag is not enabled, then
+.BR poll (2)
+(always) indicates the file as having a
+.B POLLERR
+condition, and
+.BR select (2)
+indicates the file descriptor as both readable and writable.
+.\" FIXME What is the reason for this seemingly odd behavior with respect
+.\" to the O_NONBLOCK flag? (see userfaultfd_poll() in fs/userfaultfd.c).
+.\" Something needs to be said about this.
+.SH RETURN VALUE
+On success,
+.BR userfaultfd ()
+returns a new file descriptor that refers to the userfaultfd object.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+An unsupported value was specified in
+.IR flags .
+.TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been
+reached
+.TP
+.B ENFILE
+The system-wide limit on the total number of open files has been
+reached.
+.TP
+.B ENOMEM
+Insufficient kernel memory was available.
+.TP
+.BR EPERM " (since Linux 5.2)"
+.\" cefdca0a86be517bc390fc4541e3674b8e7803b0
+The caller is not privileged (does not have the
+.B CAP_SYS_PTRACE
+capability in the initial user namespace), and
+.I /proc/sys/vm/unprivileged_userfaultfd
+has the value 0.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 4.3.
+.P
+Support for hugetlbfs and shared memory areas and
+non-page-fault events was added in Linux 4.11
+.SH NOTES
+The userfaultfd mechanism can be used as an alternative to
+traditional user-space paging techniques based on the use of the
+.B SIGSEGV
+signal and
+.BR mmap (2).
+It can also be used to implement lazy restore
+for checkpoint/restore mechanisms,
+as well as post-copy migration to allow (nearly) uninterrupted execution
+when transferring virtual machines and Linux containers
+from one host to another.
+.SH BUGS
+If the
+.B UFFD_FEATURE_EVENT_FORK
+is enabled and a system call from the
+.BR fork (2)
+family is interrupted by a signal or failed, a stale userfaultfd descriptor
+might be created.
+In this case, a spurious
+.B UFFD_EVENT_FORK
+will be delivered to the userfaultfd monitor.
+.SH EXAMPLES
+The program below demonstrates the use of the userfaultfd mechanism.
+The program creates two threads, one of which acts as the
+page-fault handler for the process, for the pages in a demand-page zero
+region created using
+.BR mmap (2).
+.P
+The program takes one command-line argument,
+which is the number of pages that will be created in a mapping
+whose page faults will be handled via userfaultfd.
+After creating a userfaultfd object,
+the program then creates an anonymous private mapping of the specified size
+and registers the address range of that mapping using the
+.B UFFDIO_REGISTER
+.BR ioctl (2)
+operation.
+The program then creates a second thread that will perform the
+task of handling page faults.
+.P
+The main thread then walks through the pages of the mapping fetching
+bytes from successive pages.
+Because the pages have not yet been accessed,
+the first access of a byte in each page will trigger a page-fault event
+on the userfaultfd file descriptor.
+.P
+Each of the page-fault events is handled by the second thread,
+which sits in a loop processing input from the userfaultfd file descriptor.
+In each loop iteration, the second thread first calls
+.BR poll (2)
+to check the state of the file descriptor,
+and then reads an event from the file descriptor.
+All such events should be
+.B UFFD_EVENT_PAGEFAULT
+events,
+which the thread handles by copying a page of data into
+the faulting region using the
+.B UFFDIO_COPY
+.BR ioctl (2)
+operation.
+.P
+The following is an example of what we see when running the program:
+.P
+.in +4n
+.EX
+$ \fB./userfaultfd_demo 3\fP
+Address returned by mmap() = 0x7fd30106c000
+\&
+fault_handler_thread():
+ poll() returns: nready = 1; POLLIN = 1; POLLERR = 0
+ UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106c00f
+ (uffdio_copy.copy returned 4096)
+Read address 0x7fd30106c00f in main(): A
+Read address 0x7fd30106c40f in main(): A
+Read address 0x7fd30106c80f in main(): A
+Read address 0x7fd30106cc0f in main(): A
+\&
+fault_handler_thread():
+ poll() returns: nready = 1; POLLIN = 1; POLLERR = 0
+ UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106d00f
+ (uffdio_copy.copy returned 4096)
+Read address 0x7fd30106d00f in main(): B
+Read address 0x7fd30106d40f in main(): B
+Read address 0x7fd30106d80f in main(): B
+Read address 0x7fd30106dc0f in main(): B
+\&
+fault_handler_thread():
+ poll() returns: nready = 1; POLLIN = 1; POLLERR = 0
+ UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106e00f
+ (uffdio_copy.copy returned 4096)
+Read address 0x7fd30106e00f in main(): C
+Read address 0x7fd30106e40f in main(): C
+Read address 0x7fd30106e80f in main(): C
+Read address 0x7fd30106ec0f in main(): C
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (userfaultfd.c)
+.EX
+/* userfaultfd_demo.c
+\&
+ Licensed under the GNU General Public License version 2 or later.
+*/
+#define _GNU_SOURCE
+#include <err.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <inttypes.h>
+#include <linux/userfaultfd.h>
+#include <poll.h>
+#include <pthread.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <sys/mman.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+\&
+static int page_size;
+\&
+static void *
+fault_handler_thread(void *arg)
+{
+ int nready;
+ long uffd; /* userfaultfd file descriptor */
+ ssize_t nread;
+ struct pollfd pollfd;
+ struct uffdio_copy uffdio_copy;
+\&
+ static int fault_cnt = 0; /* Number of faults so far handled */
+ static char *page = NULL;
+ static struct uffd_msg msg; /* Data read from userfaultfd */
+\&
+ uffd = (long) arg;
+\&
+ /* Create a page that will be copied into the faulting region. */
+\&
+ if (page == NULL) {
+ page = mmap(NULL, page_size, PROT_READ | PROT_WRITE,
+ MAP_PRIVATE | MAP_ANONYMOUS, \-1, 0);
+ if (page == MAP_FAILED)
+ err(EXIT_FAILURE, "mmap");
+ }
+\&
+ /* Loop, handling incoming events on the userfaultfd
+ file descriptor. */
+\&
+ for (;;) {
+\&
+ /* See what poll() tells us about the userfaultfd. */
+\&
+ pollfd.fd = uffd;
+ pollfd.events = POLLIN;
+ nready = poll(&pollfd, 1, \-1);
+ if (nready == \-1)
+ err(EXIT_FAILURE, "poll");
+\&
+ printf("\enfault_handler_thread():\en");
+ printf(" poll() returns: nready = %d; "
+ "POLLIN = %d; POLLERR = %d\en", nready,
+ (pollfd.revents & POLLIN) != 0,
+ (pollfd.revents & POLLERR) != 0);
+\&
+ /* Read an event from the userfaultfd. */
+\&
+ nread = read(uffd, &msg, sizeof(msg));
+ if (nread == 0) {
+ printf("EOF on userfaultfd!\en");
+ exit(EXIT_FAILURE);
+ }
+\&
+ if (nread == \-1)
+ err(EXIT_FAILURE, "read");
+\&
+ /* We expect only one kind of event; verify that assumption. */
+\&
+ if (msg.event != UFFD_EVENT_PAGEFAULT) {
+ fprintf(stderr, "Unexpected event on userfaultfd\en");
+ exit(EXIT_FAILURE);
+ }
+\&
+ /* Display info about the page\-fault event. */
+\&
+ printf(" UFFD_EVENT_PAGEFAULT event: ");
+ printf("flags = %"PRIx64"; ", msg.arg.pagefault.flags);
+ printf("address = %"PRIx64"\en", msg.arg.pagefault.address);
+\&
+ /* Copy the page pointed to by \[aq]page\[aq] into the faulting
+ region. Vary the contents that are copied in, so that it
+ is more obvious that each fault is handled separately. */
+\&
+ memset(page, \[aq]A\[aq] + fault_cnt % 20, page_size);
+ fault_cnt++;
+\&
+ uffdio_copy.src = (unsigned long) page;
+\&
+ /* We need to handle page faults in units of pages(!).
+ So, round faulting address down to page boundary. */
+\&
+ uffdio_copy.dst = (unsigned long) msg.arg.pagefault.address &
+ \[ti](page_size \- 1);
+ uffdio_copy.len = page_size;
+ uffdio_copy.mode = 0;
+ uffdio_copy.copy = 0;
+ if (ioctl(uffd, UFFDIO_COPY, &uffdio_copy) == \-1)
+ err(EXIT_FAILURE, "ioctl\-UFFDIO_COPY");
+\&
+ printf(" (uffdio_copy.copy returned %"PRId64")\en",
+ uffdio_copy.copy);
+ }
+}
+\&
+int
+main(int argc, char *argv[])
+{
+ int s;
+ char c;
+ char *addr; /* Start of region handled by userfaultfd */
+ long uffd; /* userfaultfd file descriptor */
+ size_t len, l; /* Length of region handled by userfaultfd */
+ pthread_t thr; /* ID of thread that handles page faults */
+ struct uffdio_api uffdio_api;
+ struct uffdio_register uffdio_register;
+\&
+ if (argc != 2) {
+ fprintf(stderr, "Usage: %s num\-pages\en", argv[0]);
+ exit(EXIT_FAILURE);
+ }
+\&
+ page_size = sysconf(_SC_PAGE_SIZE);
+ len = strtoull(argv[1], NULL, 0) * page_size;
+\&
+ /* Create and enable userfaultfd object. */
+\&
+ uffd = syscall(SYS_userfaultfd, O_CLOEXEC | O_NONBLOCK);
+ if (uffd == \-1)
+ err(EXIT_FAILURE, "userfaultfd");
+\&
+ /* NOTE: Two-step feature handshake is not needed here, since this
+ example doesn't require any specific features.
+\&
+ Programs that *do* should call UFFDIO_API twice: once with
+ `features = 0` to detect features supported by this kernel, and
+ again with the subset of features the program actually wants to
+ enable. */
+ uffdio_api.api = UFFD_API;
+ uffdio_api.features = 0;
+ if (ioctl(uffd, UFFDIO_API, &uffdio_api) == \-1)
+ err(EXIT_FAILURE, "ioctl\-UFFDIO_API");
+\&
+ /* Create a private anonymous mapping. The memory will be
+ demand\-zero paged\-\-that is, not yet allocated. When we
+ actually touch the memory, it will be allocated via
+ the userfaultfd. */
+\&
+ addr = mmap(NULL, len, PROT_READ | PROT_WRITE,
+ MAP_PRIVATE | MAP_ANONYMOUS, \-1, 0);
+ if (addr == MAP_FAILED)
+ err(EXIT_FAILURE, "mmap");
+\&
+ printf("Address returned by mmap() = %p\en", addr);
+\&
+ /* Register the memory range of the mapping we just created for
+ handling by the userfaultfd object. In mode, we request to track
+ missing pages (i.e., pages that have not yet been faulted in). */
+\&
+ uffdio_register.range.start = (unsigned long) addr;
+ uffdio_register.range.len = len;
+ uffdio_register.mode = UFFDIO_REGISTER_MODE_MISSING;
+ if (ioctl(uffd, UFFDIO_REGISTER, &uffdio_register) == \-1)
+ err(EXIT_FAILURE, "ioctl\-UFFDIO_REGISTER");
+\&
+ /* Create a thread that will process the userfaultfd events. */
+\&
+ s = pthread_create(&thr, NULL, fault_handler_thread, (void *) uffd);
+ if (s != 0) {
+ errc(EXIT_FAILURE, s, "pthread_create");
+ }
+\&
+ /* Main thread now touches memory in the mapping, touching
+ locations 1024 bytes apart. This will trigger userfaultfd
+ events for all pages in the region. */
+\&
+ l = 0xf; /* Ensure that faulting address is not on a page
+ boundary, in order to test that we correctly
+ handle that case in fault_handling_thread(). */
+ while (l < len) {
+ c = addr[l];
+ printf("Read address %p in %s(): ", addr + l, __func__);
+ printf("%c\en", c);
+ l += 1024;
+ usleep(100000); /* Slow things down a little */
+ }
+\&
+ exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR fcntl (2),
+.BR ioctl (2),
+.BR ioctl_userfaultfd (2),
+.BR madvise (2),
+.BR mmap (2)
+.P
+.I Documentation/admin\-guide/mm/userfaultfd.rst
+in the Linux kernel source tree