1 .\" Copyright (C) Michael Kerrisk, 2004
2 .\" using some material drawn from earlier man pages
3 .\" written by Thomas Kuhn, Copyright 1996
5 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
6 .\" This is free documentation; you can redistribute it and/or
7 .\" modify it under the terms of the GNU General Public License as
8 .\" published by the Free Software Foundation; either version 2 of
9 .\" the License, or (at your option) any later version.
11 .\" The GNU General Public License's references to "object code"
12 .\" and "executables" are to be interpreted as the output of any
13 .\" document formatting or typesetting system, including
14 .\" intermediate and printed output.
16 .\" This manual is distributed in the hope that it will be useful,
17 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 .\" GNU General Public License for more details.
21 .\" You should have received a copy of the GNU General Public
22 .\" License along with this manual; if not, see
23 .\" <http://www.gnu.org/licenses/>.
26 .TH MLOCK 2 2015-08-28 "Linux" "Linux Programmer's Manual"
28 mlock, mlock2, munlock, mlockall, munlockall \- lock and unlock memory
31 .B #include <sys/mman.h>
33 .BI "int mlock(const void *" addr ", size_t " len );
34 .BI "int mlock2(const void *" addr ", size_t " len ", int " flags );
35 .BI "int munlock(const void *" addr ", size_t " len );
37 .BI "int mlockall(int " flags );
38 .B int munlockall(void);
45 respectively lock part or all of the calling process's virtual address
46 space into RAM, preventing that memory from being paged to the
51 perform the converse operation,
52 respectively unlocking part or all of the calling process's virtual
53 address space, so that pages in the specified virtual address range may
54 once more to be swapped out if required by the kernel memory manager.
55 Memory locking and unlocking are performed in units of whole pages.
56 .SS mlock(), mlock2(), and munlock()
58 locks pages in the address range starting at
63 All pages that contain a part of the specified address range are
64 guaranteed to be resident in RAM when the call returns successfully;
65 the pages are guaranteed to stay in RAM until later unlocked.
68 .\" commit a8ca5d0ecbdde5cc3d7accacbd69968b0c98764e
69 .\" commit de60f5f10c58d4f34b68622442c0e04180367f3f
70 .\" commit b0f205c2a3082dd9081f9a94e50658c5fa906ff1
71 also locks pages in the specified range starting at
76 However, the state of the pages contained in that range after the call
77 returns successfully will depend on the value in the
83 argument can be either 0 or the following constant:
86 Lock pages that are currently resident and mark the entire range to have
87 pages locked when they are populated by the page fault.
94 behaves exactly the same as
97 Note: currently, there is not a glibc wrapper for
99 so it will need to be invoked using
103 unlocks pages in the address range starting at
108 After this call, all pages that contain a part of the specified
109 memory range can be moved to external swap space again by the kernel.
110 .SS mlockall() and munlockall()
112 locks all pages mapped into the address space of the
114 This includes the pages of the code, data and stack
115 segment, as well as shared libraries, user space kernel data, shared
116 memory, and memory-mapped files.
117 All mapped pages are guaranteed
118 to be resident in RAM when the call returns successfully;
119 the pages are guaranteed to stay in RAM until later unlocked.
123 argument is constructed as the bitwise OR of one or more of the
127 Lock all pages which are currently mapped into the address space of
131 Lock all pages which will become mapped into the address space of the
132 process in the future.
133 These could be, for instance, new pages required
134 by a growing heap and stack as well as new memory-mapped files or
135 shared memory regions.
137 .BR MCL_ONFAULT " (since Linux 4.4)"
142 Mark all current (with
146 mappings to lock pages when they are faulted in.
149 all present pages are locked, but
151 will not fault in non-present pages.
154 all future mappings will be marked to lock pages when they are faulted
155 in, but they will not be populated by the lock when the mapping is
158 must be used with either
166 has been specified, then a later system call (e.g.,
170 may fail if it would cause the number of locked bytes to exceed
171 the permitted maximum (see below).
172 In the same circumstances, stack growth may likewise fail:
173 the kernel will deny stack expansion and deliver a
175 signal to the process.
178 unlocks all pages mapped into the address space of the
181 On success, these system calls return 0.
182 On error, \-1 is returned,
184 is set appropriately, and no changes are made to any locks in the
185 address space of the process.
189 (Linux 2.6.9 and later) the caller had a nonzero
191 soft resource limit, but tried to lock more memory than the limit
193 This limit is not enforced if the process is privileged
194 .RB ( CAP_IPC_LOCK ).
197 (Linux 2.4 and earlier) the calling process tried to lock more than
199 .\" In the case of mlock(), this check is somewhat buggy: it doesn't
200 .\" take into account whether the to-be-locked range overlaps with
201 .\" already locked pages. Thus, suppose we allocate
202 .\" (num_physpages / 4 + 1) of memory, and lock those pages once using
203 .\" mlock(), and then lock the *same* page range a second time.
204 .\" In the case, the second mlock() call will fail, since the check
205 .\" calculates that the process is trying to lock (num_physpages / 2 + 2)
206 .\" pages, which of course is not true. (MTK, Nov 04, kernel 2.4.28)
209 The caller is not privileged, but needs privilege
211 to perform the requested operation.
212 .\"SVr4 documents an additional EAGAIN error code.
221 Some or all of the specified address range could not be locked.
224 The result of the addition
228 (e.g., the addition may have resulted in an overflow).
233 was not a multiple of the page size.
236 Some of the specified address range does not correspond to mapped
237 pages in the address space of the process.
240 Locking or unlocking a region would result in the total number of
241 mappings with distinct attributes (e.g., locked versus unlocked)
242 exceeding the allowed maximum.
243 .\" I.e., the number of VMAs would exceed the 64kB maximum
244 (For example, unlocking a range in the middle of a currently locked
245 mapping would result in three mappings:
246 two locked mappings at each end and an unlocked mapping in the middle.)
252 Unknown \fIflags\fP were specified.
258 Unknown \fIflags\fP were specified or
260 was specified without either
269 (Linux 2.6.8 and earlier) The caller was not privileged
270 .RB ( CAP_IPC_LOCK ).
273 is available since Linux 4.4.
275 POSIX.1-2001, POSIX.1-2008, SVr4.
277 On POSIX systems on which
282 .B _POSIX_MEMLOCK_RANGE
283 is defined in \fI<unistd.h>\fP and the number of bytes in a page
284 can be determined from the constant
286 (if defined) in \fI<limits.h>\fP or by calling
287 .IR sysconf(_SC_PAGESIZE) .
289 On POSIX systems on which
295 is defined in \fI<unistd.h>\fP to a value greater than 0.
298 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
299 .\" -1: unavailable, 0: ask using sysconf().
300 .\" glibc defines it to 1.
302 Memory locking has two main applications: real-time algorithms and
303 high-security data processing.
304 Real-time applications require
305 deterministic timing, and, like scheduling, paging is one major cause
306 of unexpected program execution delays.
307 Real-time applications will
308 usually also switch to a real-time scheduler with
309 .BR sched_setscheduler (2).
310 Cryptographic security software often handles critical bytes like
311 passwords or secret keys as data structures.
312 As a result of paging,
313 these secrets could be transferred onto a persistent swap store medium,
314 where they might be accessible to the enemy long after the security
315 software has erased the secrets in RAM and terminated.
316 (But be aware that the suspend mode on laptops and some desktop
317 computers will save a copy of the system's RAM to disk, regardless
320 Real-time processes that are using
322 to prevent delays on page faults should reserve enough
323 locked stack pages before entering the time-critical section,
324 so that no page fault can be caused by function calls.
325 This can be achieved by calling a function that allocates a
326 sufficiently large automatic variable (an array) and writes to the
327 memory occupied by this array in order to touch these stack pages.
328 This way, enough pages will be mapped for the stack and can be
330 The dummy writes ensure that not even copy-on-write
331 page faults can occur in the critical section.
333 Memory locks are not inherited by a child created via
335 and are automatically removed (unlocked) during an
337 or when the process terminates.
342 .B MCL_FUTURE | MCL_ONFAULT
343 settings are not inherited by a child created via
345 and are cleared during an
348 The memory lock on an address range is automatically removed
349 if the address range is unmapped via
352 Memory locks do not stack, that is, pages which have been locked several times
358 will be unlocked by a single call to
360 for the corresponding range or by
362 Pages which are mapped to several locations or by several processes stay
363 locked into RAM as long as they are locked at least at one location or by
364 at least one process.
370 flag is followed by another call that does not specify this flag, the
382 down to the nearest page boundary.
383 However, the POSIX.1 specification of
387 allows an implementation to require that
389 is page aligned, so portable applications should ensure this.
393 field of the Linux-specific
395 file shows how many kilobytes of memory the process with ID
404 .SS Limits and permissions
405 In Linux 2.6.8 and earlier,
406 a process must be privileged
408 in order to lock memory and the
410 soft resource limit defines a limit on how much memory the process may lock.
412 Since Linux 2.6.9, no limits are placed on the amount of memory
413 that a privileged process can lock and the
415 soft resource limit instead defines a limit on how much memory an
416 unprivileged process may lock.
418 In the 2.4 series Linux kernels up to and including 2.4.17,
422 flag to be inherited across a
424 This was rectified in kernel 2.4.18.
426 Since kernel 2.6.9, if a privileged process calls
427 .I mlockall(MCL_FUTURE)
428 and later drops privileges (loses the
430 capability by, for example,
431 setting its effective UID to a nonzero value),
432 then subsequent memory allocations (e.g.,
437 resource limit is encountered.
438 .\" See the following LKML thread:
439 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2
440 .\" "Rationale for RLIMIT_MEMLOCK"