fuse.4: ffix

[thirdparty/man-pages.git] / man2 / userfaultfd.2

diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index 52dd56537d63086aad4b04c5493b8bc74bbee6c4..e1a8343b3b36272fdd94334dad935f528ea3e5b1 100644 (file)
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2
@@ -24,7 +24,7 @@
 .\" the source, must acknowledge the copyright and authors of this work.
 .\" %%%LICENSE_END
 .\"
-.TH USERFAULTFD 2 2017-05-03 "Linux" "Linux Programmer's Manual"
+.TH USERFAULTFD 2 2017-09-15 "Linux" "Linux Programmer's Manual"
 .SH NAME
 userfaultfd \- create a file descriptor for handling page faults in user space
 .SH SYNOPSIS
@@ -168,10 +168,36 @@ the user-space application.
 The application can then use the
 .B UFFDIO_COPY
 or
-.B UFFDIO_ZERO
+.B UFFDIO_ZEROPAGE
 .BR ioctl (2)
 operations to resolve the page fault.
 .PP
+Starting from 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.
+.PP
+The
+.B UFFD_FEATURE_SIGBUS
+feature is implicitly inherited through
+.BR fork (2)
+if used in combination with
+.BR UFFD_FEATURE_FORK .
+.PP
 Details of the various
 .BR ioctl (2)
 operations can be found in
@@ -195,8 +221,8 @@ from the userfaultfd file descriptor returns one or more
 structures, each of which describes a page-fault event
 or an event required for the non-cooperative userfaultfd usage:
 .PP
-.nf
 .in +4n
+.EX
 struct uffd_msg {
     __u8  event;            /* Type of event */
     ...
@@ -226,8 +252,8 @@ struct uffd_msg {
 
     /* Padding fields omitted */
 } __packed;
+.EE
 .in
-.fi
 .PP
 If multiple events are available and the supplied buffer is large enough,
 .BR read (2)
@@ -439,6 +465,16 @@ 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 EXAMPLE
 The program below demonstrates the use of the userfaultfd mechanism.
 The program creates two threads, one of which acts as the
@@ -481,8 +517,8 @@ operation.
 .PP
 The following is an example of what we see when running the program:
 .PP
-.nf
 .in +4n
+.EX
 $ \fB./userfaultfd_demo 3\fP
 Address returned by mmap() = 0x7fd30106c000
 
@@ -512,8 +548,8 @@ 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
-.fi
 .SS Program source
 \&
 .EX
@@ -720,6 +756,6 @@ main(int argc, char *argv[])
 .BR madvise (2),
 .BR mmap (2)
 .PP
-.IR Documentation/vm/userfaultfd.txt
+.IR Documentation/admin-guide/mm/userfaultfd.rst
 in the Linux kernel source tree
 .PP