Re: [PATCH v4] mlock.2: mlock2.2: Add entry to for new mlock2 syscall

[Michael Kerrisk (man-pages)]

On 11/09/2015 07:27 PM, Eric B Munson wrote:
> Update the mlock.2 man page with information on mlock2() and the new
> mlockall() flag MCL_ONFAULT.

Hello Eric,

Thanks for the nicely written patch. I've applied.

Cheers,

Michael


> Signed-off-by: Eric B Munson 
> Acked-by: Michal Hocko 
> Acked-by: Vlastimil Babka 
> Cc: Michal Hocko 
> Cc: Vlastimil Babka 
> Cc: Jonathan Corbet 
> Cc: linux-...@vger.kernel.org
> Cc: linux...@kvack.org
> Cc: linux-kernel@vger.kernel.org
> ---
> Changes from V3:
>  Add note about not having a glibc wrapper for mlock2
> 
> Changes from V2:
>  Update available from kernel version
> 
>  man2/mlock.2  | 114 
> +++---
>  man2/mlock2.2 |   1 +
>  2 files changed, 102 insertions(+), 13 deletions(-)
>  create mode 100644 man2/mlock2.2
> 
> diff --git a/man2/mlock.2 b/man2/mlock.2
> index 79c544d..0ad580c 100644
> --- a/man2/mlock.2
> +++ b/man2/mlock.2
> @@ -23,21 +23,23 @@
>  .\" .
>  .\" %%%LICENSE_END
>  .\"
> -.TH MLOCK 2 2015-07-23 "Linux" "Linux Programmer's Manual"
> +.TH MLOCK 2 2015-08-28 "Linux" "Linux Programmer's Manual"
>  .SH NAME
> -mlock, munlock, mlockall, munlockall \- lock and unlock memory
> +mlock, mlock2, munlock, mlockall, munlockall \- lock and unlock memory
>  .SH SYNOPSIS
>  .nf
>  .B #include 
>  .sp
>  .BI "int mlock(const void *" addr ", size_t " len );
> +.BI "int mlock2(const void *" addr ", size_t " len ", int " flags );
>  .BI "int munlock(const void *" addr ", size_t " len );
>  .sp
>  .BI "int mlockall(int " flags );
>  .B int munlockall(void);
>  .fi
>  .SH DESCRIPTION
> -.BR mlock ()
> +.BR mlock (),
> +.BR mlock2 (),
>  and
>  .BR mlockall ()
>  respectively lock part or all of the calling process's virtual address
> @@ -51,7 +53,7 @@ respectively unlocking part or all of the calling process's 
> virtual
>  address space, so that pages in the specified virtual address range may
>  once more to be swapped out if required by the kernel memory manager.
>  Memory locking and unlocking are performed in units of whole pages.
> -.SS mlock() and munlock()
> +.SS mlock(), mlock2(), and munlock()
>  .BR mlock ()
>  locks pages in the address range starting at
>  .I addr
> @@ -62,6 +64,39 @@ All pages that contain a part of the specified address 
> range are
>  guaranteed to be resident in RAM when the call returns successfully;
>  the pages are guaranteed to stay in RAM until later unlocked.
>  
> +.BR mlock2 ()
> +also locks pages in the specified range starting at
> +.I addr
> +and continuing for
> +.I len
> +bytes.
> +However, the state of the pages contained in that range after the call
> +returns successfully will depend on the value in the
> +.I flags
> +argument.
> +
> +The
> +.I flags
> +argument can be either 0 or the following constant:
> +.TP 1.2i
> +.B MLOCK_ONFAULT
> +Lock pages that are currently resident and mark the entire range to have
> +pages locked when they are populated by the page fault.
> +.PP
> +
> +If
> +.I flags
> +is 0,
> +.BR mlock2 ()
> +will function exactly as
> +.BR mlock ()
> +would.
> +
> +Note: Currently, there is not a glibc wrapper for
> +.BR mlock2 ()
> +so it will need to be invoked using
> +.BR syscall (2)
> +
>  .BR munlock ()
>  unlocks pages in the address range starting at
>  .I addr
> @@ -93,9 +128,33 @@ the process.
>  .B MCL_FUTURE
>  Lock all pages which will become mapped into the address space of the
>  process in the future.
> -These could be for instance new pages required
> +These could be, for instance, new pages required
>  by a growing heap and stack as well as new memory-mapped files or
>  shared memory regions.
> +.TP
> +.BR MCL_ONFAULT " (since Linux 4.4)"
> +Used together with
> +.BR MCL_CURRENT ,
> +.BR MCL_FUTURE ,
> +or both.  Mark all current (with
> +.BR MCL_CURRENT )
> +or future (with
> +.BR MCL_FUTURE )
> +mappings to lock pages when they are faulted in.  When used with
> +.BR MCL_CURRENT ,
> +all present pages are locked, but
> +.BR mlockall ()
> +will not fault in non-present pages.  When used with
> +.BR MCL_FUTURE ,
> +all future mappings will be marked to lock pages when they are faulted
> +in, but they will not be populated by the lock when the mapping is
> +created.
> +.B MCL_ONFAULT
> +must be used with either
> +.B MCL_CURRENT
> +or
> +.B MCL_FUTURE
> +or both.
>  .PP
>  If
>  .B MCL_FUTURE
> @@ -148,7 +207,8 @@ to perform the requested operation.
>  .\"SVr4 documents an additional EAGAIN error code.
>  .LP
>  For
> -.BR mlock ()
> +.BR mlock (),
> +.BR mlock2 (),
>  and
>  .BR munlock ():
>  .TP
> @@ -157,9 +217,9 @@ Some or all of the specified address range could not be 
> locked.
>  .TP
>  .B EINVAL
>  The result of the addition
> -.IR start + len
> +.IR addr + len
>  was less than
> -.IR start
> +.IR addr
>  (e.g., the addition may have resulted in an overflow).
>  .TP
>  .B EINVAL
> @@ -181,12 +241,23 @@ mapping would result in three mappings:
>  two locked mappings at each end and an 

Re: [PATCH v4] mlock.2: mlock2.2: Add entry to for new mlock2 syscall

[Michael Kerrisk (man-pages)]

On 11/09/2015 07:27 PM, Eric B Munson wrote:
> Update the mlock.2 man page with information on mlock2() and the new
> mlockall() flag MCL_ONFAULT.

Hello Eric,

Thanks for the nicely written patch. I've applied.

Cheers,

Michael


> Signed-off-by: Eric B Munson 
> Acked-by: Michal Hocko 
> Acked-by: Vlastimil Babka 
> Cc: Michal Hocko 
> Cc: Vlastimil Babka 
> Cc: Jonathan Corbet 
> Cc: linux-...@vger.kernel.org
> Cc: linux...@kvack.org
> Cc: linux-kernel@vger.kernel.org
> ---
> Changes from V3:
>  Add note about not having a glibc wrapper for mlock2
> 
> Changes from V2:
>  Update available from kernel version
> 
>  man2/mlock.2  | 114 
> +++---
>  man2/mlock2.2 |   1 +
>  2 files changed, 102 insertions(+), 13 deletions(-)
>  create mode 100644 man2/mlock2.2
> 
> diff --git a/man2/mlock.2 b/man2/mlock.2
> index 79c544d..0ad580c 100644
> --- a/man2/mlock.2
> +++ b/man2/mlock.2
> @@ -23,21 +23,23 @@
>  .\" .
>  .\" %%%LICENSE_END
>  .\"
> -.TH MLOCK 2 2015-07-23 "Linux" "Linux Programmer's Manual"
> +.TH MLOCK 2 2015-08-28 "Linux" "Linux Programmer's Manual"
>  .SH NAME
> -mlock, munlock, mlockall, munlockall \- lock and unlock memory
> +mlock, mlock2, munlock, mlockall, munlockall \- lock and unlock memory
>  .SH SYNOPSIS
>  .nf
>  .B #include 
>  .sp
>  .BI "int mlock(const void *" addr ", size_t " len );
> +.BI "int mlock2(const void *" addr ", size_t " len ", int " flags );
>  .BI "int munlock(const void *" addr ", size_t " len );
>  .sp
>  .BI "int mlockall(int " flags );
>  .B int munlockall(void);
>  .fi
>  .SH DESCRIPTION
> -.BR mlock ()
> +.BR mlock (),
> +.BR mlock2 (),
>  and
>  .BR mlockall ()
>  respectively lock part or all of the calling process's virtual address
> @@ -51,7 +53,7 @@ respectively unlocking part or all of the calling process's 
> virtual
>  address space, so that pages in the specified virtual address range may
>  once more to be swapped out if required by the kernel memory manager.
>  Memory locking and unlocking are performed in units of whole pages.
> -.SS mlock() and munlock()
> +.SS mlock(), mlock2(), and munlock()
>  .BR mlock ()
>  locks pages in the address range starting at
>  .I addr
> @@ -62,6 +64,39 @@ All pages that contain a part of the specified address 
> range are
>  guaranteed to be resident in RAM when the call returns successfully;
>  the pages are guaranteed to stay in RAM until later unlocked.
>  
> +.BR mlock2 ()
> +also locks pages in the specified range starting at
> +.I addr
> +and continuing for
> +.I len
> +bytes.
> +However, the state of the pages contained in that range after the call
> +returns successfully will depend on the value in the
> +.I flags
> +argument.
> +
> +The
> +.I flags
> +argument can be either 0 or the following constant:
> +.TP 1.2i
> +.B MLOCK_ONFAULT
> +Lock pages that are currently resident and mark the entire range to have
> +pages locked when they are populated by the page fault.
> +.PP
> +
> +If
> +.I flags
> +is 0,
> +.BR mlock2 ()
> +will function exactly as
> +.BR mlock ()
> +would.
> +
> +Note: Currently, there is not a glibc wrapper for
> +.BR mlock2 ()
> +so it will need to be invoked using
> +.BR syscall (2)
> +
>  .BR munlock ()
>  unlocks pages in the address range starting at
>  .I addr
> @@ -93,9 +128,33 @@ the process.
>  .B MCL_FUTURE
>  Lock all pages which will become mapped into the address space of the
>  process in the future.
> -These could be for instance new pages required
> +These could be, for instance, new pages required
>  by a growing heap and stack as well as new memory-mapped files or
>  shared memory regions.
> +.TP
> +.BR MCL_ONFAULT " (since Linux 4.4)"
> +Used together with
> +.BR MCL_CURRENT ,
> +.BR MCL_FUTURE ,
> +or both.  Mark all current (with
> +.BR MCL_CURRENT )
> +or future (with
> +.BR MCL_FUTURE )
> +mappings to lock pages when they are faulted in.  When used with
> +.BR MCL_CURRENT ,
> +all present pages are locked, but
> +.BR mlockall ()
> +will not fault in non-present pages.  When used with
> +.BR MCL_FUTURE ,
> +all future mappings will be marked to lock pages when they are faulted
> +in, but they will not be populated by the lock when the mapping is
> +created.
> +.B MCL_ONFAULT
> +must be used with either
> +.B MCL_CURRENT
> +or
> +.B MCL_FUTURE
> +or both.
>  .PP
>  If
>  .B MCL_FUTURE
> @@ -148,7 +207,8 @@ to perform the requested operation.
>  .\"SVr4 documents an additional EAGAIN error code.
>  .LP
>  For
> -.BR mlock ()
> +.BR mlock (),
> +.BR mlock2 (),
>  and
>  .BR munlock ():
>  .TP
> @@ -157,9 +217,9 @@ Some or all of the specified address range could not be 
> locked.
>  .TP
>  .B EINVAL
>  The result of the addition
> -.IR start + len
> +.IR addr + len
>  was less than
> -.IR start
> +.IR addr
>  (e.g., the addition may have resulted in an overflow).
>  .TP
>  .B EINVAL
> @@