mlockall: Document MCL_ONFAULT flag

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

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

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
  

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.
  

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