1 .\" Copyright (C) Michael Kerrisk, 2004
2 .\" using some material drawn from earlier man pages
3 .\" written by Thomas Kuhn, Copyright 1996
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
7 .TH MLOCK 2 2021-08-27 "Linux man-pages (unreleased)"
9 mlock, mlock2, munlock, mlockall, munlockall \- lock and unlock memory
12 .RI ( libc ", " \-lc )
15 .B #include <sys/mman.h>
17 .BI "int mlock(const void *" addr ", size_t " len );
18 .BI "int mlock2(const void *" addr ", size_t " len ", unsigned int " flags );
19 .BI "int munlock(const void *" addr ", size_t " len );
21 .BI "int mlockall(int " flags );
22 .B int munlockall(void);
29 lock part or all of the calling process's virtual address
30 space into RAM, preventing that memory from being paged to the
36 perform the converse operation,
37 unlocking part or all of the calling process's virtual
38 address space, so that pages in the specified virtual address range may
39 once more to be swapped out if required by the kernel memory manager.
41 Memory locking and unlocking are performed in units of whole pages.
42 .SS mlock(), mlock2(), and munlock()
44 locks pages in the address range starting at
49 All pages that contain a part of the specified address range are
50 guaranteed to be resident in RAM when the call returns successfully;
51 the pages are guaranteed to stay in RAM until later unlocked.
54 .\" commit a8ca5d0ecbdde5cc3d7accacbd69968b0c98764e
55 .\" commit de60f5f10c58d4f34b68622442c0e04180367f3f
56 .\" commit b0f205c2a3082dd9081f9a94e50658c5fa906ff1
57 also locks pages in the specified range starting at
62 However, the state of the pages contained in that range after the call
63 returns successfully will depend on the value in the
69 argument can be either 0 or the following constant:
72 Lock pages that are currently resident and mark the entire range so
73 that the remaining nonresident pages are locked when they are populated
80 behaves exactly the same as
84 unlocks pages in the address range starting at
89 After this call, all pages that contain a part of the specified
90 memory range can be moved to external swap space again by the kernel.
91 .SS mlockall() and munlockall()
93 locks all pages mapped into the address space of the
95 This includes the pages of the code, data, and stack
96 segment, as well as shared libraries, user space kernel data, shared
97 memory, and memory-mapped files.
98 All mapped pages are guaranteed
99 to be resident in RAM when the call returns successfully;
100 the pages are guaranteed to stay in RAM until later unlocked.
104 argument is constructed as the bitwise OR of one or more of the
108 Lock all pages which are currently mapped into the address space of
112 Lock all pages which will become mapped into the address space of the
113 process in the future.
114 These could be, for instance, new pages required
115 by a growing heap and stack as well as new memory-mapped files or
116 shared memory regions.
118 .BR MCL_ONFAULT " (since Linux 4.4)"
123 Mark all current (with
127 mappings to lock pages when they are faulted in.
130 all present pages are locked, but
132 will not fault in non-present pages.
135 all future mappings will be marked to lock pages when they are faulted
136 in, but they will not be populated by the lock when the mapping is
139 must be used with either
147 has been specified, then a later system call (e.g.,
151 may fail if it would cause the number of locked bytes to exceed
152 the permitted maximum (see below).
153 In the same circumstances, stack growth may likewise fail:
154 the kernel will deny stack expansion and deliver a
156 signal to the process.
159 unlocks all pages mapped into the address space of the
162 On success, these system calls return 0.
163 On error, \-1 is returned,
165 is set to indicate the error,
166 and no changes are made to any locks in the
167 address space of the process.
169 .\"SVr4 documents an additional EAGAIN error code.
176 Some or all of the specified address range could not be locked.
183 The result of the addition
187 (e.g., the addition may have resulted in an overflow).
191 Unknown \fIflags\fP were specified.
195 Unknown \fIflags\fP were specified or
197 was specified without either
205 was not a multiple of the page size.
212 Some of the specified address range does not correspond to mapped
213 pages in the address space of the process.
220 Locking or unlocking a region would result in the total number of
221 mappings with distinct attributes (e.g., locked versus unlocked)
222 exceeding the allowed maximum.
223 .\" I.e., the number of VMAs would exceed the 64kB maximum
224 (For example, unlocking a range in the middle of a currently locked
225 mapping would result in three mappings:
226 two locked mappings at each end and an unlocked mapping in the middle.)
229 (Linux 2.6.9 and later) the caller had a nonzero
231 soft resource limit, but tried to lock more memory than the limit
233 This limit is not enforced if the process is privileged
234 .RB ( CAP_IPC_LOCK ).
237 (Linux 2.4 and earlier) the calling process tried to lock more than
239 .\" In the case of mlock(), this check is somewhat buggy: it doesn't
240 .\" take into account whether the to-be-locked range overlaps with
241 .\" already locked pages. Thus, suppose we allocate
242 .\" (num_physpages / 4 + 1) of memory, and lock those pages once using
243 .\" mlock(), and then lock the *same* page range a second time.
244 .\" In the case, the second mlock() call will fail, since the check
245 .\" calculates that the process is trying to lock (num_physpages / 2 + 2)
246 .\" pages, which of course is not true. (MTK, Nov 04, kernel 2.4.28)
249 The caller is not privileged, but needs privilege
251 to perform the requested operation.
255 (Linux 2.6.8 and earlier) The caller was not privileged
256 .RB ( CAP_IPC_LOCK ).
259 is available since Linux 4.4;
260 glibc support was added in version 2.27.
267 POSIX.1-2001, POSIX.1-2008, SVr4.
272 On POSIX systems on which
277 .B _POSIX_MEMLOCK_RANGE
278 is defined in \fI<unistd.h>\fP and the number of bytes in a page
279 can be determined from the constant
281 (if defined) in \fI<limits.h>\fP or by calling
282 .IR sysconf(_SC_PAGESIZE) .
284 On POSIX systems on which
290 is defined in \fI<unistd.h>\fP to a value greater than 0.
293 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
294 .\" -1: unavailable, 0: ask using sysconf().
295 .\" glibc defines it to 1.
297 Memory locking has two main applications: real-time algorithms and
298 high-security data processing.
299 Real-time applications require
300 deterministic timing, and, like scheduling, paging is one major cause
301 of unexpected program execution delays.
302 Real-time applications will
303 usually also switch to a real-time scheduler with
304 .BR sched_setscheduler (2).
305 Cryptographic security software often handles critical bytes like
306 passwords or secret keys as data structures.
307 As a result of paging,
308 these secrets could be transferred onto a persistent swap store medium,
309 where they might be accessible to the enemy long after the security
310 software has erased the secrets in RAM and terminated.
311 (But be aware that the suspend mode on laptops and some desktop
312 computers will save a copy of the system's RAM to disk, regardless
315 Real-time processes that are using
317 to prevent delays on page faults should reserve enough
318 locked stack pages before entering the time-critical section,
319 so that no page fault can be caused by function calls.
320 This can be achieved by calling a function that allocates a
321 sufficiently large automatic variable (an array) and writes to the
322 memory occupied by this array in order to touch these stack pages.
323 This way, enough pages will be mapped for the stack and can be
325 The dummy writes ensure that not even copy-on-write
326 page faults can occur in the critical section.
328 Memory locks are not inherited by a child created via
330 and are automatically removed (unlocked) during an
332 or when the process terminates.
337 .B MCL_FUTURE | MCL_ONFAULT
338 settings are not inherited by a child created via
340 and are cleared during an
345 will prepare the address space for a copy-on-write operation.
346 The consequence is that any write access that follows will cause
347 a page fault that in turn may cause high latencies for a real-time process.
348 Therefore, it is crucial not to invoke
354 operation\(emnot even from a thread which runs at a low priority within
355 a process which also has a thread running at elevated priority.
357 The memory lock on an address range is automatically removed
358 if the address range is unmapped via
361 Memory locks do not stack, that is, pages which have been locked several times
367 will be unlocked by a single call to
369 for the corresponding range or by
371 Pages which are mapped to several locations or by several processes stay
372 locked into RAM as long as they are locked at least at one location or by
373 at least one process.
379 flag is followed by another call that does not specify this flag, the
390 flag allow efficient memory locking for applications that deal with
391 large mappings where only a (small) portion of pages in the mapping are touched.
392 In such cases, locking all of the pages in a mapping would incur
393 a significant penalty for memory locking.
402 down to the nearest page boundary.
403 However, the POSIX.1 specification of
407 allows an implementation to require that
409 is page aligned, so portable applications should ensure this.
413 field of the Linux-specific
414 .I /proc/[pid]/status
415 file shows how many kilobytes of memory the process with ID
424 .SS Limits and permissions
425 In Linux 2.6.8 and earlier,
426 a process must be privileged
428 in order to lock memory and the
430 soft resource limit defines a limit on how much memory the process may lock.
432 Since Linux 2.6.9, no limits are placed on the amount of memory
433 that a privileged process can lock and the
435 soft resource limit instead defines a limit on how much memory an
436 unprivileged process may lock.
438 In Linux 4.8 and earlier,
439 a bug in the kernel's accounting of locked memory for unprivileged processes
442 meant that if the region specified by
446 overlapped an existing lock,
447 then the already locked bytes in the overlapping region were counted twice
448 when checking against the limit.
449 Such double accounting could incorrectly calculate a "total locked memory"
450 value for the process that exceeded the
452 limit, with the result that
456 would fail on requests that should have succeeded.
458 .\" commit 0cf2f6f6dc605e587d2c1120f295934c77e810e8
461 In the 2.4 series Linux kernels up to and including 2.4.17,
465 flag to be inherited across a
467 This was rectified in kernel 2.4.18.
469 Since kernel 2.6.9, if a privileged process calls
470 .I mlockall(MCL_FUTURE)
471 and later drops privileges (loses the
473 capability by, for example,
474 setting its effective UID to a nonzero value),
475 then subsequent memory allocations (e.g.,
480 resource limit is encountered.
481 .\" See the following LKML thread:
482 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2
483 .\" "Rationale for RLIMIT_MEMLOCK"
projects / thirdparty / man-pages.git / blob