|
|
96cc1f |
From 88a7af51d8ef4d9199ff9073bc09eabb5182fe80 Mon Sep 17 00:00:00 2001
|
|
|
96cc1f |
From: =?UTF-8?q?Nikola=20Forr=C3=B3?= <nforro@redhat.com>
|
|
|
96cc1f |
Date: Tue, 19 Jun 2018 13:14:13 +0200
|
|
|
96cc1f |
Subject: [PATCH 2/3] mlock.2, mlock2.2: document mlock2(2) and MCL_ONFAULT
|
|
|
96cc1f |
---
|
|
|
96cc1f |
man-pages/man2/mlock.2 | 152 ++++++++++++++++++++++++++++++++++++-----
|
|
|
96cc1f |
1 file changed, 136 insertions(+), 16 deletions(-)
|
|
|
96cc1f |
|
|
|
96cc1f |
diff --git a/man-pages/man2/mlock.2 b/man-pages/man2/mlock.2
|
|
|
96cc1f |
index 27189d8..595c9e9 100644
|
|
|
96cc1f |
--- a/man-pages/man2/mlock.2
|
|
|
96cc1f |
+++ b/man-pages/man2/mlock.2
|
|
|
96cc1f |
@@ -23,35 +23,39 @@
|
|
|
96cc1f |
.\" <http://www.gnu.org/licenses/>.
|
|
|
96cc1f |
.\" %%%LICENSE_END
|
|
|
96cc1f |
.\"
|
|
|
96cc1f |
-.TH MLOCK 2 2011-09-14 "Linux" "Linux Programmer's Manual"
|
|
|
96cc1f |
+.TH MLOCK 2 2015-08-28 "Linux" "Linux Programmer's Manual"
|
|
|
96cc1f |
.SH NAME
|
|
|
96cc1f |
-mlock, munlock, mlockall, munlockall \- lock and unlock memory
|
|
|
96cc1f |
+mlock, mlock2, munlock, mlockall, munlockall \- lock and unlock memory
|
|
|
96cc1f |
.SH SYNOPSIS
|
|
|
96cc1f |
.nf
|
|
|
96cc1f |
.B #include <sys/mman.h>
|
|
|
96cc1f |
.sp
|
|
|
96cc1f |
.BI "int mlock(const void *" addr ", size_t " len );
|
|
|
96cc1f |
+.BI "int mlock2(const void *" addr ", size_t " len ", int " flags );
|
|
|
96cc1f |
.BI "int munlock(const void *" addr ", size_t " len );
|
|
|
96cc1f |
.sp
|
|
|
96cc1f |
.BI "int mlockall(int " flags );
|
|
|
96cc1f |
.B int munlockall(void);
|
|
|
96cc1f |
.fi
|
|
|
96cc1f |
.SH DESCRIPTION
|
|
|
96cc1f |
-.BR mlock ()
|
|
|
96cc1f |
+.BR mlock (),
|
|
|
96cc1f |
+.BR mlock2 (),
|
|
|
96cc1f |
and
|
|
|
96cc1f |
.BR mlockall ()
|
|
|
96cc1f |
-respectively lock part or all of the calling process's virtual address
|
|
|
96cc1f |
+lock part or all of the calling process's virtual address
|
|
|
96cc1f |
space into RAM, preventing that memory from being paged to the
|
|
|
96cc1f |
swap area.
|
|
|
96cc1f |
+
|
|
|
96cc1f |
.BR munlock ()
|
|
|
96cc1f |
and
|
|
|
96cc1f |
.BR munlockall ()
|
|
|
96cc1f |
perform the converse operation,
|
|
|
96cc1f |
-respectively unlocking part or all of the calling process's virtual
|
|
|
96cc1f |
+unlocking part or all of the calling process's virtual
|
|
|
96cc1f |
address space, so that pages in the specified virtual address range may
|
|
|
96cc1f |
once more to be swapped out if required by the kernel memory manager.
|
|
|
96cc1f |
+
|
|
|
96cc1f |
Memory locking and unlocking are performed in units of whole pages.
|
|
|
96cc1f |
-.SS mlock() and munlock()
|
|
|
96cc1f |
+.SS mlock(), mlock2(), and munlock()
|
|
|
96cc1f |
.BR mlock ()
|
|
|
96cc1f |
locks pages in the address range starting at
|
|
|
96cc1f |
.I addr
|
|
|
96cc1f |
@@ -62,6 +66,41 @@ All pages that contain a part of the specified address range are
|
|
|
96cc1f |
guaranteed to be resident in RAM when the call returns successfully;
|
|
|
96cc1f |
the pages are guaranteed to stay in RAM until later unlocked.
|
|
|
96cc1f |
|
|
|
96cc1f |
+.BR mlock2 ()
|
|
|
96cc1f |
+.\" commit a8ca5d0ecbdde5cc3d7accacbd69968b0c98764e
|
|
|
96cc1f |
+.\" commit de60f5f10c58d4f34b68622442c0e04180367f3f
|
|
|
96cc1f |
+.\" commit b0f205c2a3082dd9081f9a94e50658c5fa906ff1
|
|
|
96cc1f |
+also locks pages in the specified range starting at
|
|
|
96cc1f |
+.I addr
|
|
|
96cc1f |
+and continuing for
|
|
|
96cc1f |
+.I len
|
|
|
96cc1f |
+bytes.
|
|
|
96cc1f |
+However, the state of the pages contained in that range after the call
|
|
|
96cc1f |
+returns successfully will depend on the value in the
|
|
|
96cc1f |
+.I flags
|
|
|
96cc1f |
+argument.
|
|
|
96cc1f |
+
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.I flags
|
|
|
96cc1f |
+argument can be either 0 or the following constant:
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B MLOCK_ONFAULT
|
|
|
96cc1f |
+Lock pages that are currently resident and mark the entire range to have
|
|
|
96cc1f |
+pages locked when they are populated by the page fault.
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+
|
|
|
96cc1f |
+If
|
|
|
96cc1f |
+.I flags
|
|
|
96cc1f |
+is 0,
|
|
|
96cc1f |
+.BR mlock2 ()
|
|
|
96cc1f |
+behaves exactly the same as
|
|
|
96cc1f |
+.BR mlock ().
|
|
|
96cc1f |
+
|
|
|
96cc1f |
+Note: currently, there is not a glibc wrapper for
|
|
|
96cc1f |
+.BR mlock2 (),
|
|
|
96cc1f |
+so it will need to be invoked using
|
|
|
96cc1f |
+.BR syscall (2).
|
|
|
96cc1f |
+
|
|
|
96cc1f |
.BR munlock ()
|
|
|
96cc1f |
unlocks pages in the address range starting at
|
|
|
96cc1f |
.I addr
|
|
|
96cc1f |
@@ -93,9 +132,36 @@ the process.
|
|
|
96cc1f |
.B MCL_FUTURE
|
|
|
96cc1f |
Lock all pages which will become mapped into the address space of the
|
|
|
96cc1f |
process in the future.
|
|
|
96cc1f |
-These could be for instance new pages required
|
|
|
96cc1f |
-by a growing heap and stack as well as new memory mapped files or
|
|
|
96cc1f |
+These could be, for instance, new pages required
|
|
|
96cc1f |
+by a growing heap and stack as well as new memory-mapped files or
|
|
|
96cc1f |
shared memory regions.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR MCL_ONFAULT " (since Linux 4.4)"
|
|
|
96cc1f |
+Used together with
|
|
|
96cc1f |
+.BR MCL_CURRENT ,
|
|
|
96cc1f |
+.BR MCL_FUTURE ,
|
|
|
96cc1f |
+or both.
|
|
|
96cc1f |
+Mark all current (with
|
|
|
96cc1f |
+.BR MCL_CURRENT )
|
|
|
96cc1f |
+or future (with
|
|
|
96cc1f |
+.BR MCL_FUTURE )
|
|
|
96cc1f |
+mappings to lock pages when they are faulted in.
|
|
|
96cc1f |
+When used with
|
|
|
96cc1f |
+.BR MCL_CURRENT ,
|
|
|
96cc1f |
+all present pages are locked, but
|
|
|
96cc1f |
+.BR mlockall ()
|
|
|
96cc1f |
+will not fault in non-present pages.
|
|
|
96cc1f |
+When used with
|
|
|
96cc1f |
+.BR MCL_FUTURE ,
|
|
|
96cc1f |
+all future mappings will be marked to lock pages when they are faulted
|
|
|
96cc1f |
+in, but they will not be populated by the lock when the mapping is
|
|
|
96cc1f |
+created.
|
|
|
96cc1f |
+.B MCL_ONFAULT
|
|
|
96cc1f |
+must be used with either
|
|
|
96cc1f |
+.B MCL_CURRENT
|
|
|
96cc1f |
+or
|
|
|
96cc1f |
+.B MCL_FUTURE
|
|
|
96cc1f |
+or both.
|
|
|
96cc1f |
.PP
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.B MCL_FUTURE
|
|
|
96cc1f |
@@ -148,7 +214,8 @@ to perform the requested operation.
|
|
|
96cc1f |
.\"SVr4 documents an additional EAGAIN error code.
|
|
|
96cc1f |
.LP
|
|
|
96cc1f |
For
|
|
|
96cc1f |
-.BR mlock ()
|
|
|
96cc1f |
+.BR mlock (),
|
|
|
96cc1f |
+.BR mlock2 (),
|
|
|
96cc1f |
and
|
|
|
96cc1f |
.BR munlock ():
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
@@ -157,9 +224,9 @@ Some or all of the specified address range could not be locked.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B EINVAL
|
|
|
96cc1f |
The result of the addition
|
|
|
96cc1f |
-.IR start + len
|
|
|
96cc1f |
+.IR addr + len
|
|
|
96cc1f |
was less than
|
|
|
96cc1f |
-.IR start
|
|
|
96cc1f |
+.IR addr
|
|
|
96cc1f |
(e.g., the addition may have resulted in an overflow).
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B EINVAL
|
|
|
96cc1f |
@@ -172,19 +239,36 @@ Some of the specified address range does not correspond to mapped
|
|
|
96cc1f |
pages in the address space of the process.
|
|
|
96cc1f |
.LP
|
|
|
96cc1f |
For
|
|
|
96cc1f |
-.BR mlockall ():
|
|
|
96cc1f |
+.BR mlock2 ():
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B EINVAL
|
|
|
96cc1f |
Unknown \fIflags\fP were specified.
|
|
|
96cc1f |
.LP
|
|
|
96cc1f |
For
|
|
|
96cc1f |
+.BR mlockall ():
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B EINVAL
|
|
|
96cc1f |
+Unknown \fIflags\fP were specified or
|
|
|
96cc1f |
+.B MCL_ONFAULT
|
|
|
96cc1f |
+was specified without either
|
|
|
96cc1f |
+.B MCL_FUTURE
|
|
|
96cc1f |
+or
|
|
|
96cc1f |
+.BR MCL_CURRENT .
|
|
|
96cc1f |
+.LP
|
|
|
96cc1f |
+For
|
|
|
96cc1f |
.BR munlockall ():
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B EPERM
|
|
|
96cc1f |
(Linux 2.6.8 and earlier) The caller was not privileged
|
|
|
96cc1f |
.RB ( CAP_IPC_LOCK ).
|
|
|
96cc1f |
+.SH VERSIONS
|
|
|
96cc1f |
+.BR mlock2 (2)
|
|
|
96cc1f |
+is available since Linux 4.4.
|
|
|
96cc1f |
.SH CONFORMING TO
|
|
|
96cc1f |
-POSIX.1-2001, SVr4.
|
|
|
96cc1f |
+POSIX.1-2001, POSIX.1-2008, SVr4.
|
|
|
96cc1f |
+
|
|
|
96cc1f |
+mlock2 ()
|
|
|
96cc1f |
+is Linux specific.
|
|
|
96cc1f |
.SH AVAILABILITY
|
|
|
96cc1f |
On POSIX systems on which
|
|
|
96cc1f |
.BR mlock ()
|
|
|
96cc1f |
@@ -247,6 +331,15 @@ Memory locks are not inherited by a child created via
|
|
|
96cc1f |
and are automatically removed (unlocked) during an
|
|
|
96cc1f |
.BR execve (2)
|
|
|
96cc1f |
or when the process terminates.
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.BR mlockall ()
|
|
|
96cc1f |
+.B MCL_FUTURE
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.B MCL_FUTURE | MCL_ONFAULT
|
|
|
96cc1f |
+settings are not inherited by a child created via
|
|
|
96cc1f |
+.BR fork (2)
|
|
|
96cc1f |
+and are cleared during an
|
|
|
96cc1f |
+.BR execve (2).
|
|
|
96cc1f |
|
|
|
96cc1f |
The memory lock on an address range is automatically removed
|
|
|
96cc1f |
if the address range is unmapped via
|
|
|
96cc1f |
@@ -254,7 +347,8 @@ if the address range is unmapped via
|
|
|
96cc1f |
|
|
|
96cc1f |
Memory locks do not stack, that is, pages which have been locked several times
|
|
|
96cc1f |
by calls to
|
|
|
96cc1f |
-.BR mlock ()
|
|
|
96cc1f |
+.BR mlock (),
|
|
|
96cc1f |
+.BR mlock2 (),
|
|
|
96cc1f |
or
|
|
|
96cc1f |
.BR mlockall ()
|
|
|
96cc1f |
will be unlocked by a single call to
|
|
|
96cc1f |
@@ -264,15 +358,40 @@ for the corresponding range or by
|
|
|
96cc1f |
Pages which are mapped to several locations or by several processes stay
|
|
|
96cc1f |
locked into RAM as long as they are locked at least at one location or by
|
|
|
96cc1f |
at least one process.
|
|
|
96cc1f |
+
|
|
|
96cc1f |
+If a call to
|
|
|
96cc1f |
+.BR mlockall ()
|
|
|
96cc1f |
+which uses the
|
|
|
96cc1f |
+.B MCL_FUTURE
|
|
|
96cc1f |
+flag is followed by another call that does not specify this flag, the
|
|
|
96cc1f |
+changes made by the
|
|
|
96cc1f |
+.B MCL_FUTURE
|
|
|
96cc1f |
+call will be lost.
|
|
|
96cc1f |
+
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.BR mlock2 ()
|
|
|
96cc1f |
+.B MLOCK_ONFAULT
|
|
|
96cc1f |
+flag and the
|
|
|
96cc1f |
+.BR mlockall ()
|
|
|
96cc1f |
+.B MCL_ONFAULT
|
|
|
96cc1f |
+flag allow efficient memory locking for applications that deal with
|
|
|
96cc1f |
+large mappings where only a (small) portion of pages in the mapping are touched.
|
|
|
96cc1f |
+In such cases, locking all of the pages in a mapping would incur
|
|
|
96cc1f |
+a significant penalty for memory locking.
|
|
|
96cc1f |
.SS Linux notes
|
|
|
96cc1f |
Under Linux,
|
|
|
96cc1f |
-.BR mlock ()
|
|
|
96cc1f |
+.BR mlock (),
|
|
|
96cc1f |
+.BR mlock2 (),
|
|
|
96cc1f |
and
|
|
|
96cc1f |
.BR munlock ()
|
|
|
96cc1f |
automatically round
|
|
|
96cc1f |
.I addr
|
|
|
96cc1f |
down to the nearest page boundary.
|
|
|
96cc1f |
-However, POSIX.1-2001 allows an implementation to require that
|
|
|
96cc1f |
+However, the POSIX.1 specification of
|
|
|
96cc1f |
+.BR mlock ()
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.BR munlock ()
|
|
|
96cc1f |
+allows an implementation to require that
|
|
|
96cc1f |
.I addr
|
|
|
96cc1f |
is page aligned, so portable applications should ensure this.
|
|
|
96cc1f |
|
|
|
96cc1f |
@@ -284,6 +403,7 @@ file shows how many kilobytes of memory the process with ID
|
|
|
96cc1f |
.I PID
|
|
|
96cc1f |
has locked using
|
|
|
96cc1f |
.BR mlock (),
|
|
|
96cc1f |
+.BR mlock2 (),
|
|
|
96cc1f |
.BR mlockall (),
|
|
|
96cc1f |
and
|
|
|
96cc1f |
.BR mmap (2)
|
|
|
96cc1f |
--
|
|
|
96cc1f |
2.17.1
|
|
|
96cc1f |
|