Re: [PATCH] mlockall: Document MCL_ONFAULT flag

[Rical Jasan <ricaljasan@pacific.net>]

On 11/24/2017 08:59 AM, Florian Weimer wrote:
> 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}

Thanks for completing those (though I haven't confirmed the standard).

>  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

"only those pages"

> +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

Good eye; looks like a typo.

> +@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).

Someone else will have to vouch for the correctness of this.

>  
>  When the function fails, it does not affect the lock status of any pages
>  or the future locking mode.

Rical