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 .\" FIXME Need to describe close(2) semantics for userfaulfd file descriptor
  28 .\"
  29 .TH USERFAULTFD 2 2016-12-12 "Linux" "Linux Programmer's Manual"
  30 .SH NAME
  31 userfaultfd \- create a file descriptor for handling page faults in user space
  32 .SH SYNOPSIS
  33 .nf
  34 .B #include <sys/types.h>
  35 .sp
  36 .BI "int userfaultfd(int " flags );
  37 .fi
  38 .PP
  39 .IR Note :
  40 There is no glibc wrapper for this system call; see NOTES.
  41 .SH DESCRIPTION
  42 .BR userfaultfd ()
  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
  47 .BR ioctl (2).
  48
  49 Once the userfaultfd object is configured, the application can use
  50 .BR read (2)
  51 to receive userfaultfd notifications.
  52 The reads from userfaultfd may be blocking or non-blocking,
  53 depending on the value of
  54 .I flags
  55 used for the creation of the userfaultfd or subsequent calls to
  56 .BR fcntl (2).
  57
  58 The following values may be bitwise ORed in
  59 .IR flags
  60 to change the behavior of
  61 .BR userfaultfd ():
  62 .TP
  63 .BR O_CLOEXEC
  64 Enable the close-on-exec flag for the new userfaultfd file descriptor.
  65 See the description of the
  66 .B O_CLOEXEC
  67 flag in
  68 .BR open (2).
  69 .TP
  70 .BR O_NONBLOCK
  71 Enables non-blocking operation for the userfaultfd object.
  72 See the description of the
  73 .BR O_NONBLOCK
  74 flag in
  75 .BR open (2).
  76 .\"
  77 .SS Usage
  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.
  89 .\"
  90 .SS Userfaultfd operation
  91 After the userfaultfd object is created with
  92 .BR userfaultfd (),
  93 the application must enable it using the
  94 .B UFFDIO_API
  95 .BR ioctl (2)
  96 operation.
  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
 100 .BR ioctl (2)
 101 operations described below (or those operations fail with the
 102 .BR EINVAL
 103 error).
 104
 105 After a successful
 106 .B UFFDIO_API
 107 operation,
 108 the application then registers memory address ranges using the
 109 .B UFFDIO_REGISTER
 110 .BR ioctl (2)
 111 operation.
 112 After successful completion of a
 113 .B UFFDIO_REGISTER
 114 operation,
 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
 119 .B UFFDIO_COPY
 120 or
 121 .B UFFDIO_ZERO
 122 .BR ioctl (2)
 123 operations to resolve the page fault.
 124
 125 Details of the various
 126 .BR ioctl (2)
 127 operations can be found in
 128 .BR ioctl_userfaultfd (2).
 129
 130 Currently, userfaultfd can be used only with anonymous private memory
 131 mappings.
 132 .\"
 133 .SS Reading from the userfaultfd structure
 134 .\" FIXME are the details below correct
 135 Each
 136 .BR read (2)
 137 from the userfaultfd file descriptor returns one or more
 138 .I uffd_msg
 139 structures, each of which describes a page-fault event:
 140
 141 .nf
 142 .in +4n
 143 struct uffd_msg {
 144     __u8  event;                /* Type of event */
 145     ...
 146     union {
 147         struct {
 148             __u64 flags;        /* Flags describing fault */
 149             __u64 address;      /* Faulting address */
 150         } pagefault;
 151         ...
 152     } arg;
 153
 154     /* Padding fields omitted */
 155 } __packed;
 156 .in
 157 .fi
 158
 159 If multiple events are available and the supplied buffer is large enough,
 160 .BR read (2)
 161 returns as many events as will fit in the supplied buffer.
 162 If the buffer supplied to
 163 .BR read (2)
 164 is smaller than the size of the
 165 .I uffd_msg
 166 structure, the
 167 .BR read (2)
 168 fails with the error
 169 .BR EINVAL .
 170
 171 The fields set in the
 172 .I uffd_msg
 173 structure are as follows:
 174 .TP
 175 .I event
 176 The type of event.
 177 Currently, only one value can appear in this field:
 178 .BR UFFD_EVENT_PAGEFAULT ,
 179 which indicates a page-fault event.
 180 .TP
 181 .I address
 182 The address that triggered the page fault.
 183 .TP
 184 .I flags
 185 A bit mask of flags that describe the event.
 186 For
 187 .BR UFFD_EVENT_PAGEFAULT ,
 188 the following flag may appear:
 189 .RS
 190 .TP
 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
 194 flag (see
 195 .BR ioctl_userfaultfd (2))
 196 and this flag is set, this a write fault;
 197 otherwise it is a read fault.
 198 .\"
 199 .\" UFFD_PAGEFAULT_FLAG_WP is not yet supported.
 200 .RE
 201 .PP
 202 The userfaultfd file descriptor can be monitored with
 203 .BR poll (2),
 204 .BR select (2),
 205 and
 206 .BR epoll (7).
 207 When events are available, the file descriptor indicates as readable.
 208 .SH RETURN VALUE
 209 On success,
 210 .BR userfaultfd ()
 211 returns a new file descriptor that refers to the userfaultfd object.
 212 On error, \-1 is returned, and
 213 .I errno
 214 is set appropriately.
 215 .SH ERRORS
 216 .TP
 217 .B EINVAL
 218 An unsupported value was specified in
 219 .IR flags .
 220 .TP
 221 .BR EMFILE
 222 The per-process limit on the number of open file descriptors has been
 223 reached
 224 .TP
 225 .B ENFILE
 226 The system-wide limit on the total number of open files has been
 227 reached.
 228 .TP
 229 .B ENOMEM
 230 Insufficient kernel memory was available.
 231 .SH VERSIONS
 232 The
 233 .BR userfaultfd ()
 234 system call first appeared in Linux 4.3.
 235 .SH CONFORMING TO
 236 .BR userfaultfd ()
 237 is Linux-specific and should not be used in programs intended to be
 238 portable.
 239 .SH NOTES
 240 Glibc does not provide a wrapper for this system call; call it using
 241 .BR syscall (2).
 242 .SH SEE ALSO
 243 .BR fcntl (2),
 244 .BR ioctl (2),
 245 .BR ioctl_userfaultfd (2),
 246 .BR mmap (2)
 247
 248 .IR Documentation/vm/userfaultfd.txt
 249 in the Linux kernel source tree
 250