[PATCH] mlockall: Document MCL_ONFAULT flag

[PATCH] mlockall: Document MCL_ONFAULT flag

[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.

Re: [PATCH] mlockall: Document MCL_ONFAULT flag

[Rical Jasan]

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

Re: [PATCH] mlockall: Document MCL_ONFAULT flag

[Florian Weimer]

On 11/28/2017 11:42 AM, Rical Jasan wrote:
> 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).

Neither have I.  I assumed they were defined along with mlockall.  These 
constants are in current POSIX.

>> +@item MCL_ONFAULT
>> +@standards{Linux, sys/mman.h}
>> +Together with @code{MCL_CURRENT}, only those which are already in memory
> 
> "only those pages"

Fixed.

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

Right, should have added that to the ChangeLog.  Now fixed.

Thanks,
Florian

Re: [PATCH] mlockall: Document MCL_ONFAULT flag

[Joseph Myers]

On Mon, 27 Nov 2017, Florian Weimer wrote:

> > >     @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).
> 
> Neither have I.  I assumed they were defined along with mlockall.  These
> constants are in current POSIX.

POSIX.1b (1993) is correct for these constants.

-- 
Joseph S. Myers
joseph@codesourcery.com