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 2014-04-14 "Linux" "Linux Programmer's Manual"
28 mlock, 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 munlock(const void *" addr ", size_t " len );
36 .BI "int mlockall(int " flags );
37 .B int munlockall(void);
43 respectively lock part or all of the calling process's virtual address
44 space into RAM, preventing that memory from being paged to the
49 perform the converse operation,
50 respectively unlocking part or all of the calling process's virtual
51 address space, so that pages in the specified virtual address range may
52 once more to be swapped out if required by the kernel memory manager.
53 Memory locking and unlocking are performed in units of whole pages.
54 .SS mlock() and munlock()
56 locks pages in the address range starting at
61 All pages that contain a part of the specified address range are
62 guaranteed to be resident in RAM when the call returns successfully;
63 the pages are guaranteed to stay in RAM until later unlocked.
66 unlocks pages in the address range starting at
71 After this call, all pages that contain a part of the specified
72 memory range can be moved to external swap space again by the kernel.
73 .SS mlockall() and munlockall()
75 locks all pages mapped into the address space of the
77 This includes the pages of the code, data and stack
78 segment, as well as shared libraries, user space kernel data, shared
79 memory, and memory-mapped files.
80 All mapped pages are guaranteed
81 to be resident in RAM when the call returns successfully;
82 the pages are guaranteed to stay in RAM until later unlocked.
86 argument is constructed as the bitwise OR of one or more of the
90 Lock all pages which are currently mapped into the address space of
94 Lock all pages which will become mapped into the address space of the
95 process in the future.
96 These could be for instance new pages required
97 by a growing heap and stack as well as new memory-mapped files or
98 shared memory regions.
102 has been specified, then a later system call (e.g.,
106 may fail if it would cause the number of locked bytes to exceed
107 the permitted maximum (see below).
108 In the same circumstances, stack growth may likewise fail:
109 the kernel will deny stack expansion and deliver a
111 signal to the process.
114 unlocks all pages mapped into the address space of the
117 On success these system calls return 0.
118 On error, \-1 is returned,
120 is set appropriately, and no changes are made to any locks in the
121 address space of the process.
125 (Linux 2.6.9 and later) the caller had a nonzero
127 soft resource limit, but tried to lock more memory than the limit
129 This limit is not enforced if the process is privileged
130 .RB ( CAP_IPC_LOCK ).
133 (Linux 2.4 and earlier) the calling process tried to lock more than
135 .\" In the case of mlock(), this check is somewhat buggy: it doesn't
136 .\" take into account whether the to-be-locked range overlaps with
137 .\" already locked pages. Thus, suppose we allocate
138 .\" (num_physpages / 4 + 1) of memory, and lock those pages once using
139 .\" mlock(), and then lock the *same* page range a second time.
140 .\" In the case, the second mlock() call will fail, since the check
141 .\" calculates that the process is trying to lock (num_physpages / 2 + 2)
142 .\" pages, which of course is not true. (MTK, Nov 04, kernel 2.4.28)
145 The caller is not privileged, but needs privilege
147 to perform the requested operation.
148 .\"SVr4 documents an additional EAGAIN error code.
156 Some or all of the specified address range could not be locked.
159 The result of the addition
163 (e.g., the addition may have resulted in an overflow).
168 was not a multiple of the page size.
171 Some of the specified address range does not correspond to mapped
172 pages in the address space of the process.
178 Unknown \fIflags\fP were specified.
184 (Linux 2.6.8 and earlier) The caller was not privileged
185 .RB ( CAP_IPC_LOCK ).
189 On POSIX systems on which
194 .B _POSIX_MEMLOCK_RANGE
195 is defined in \fI<unistd.h>\fP and the number of bytes in a page
196 can be determined from the constant
198 (if defined) in \fI<limits.h>\fP or by calling
199 .IR sysconf(_SC_PAGESIZE) .
201 On POSIX systems on which
207 is defined in \fI<unistd.h>\fP to a value greater than 0.
210 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
211 .\" -1: unavailable, 0: ask using sysconf().
212 .\" glibc defines it to 1.
214 Memory locking has two main applications: real-time algorithms and
215 high-security data processing.
216 Real-time applications require
217 deterministic timing, and, like scheduling, paging is one major cause
218 of unexpected program execution delays.
219 Real-time applications will
220 usually also switch to a real-time scheduler with
221 .BR sched_setscheduler (2).
222 Cryptographic security software often handles critical bytes like
223 passwords or secret keys as data structures.
224 As a result of paging,
225 these secrets could be transferred onto a persistent swap store medium,
226 where they might be accessible to the enemy long after the security
227 software has erased the secrets in RAM and terminated.
228 (But be aware that the suspend mode on laptops and some desktop
229 computers will save a copy of the system's RAM to disk, regardless
232 Real-time processes that are using
234 to prevent delays on page faults should reserve enough
235 locked stack pages before entering the time-critical section,
236 so that no page fault can be caused by function calls.
237 This can be achieved by calling a function that allocates a
238 sufficiently large automatic variable (an array) and writes to the
239 memory occupied by this array in order to touch these stack pages.
240 This way, enough pages will be mapped for the stack and can be
242 The dummy writes ensure that not even copy-on-write
243 page faults can occur in the critical section.
245 Memory locks are not inherited by a child created via
247 and are automatically removed (unlocked) during an
249 or when the process terminates.
253 setting is not inherited by a child created via
255 and is cleared during an
258 The memory lock on an address range is automatically removed
259 if the address range is unmapped via
262 Memory locks do not stack, that is, pages which have been locked several times
267 will be unlocked by a single call to
269 for the corresponding range or by
271 Pages which are mapped to several locations or by several processes stay
272 locked into RAM as long as they are locked at least at one location or by
273 at least one process.
281 down to the nearest page boundary.
282 However, POSIX.1-2001 allows an implementation to require that
284 is page aligned, so portable applications should ensure this.
288 field of the Linux-specific
290 file shows how many kilobytes of memory the process with ID
298 .SS Limits and permissions
299 In Linux 2.6.8 and earlier,
300 a process must be privileged
302 in order to lock memory and the
304 soft resource limit defines a limit on how much memory the process may lock.
306 Since Linux 2.6.9, no limits are placed on the amount of memory
307 that a privileged process can lock and the
309 soft resource limit instead defines a limit on how much memory an
310 unprivileged process may lock.
312 In the 2.4 series Linux kernels up to and including 2.4.17,
316 flag to be inherited across a
318 This was rectified in kernel 2.4.18.
320 Since kernel 2.6.9, if a privileged process calls
321 .I mlockall(MCL_FUTURE)
322 and later drops privileges (loses the
324 capability by, for example,
325 setting its effective UID to a nonzero value),
326 then subsequent memory allocations (e.g.,
331 resource limit is encountered.
332 .\" See the following LKML thread:
333 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2
334 .\" "Rationale for RLIMIT_MEMLOCK"
344 This page is part of release 3.68 of the Linux
347 A description of the project,
348 information about reporting bugs,
349 and the latest version of this page,
351 \%http://www.kernel.org/doc/man\-pages/.