[PATCH] mlockall: Document MCL_ONFAULT flag

[fweimer at redhat dot com (Florian Weimer)]

2017-11-24  Florian Weimer  <fweimer@redhat.com>

	* manual/memory.texi (Page Lock Functions): Document MCL_ONFAULT.

diff --git a/manual/memory.texi b/manual/memory.texi
index 1b431bf5da..d96e9881de 100644
--- a/manual/memory.texi
+++ b/manual/memory.texi
@@ -3404,31 +3404,52 @@ other bits must be zero.
 @vtable @code
 
 @item MCL_CURRENT
+@standards{POSIX.1b, sys/mman.h}
 Lock all pages which currently exist in the calling process' virtual
 address space.
 
 @item MCL_FUTURE
+@standards{POSIX.1b, sys/mman.h}
 Set a mode such that any pages added to the process' virtual address
 space in the future will be locked from birth.  This mode does not
 affect future address spaces owned by the same process so exec, which
 replaces a process' address space, wipes out @code{MCL_FUTURE}.
 @xref{Executing a File}.
 
+@item MCL_ONFAULT
+@standards{Linux, sys/mman.h}
+Together with @code{MCL_CURRENT}, only those which are already in memory
+are locked immediately.  Additional pages in the range are automatically
+locked in case of a page fault and allocation of memory.  That is, all
+existing mappings behave as if @code{MLOCK_ONFAULT} had been specified
+for them using @code{mlock2}.
+
+Together with @code{MCL_FUTURE}, new mappings behave as if
+@code{MLOCK_ONFAULT} is specified for them using @code{mlock2} (that is,
+they are not immediately locked into memory, but will be on a page
+fault).
 @end vtable
 
 When the function returns successfully, and you specified
-@code{MCL_CURRENT}, all of the process' pages are backed by (connected
-to) real frames (they are resident) and are marked to stay that way.
-This means the function may cause page-ins and have to wait for them.
+@code{MCL_CURRENT} without @code{MCL_ONFAULT}, all of the process' pages
+are backed by (connected to) real frames (they are resident) and are
+marked to stay that way.  This means the function may cause page-ins and
+have to wait for them.
 
 When the process is in @code{MCL_FUTURE} mode because it successfully
-executed this function and specified @code{MCL_CURRENT}, any system call
-by the process that requires space be added to its virtual address space
-fails with @code{errno} = @code{ENOMEM} if locking the additional space
-would cause the process to exceed its locked page limit.  In the case
-that the address space addition that can't be accommodated is stack
-expansion, the stack expansion fails and the kernel sends a
-@code{SIGSEGV} signal to the process.
+executed this function and specified @code{MCL_FUTURE} without
+@code{MCL_ONFAULT}, any system call by the process that requires space
+be added to its virtual address space fails with @code{errno} =
+@code{ENOMEM} if locking the additional space would cause the process to
+exceed its locked page limit.  In the case that the address space
+addition that can't be accommodated is stack expansion, the stack
+expansion fails and the kernel sends a @code{SIGSEGV} signal to the
+process.
+
+When you specify the additional @code{MCL_ONFAULT}, no page-ins occur
+with @code{MCL_CURRENT}, and with @code{MCL_FUTURE}, new allocations do
+not initially count against the locked page limit (until a page fault
+happens and they are locked into memory).
 
 When the function fails, it does not affect the lock status of any pages
 or the future locking mode.