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 <emunson@xxxxxxxxxx>
> Acked-by: Michal Hocko <mhocko@xxxxxxxx>
> Acked-by: Vlastimil Babka <vbabka@xxxxxxx>
> Cc: Michal Hocko <mhocko@xxxxxxx>
> Cc: Vlastimil Babka <vbabka@xxxxxxx>
> Cc: Jonathan Corbet <corbet@xxxxxxx>
> Cc: linux-man@xxxxxxxxxxxxxxx
> Cc: linux-mm@xxxxxxxxx
> Cc: linux-kernel@xxxxxxxxxxxxxxx
> ---
> 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 @@
>  .\" <http://www.gnu.org/licenses/>.
>  .\" %%%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 <sys/mman.h>
>  .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 unlocked mapping in the middle.)
>  .LP
>  For
> -.BR mlockall ():
> +.BR mlock2 ():
>  .TP
>  .B EINVAL
>  Unknown \fIflags\fP were specified.
>  .LP
>  For
> +.BR mlockall ():
> +.TP
> +.B EINVAL
> +Unknown \fIflags\fP were specified or
> +.B MCL_ONFAULT
> +was specified without either
> +.B MCL_FUTURE
> +or
> +.BR MCL_CURRENT .
> +.LP
> +For
>  .BR munlockall ():
>  .TP
>  .B EPERM
> @@ -259,9 +330,11 @@ or when the process terminates.
>  The
>  .BR mlockall ()
>  .B MCL_FUTURE
> -setting is not inherited by a child created via
> +and
> +.B MCL_FUTURE | MCL_ONFAULT
> +settings are not inherited by a child created via
>  .BR fork (2)
> -and is cleared during an
> +and are cleared during an
>  .BR execve (2).
>  
>  The memory lock on an address range is automatically removed
> @@ -270,7 +343,8 @@ if the address range is unmapped via
>  
>  Memory locks do not stack, that is, pages which have been locked several times
>  by calls to
> -.BR mlock ()
> +.BR mlock (),
> +.BR mlock2 (),
>  or
>  .BR mlockall ()
>  will be unlocked by a single call to
> @@ -280,9 +354,19 @@ for the corresponding range or by
>  Pages which are mapped to several locations or by several processes stay
>  locked into RAM as long as they are locked at least at one location or by
>  at least one process.
> +
> +If a call to
> +.BR mlockall ()
> +which uses the
> +.B MCL_FUTURE
> +flag is followed by another call that does not specify this flag, the
> +changes made by the
> +.B MCL_FUTURE
> +call will be lost.
>  .SS Linux notes
>  Under Linux,
> -.BR mlock ()
> +.BR mlock (),
> +.BR mlock2 (),
>  and
>  .BR munlock ()
>  automatically round
> @@ -300,6 +384,7 @@ file shows how many kilobytes of memory the process with ID
>  .I PID
>  has locked using
>  .BR mlock (),
> +.BR mlock2 (),
>  .BR mlockall (),
>  and
>  .BR mmap (2)
> @@ -342,6 +427,9 @@ resource limit is encountered.
>  .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2
>  .\" "Rationale for RLIMIT_MEMLOCK"
>  .\" 23 Jan 2006
> +.SH VERSIONS
> +.BR mlock2 (2)
> +is available since Linux 4.4.
>  .SH SEE ALSO
>  .BR mmap (2),
>  .BR setrlimit (2),
> diff --git a/man2/mlock2.2 b/man2/mlock2.2
> new file mode 100644
> index 0000000..5e5b3c7
> --- /dev/null
> +++ b/man2/mlock2.2
> @@ -0,0 +1 @@
> +.so man2/mlock.2
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/