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>
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.
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.
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
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
27 .\" FIXME Need to describe close(2) semantics for userfaulfd file descriptor
29 .TH USERFAULTFD 2 2016-12-12 "Linux" "Linux Programmer's Manual"
31 userfaultfd \- create a file descriptor for handling page faults in user space
34 .B #include <sys/types.h>
36 .BI "int userfaultfd(int " flags );
40 There is no glibc wrapper for this system call; see NOTES.
43 creates a new userfaultfd object that can be used for delegation of page-fault
44 handling to a user-space application,
45 and returns a file descriptor that refers to the new object.
46 The new userfaultfd object is configured using
49 Once the userfaultfd object is configured, the application can use
51 to receive userfaultfd notifications.
52 The reads from userfaultfd may be blocking or non-blocking,
53 depending on the value of
55 used for the creation of the userfaultfd or subsequent calls to
58 The following values may be bitwise ORed in
60 to change the behavior of
64 Enable the close-on-exec flag for the new userfaultfd file descriptor.
65 See the description of the
71 Enables non-blocking operation for the userfaultfd object.
72 See the description of the
78 The userfaultfd mechanism is designed to allow a thread in a multithreaded
79 program to perform user-space paging for the other threads in the process.
80 When a page fault occurs for one of the regions registered
81 to the userfaultfd object,
82 the faulting thread is put to sleep and
83 an event is generated that can be read via the userfaultfd file descriptor.
84 The fault-handling thread reads events from this file descriptor and services
85 them using the operations described in
86 .BR ioctl_userfaultfd (2).
87 When servicing the page fault events,
88 the fault-handling thread can trigger a wake-up for the sleeping thread.
90 .SS Userfaultfd operation
91 After the userfaultfd object is created with
93 the application must enable it using the
97 This operation allows a handshake between the kernel and user space
98 to determine the API version and supported features.
99 This operation must be performed before any of the other
101 operations described below (or those operations fail with the
108 the application then registers memory address ranges using the
112 After successful completion of a
115 a page fault occurring in the requested memory range, and satisfying
116 the mode defined at the registration time, will be forwarded by the kernel to
117 the user-space application.
118 The application can then use the
123 operations to resolve the page fault.
125 Details of the various
127 operations can be found in
128 .BR ioctl_userfaultfd (2).
130 Currently, userfaultfd can be used only with anonymous private memory
133 .SS Reading from the userfaultfd structure
134 .\" FIXME are the details below correct
137 from the userfaultfd file descriptor returns one or more
139 structures, each of which describes a page-fault event:
144 __u8 event; /* Type of event */
148 __u64 flags; /* Flags describing fault */
149 __u64 address; /* Faulting address */
154 /* Padding fields omitted */
159 If multiple events are available and the supplied buffer is large enough,
161 returns as many events as will fit in the supplied buffer.
162 If the buffer supplied to
164 is smaller than the size of the
171 The fields set in the
173 structure are as follows:
177 Currently, only one value can appear in this field:
178 .BR UFFD_EVENT_PAGEFAULT ,
179 which indicates a page-fault event.
182 The address that triggered the page fault.
185 A bit mask of flags that describe the event.
187 .BR UFFD_EVENT_PAGEFAULT ,
188 the following flag may appear:
191 .B UFFD_PAGEFAULT_FLAG_WRITE
192 If the address is in a range that was registered with the
193 .B UFFDIO_REGISTER_MODE_MISSING
195 .BR ioctl_userfaultfd (2))
196 and this flag is set, this a write fault;
197 otherwise it is a read fault.
199 .\" UFFD_PAGEFAULT_FLAG_WP is not yet supported.
204 on a userfaultfd file descriptor can fail with the following errors:
207 The userfaultfd object has not yet been enabled using the
212 The userfaultfd file descriptor can be monitored with
217 When events are available, the file descriptor indicates as readable.
218 .\" FIXME But, it seems, the object must be created with O_NONBLOCK.
219 .\" What is the rationale for this requirement?
223 returns a new file descriptor that refers to the userfaultfd object.
224 On error, \-1 is returned, and
226 is set appropriately.
230 An unsupported value was specified in
234 The per-process limit on the number of open file descriptors has been
238 The system-wide limit on the total number of open files has been
242 Insufficient kernel memory was available.
246 system call first appeared in Linux 4.3.
249 is Linux-specific and should not be used in programs intended to be
252 Glibc does not provide a wrapper for this system call; call it using
257 .BR ioctl_userfaultfd (2),
260 .IR Documentation/vm/userfaultfd.txt
261 in the Linux kernel source tree