mirror of https://github.com/mkerrisk/man-pages
mlock.2, mlock2.2: Document mlock2(2) and MCL_ONFAULT
Update the mlock(2) man page with information on mlock2() and the new mlockall() flag MCL_ONFAULT. Signed-off-by: Eric B Munson <emunson@akamai.com> Acked-by: Michal Hocko <mhocko@suse.com> Acked-by: Vlastimil Babka <vbabka@suse.cz> Cc: Michal Hocko <mhocko@suse.cz> Cc: Vlastimil Babka <vbabka@suse.cz> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-man@vger.kernel.org Cc: linux-mm@kvack.org Cc: linux-kernel@vger.kernel.org Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
454ab8725b
commit
7a3e8caae4
110
man2/mlock.2
110
man2/mlock.2
|
@ -23,21 +23,23 @@
|
||||||
.\" <http://www.gnu.org/licenses/>.
|
.\" <http://www.gnu.org/licenses/>.
|
||||||
.\" %%%LICENSE_END
|
.\" %%%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
|
.SH NAME
|
||||||
mlock, munlock, mlockall, munlockall \- lock and unlock memory
|
mlock, mlock2, munlock, mlockall, munlockall \- lock and unlock memory
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.nf
|
.nf
|
||||||
.B #include <sys/mman.h>
|
.B #include <sys/mman.h>
|
||||||
.sp
|
.sp
|
||||||
.BI "int mlock(const void *" addr ", size_t " len );
|
.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 );
|
.BI "int munlock(const void *" addr ", size_t " len );
|
||||||
.sp
|
.sp
|
||||||
.BI "int mlockall(int " flags );
|
.BI "int mlockall(int " flags );
|
||||||
.B int munlockall(void);
|
.B int munlockall(void);
|
||||||
.fi
|
.fi
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
.BR mlock ()
|
.BR mlock (),
|
||||||
|
.BR mlock2 (),
|
||||||
and
|
and
|
||||||
.BR mlockall ()
|
.BR mlockall ()
|
||||||
respectively lock part or all of the calling process's virtual address
|
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
|
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.
|
once more to be swapped out if required by the kernel memory manager.
|
||||||
Memory locking and unlocking are performed in units of whole pages.
|
Memory locking and unlocking are performed in units of whole pages.
|
||||||
.SS mlock() and munlock()
|
.SS mlock(), mlock2(), and munlock()
|
||||||
.BR mlock ()
|
.BR mlock ()
|
||||||
locks pages in the address range starting at
|
locks pages in the address range starting at
|
||||||
.I addr
|
.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;
|
guaranteed to be resident in RAM when the call returns successfully;
|
||||||
the pages are guaranteed to stay in RAM until later unlocked.
|
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 ()
|
.BR munlock ()
|
||||||
unlocks pages in the address range starting at
|
unlocks pages in the address range starting at
|
||||||
.I addr
|
.I addr
|
||||||
|
@ -93,9 +128,33 @@ the process.
|
||||||
.B MCL_FUTURE
|
.B MCL_FUTURE
|
||||||
Lock all pages which will become mapped into the address space of the
|
Lock all pages which will become mapped into the address space of the
|
||||||
process in the future.
|
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
|
by a growing heap and stack as well as new memory-mapped files or
|
||||||
shared memory regions.
|
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
|
.PP
|
||||||
If
|
If
|
||||||
.B MCL_FUTURE
|
.B MCL_FUTURE
|
||||||
|
@ -148,7 +207,8 @@ to perform the requested operation.
|
||||||
.\"SVr4 documents an additional EAGAIN error code.
|
.\"SVr4 documents an additional EAGAIN error code.
|
||||||
.LP
|
.LP
|
||||||
For
|
For
|
||||||
.BR mlock ()
|
.BR mlock (),
|
||||||
|
.BR mlock2 (),
|
||||||
and
|
and
|
||||||
.BR munlock ():
|
.BR munlock ():
|
||||||
.TP
|
.TP
|
||||||
|
@ -181,12 +241,23 @@ mapping would result in three mappings:
|
||||||
two locked mappings at each end and an unlocked mapping in the middle.)
|
two locked mappings at each end and an unlocked mapping in the middle.)
|
||||||
.LP
|
.LP
|
||||||
For
|
For
|
||||||
.BR mlockall ():
|
.BR mlock2 ():
|
||||||
.TP
|
.TP
|
||||||
.B EINVAL
|
.B EINVAL
|
||||||
Unknown \fIflags\fP were specified.
|
Unknown \fIflags\fP were specified.
|
||||||
.LP
|
.LP
|
||||||
For
|
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 ():
|
.BR munlockall ():
|
||||||
.TP
|
.TP
|
||||||
.B EPERM
|
.B EPERM
|
||||||
|
@ -259,9 +330,11 @@ or when the process terminates.
|
||||||
The
|
The
|
||||||
.BR mlockall ()
|
.BR mlockall ()
|
||||||
.B MCL_FUTURE
|
.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)
|
.BR fork (2)
|
||||||
and is cleared during an
|
and are cleared during an
|
||||||
.BR execve (2).
|
.BR execve (2).
|
||||||
|
|
||||||
The memory lock on an address range is automatically removed
|
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
|
Memory locks do not stack, that is, pages which have been locked several times
|
||||||
by calls to
|
by calls to
|
||||||
.BR mlock ()
|
.BR mlock (),
|
||||||
|
.BR mlock2 (),
|
||||||
or
|
or
|
||||||
.BR mlockall ()
|
.BR mlockall ()
|
||||||
will be unlocked by a single call to
|
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
|
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
|
locked into RAM as long as they are locked at least at one location or by
|
||||||
at least one process.
|
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
|
.SS Linux notes
|
||||||
Under Linux,
|
Under Linux,
|
||||||
.BR mlock ()
|
.BR mlock (),
|
||||||
|
.BR mlock2 (),
|
||||||
and
|
and
|
||||||
.BR munlock ()
|
.BR munlock ()
|
||||||
automatically round
|
automatically round
|
||||||
|
@ -300,6 +384,7 @@ file shows how many kilobytes of memory the process with ID
|
||||||
.I PID
|
.I PID
|
||||||
has locked using
|
has locked using
|
||||||
.BR mlock (),
|
.BR mlock (),
|
||||||
|
.BR mlock2 (),
|
||||||
.BR mlockall (),
|
.BR mlockall (),
|
||||||
and
|
and
|
||||||
.BR mmap (2)
|
.BR mmap (2)
|
||||||
|
@ -342,6 +427,9 @@ resource limit is encountered.
|
||||||
.\" http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2
|
.\" http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2
|
||||||
.\" "Rationale for RLIMIT_MEMLOCK"
|
.\" "Rationale for RLIMIT_MEMLOCK"
|
||||||
.\" 23 Jan 2006
|
.\" 23 Jan 2006
|
||||||
|
.SH VERSIONS
|
||||||
|
.BR mlock2 (2)
|
||||||
|
is available since Linux 4.4.
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
.BR mmap (2),
|
.BR mmap (2),
|
||||||
.BR setrlimit (2),
|
.BR setrlimit (2),
|
||||||
|
|
|
@ -0,0 +1 @@
|
||||||
|
.so man2/mlock.2
|
Loading…
Reference in New Issue