Debian Codegraph @

upstream/debian-unstable/man2/mlock.2

raw
1 .\" Copyright 1996, Thomas Kuhn
2 .\" Copyright 2004, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH mlock 2 2026-02-11 "Linux man-pages 6.18"
8 .SH NAME
9 mlock, mlock2, munlock, mlockall, munlockall \- lock and unlock memory
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <sys/mman.h>
16 .P
17 .BR "int mlock(" "size_t size;"
18 .BI " const void " addr [ size "], size_t " size );
19 .BR "int mlock2(" "size_t size;"
20 .BI " const void " addr [ size "], size_t " size ", unsigned int " flags );
21 .BR "int munlock(" "size_t size;"
22 .BI " const void " addr [ size "], size_t " size );
23 .P
24 .BI "int mlockall(int " flags );
25 .B int munlockall(void);
26 .fi
27 .SH DESCRIPTION
28 .BR mlock (),
29 .BR mlock2 (),
30 and
31 .BR mlockall ()
32 lock part or all of the calling process's virtual address
33 space into RAM, preventing that memory from being paged to the
34 swap area.
35 .P
36 .BR munlock ()
37 and
38 .BR munlockall ()
39 perform the converse operation,
40 unlocking part or all of the calling process's virtual address space,
41 so that pages in the specified virtual address range
42 can be swapped out again if required by the kernel memory manager.
43 .P
44 Memory locking and unlocking are performed in units of whole pages.
45 .SS mlock(), mlock2(), and munlock()
46 .BR mlock ()
47 locks pages in the address range starting at
48 .I addr
49 and continuing for
50 .I size
51 bytes.
52 All pages that contain a part of the specified address range are
53 guaranteed to be resident in RAM when the call returns successfully;
54 the pages are guaranteed to stay in RAM until later unlocked.
55 .P
56 .BR mlock2 ()
57 .\" commit a8ca5d0ecbdde5cc3d7accacbd69968b0c98764e
58 .\" commit de60f5f10c58d4f34b68622442c0e04180367f3f
59 .\" commit b0f205c2a3082dd9081f9a94e50658c5fa906ff1
60 also locks pages in the specified range starting at
61 .I addr
62 and continuing for
63 .I size
64 bytes.
65 However, the state of the pages contained in that range after the call
66 returns successfully will depend on the value in the
67 .I flags
68 argument.
69 .P
70 The
71 .I flags
72 argument can be either 0 or the following constant:
73 .TP
74 .B MLOCK_ONFAULT
75 Lock pages that are currently resident and mark the entire range so
76 that the remaining nonresident pages are locked when they are populated
77 by a page fault.
78 .P
79 If
80 .I flags
81 is 0,
82 .BR mlock2 ()
83 behaves exactly the same as
84 .BR mlock ().
85 .P
86 .BR munlock ()
87 unlocks pages in the address range starting at
88 .I addr
89 and continuing for
90 .I size
91 bytes.
92 After this call, all pages that contain a part of the specified
93 memory range can be moved to external swap space again by the kernel.
94 .SS mlockall() and munlockall()
95 .BR mlockall ()
96 locks all pages mapped into the address space of the
97 calling process.
98 This includes the pages of the code, data, and stack
99 segment, as well as shared libraries, user space kernel data, shared
100 memory, and memory-mapped files.
101 All mapped pages are guaranteed
102 to be resident in RAM when the call returns successfully;
103 the pages are guaranteed to stay in RAM until later unlocked.
104 .P
105 The
106 .I flags
107 argument is constructed as the bitwise OR of one or more of the
108 following constants:
109 .TP
110 .B MCL_CURRENT
111 Lock all pages which are currently mapped into the address space of
112 the process.
113 .TP
114 .B MCL_FUTURE
115 Lock all pages which will become mapped into the address space of the
116 process in the future.
117 These could be, for instance, new pages required
118 by a growing heap and stack as well as new memory-mapped files or
119 shared memory regions.
120 .TP
121 .BR MCL_ONFAULT " (since Linux 4.4)"
122 Used together with
123 .BR MCL_CURRENT ,
124 .BR MCL_FUTURE ,
125 or both.
126 Mark all current (with
127 .BR MCL_CURRENT )
128 or future (with
129 .BR MCL_FUTURE )
130 mappings to lock pages when they are faulted in.
131 When used with
132 .BR MCL_CURRENT ,
133 all present pages are locked, but
134 .BR mlockall ()
135 will not fault in non-present pages.
136 When used with
137 .BR MCL_FUTURE ,
138 all future mappings will be marked to lock pages when they are faulted
139 in, but they will not be populated by the lock when the mapping is
140 created.
141 .B MCL_ONFAULT
142 must be used with either
143 .B MCL_CURRENT
144 or
145 .B MCL_FUTURE
146 or both.
147 .P
148 If
149 .B MCL_FUTURE
150 has been specified, then a later system call (e.g.,
151 .BR mmap (2),
152 .BR sbrk (2),
153 .BR malloc (3)),
154 may fail if it would cause the number of locked bytes to exceed
155 the permitted maximum (see below).
156 In the same circumstances, stack growth may likewise fail:
157 the kernel will deny stack expansion and deliver a
158 .B SIGSEGV
159 signal to the process.
160 .P
161 .BR munlockall ()
162 unlocks all pages mapped into the address space of the
163 calling process.
164 .SH RETURN VALUE
165 On success, these system calls return 0.
166 On error, \-1 is returned,
167 .I errno
168 is set to indicate the error,
169 and no changes are made to any locks in the
170 address space of the process.
171 .SH ERRORS
172 .\"SVr4 documents an additional EAGAIN error code.
173 .TP
174 .B EAGAIN
175 .RB ( mlock (),
176 .BR mlock2 (),
177 and
178 .BR munlock ())
179 Some or all of the specified address range could not be locked.
180 .TP
181 .B EINVAL
182 .RB ( mlock (),
183 .BR mlock2 (),
184 and
185 .BR munlock ())
186 The result of the addition
187 .IR addr + size
188 was less than
189 .I addr
190 (e.g., the addition may have resulted in an overflow).
191 .TP
192 .B EINVAL
193 .RB ( mlock2 ())
194 Unknown
195 .I flags
196 were specified.
197 .TP
198 .B EINVAL
199 .RB ( mlockall ())
200 Unknown
201 .I flags
202 were specified or
203 .B MCL_ONFAULT
204 was specified without either
205 .B MCL_FUTURE
206 or
207 .BR MCL_CURRENT .
208 .TP
209 .B EINVAL
210 (Not on Linux)
211 .I addr
212 was not a multiple of the page size.
213 .TP
214 .B ENOMEM
215 .RB ( mlock (),
216 .BR mlock2 (),
217 and
218 .BR munlock ())
219 Some of the specified address range does not correspond to mapped
220 pages in the address space of the process.
221 .TP
222 .B ENOMEM
223 .RB ( mlock (),
224 .BR mlock2 (),
225 and
226 .BR munlock ())
227 Locking or unlocking a region would result in the total number of
228 mappings with distinct attributes (e.g., locked versus unlocked)
229 exceeding the allowed maximum.
230 .\" I.e., the number of VMAs would exceed the 64kB maximum
231 (For example, unlocking a range in the middle of a currently locked
232 mapping would result in three mappings:
233 two locked mappings at each end and an unlocked mapping in the middle.)
234 .TP
235 .B ENOMEM
236 (Linux 2.6.9 and later) the caller had a nonzero
237 .B RLIMIT_MEMLOCK
238 soft resource limit, but tried to lock more memory than the limit
239 permitted.
240 This limit is not enforced if the process is privileged
241 .RB ( CAP_IPC_LOCK ).
242 .TP
243 .B ENOMEM
244 (Linux 2.4 and earlier) the calling process tried to lock more than
245 half of RAM.
246 .\" In the case of mlock(), this check is somewhat buggy: it doesn't
247 .\" take into account whether the to-be-locked range overlaps with
248 .\" already locked pages. Thus, suppose we allocate
249 .\" (num_physpages / 4 + 1) of memory, and lock those pages once using
250 .\" mlock(), and then lock the *same* page range a second time.
251 .\" In the case, the second mlock() call will fail, since the check
252 .\" calculates that the process is trying to lock (num_physpages / 2 + 2)
253 .\" pages, which of course is not true. (MTK, Nov 04, kernel 2.4.28)
254 .TP
255 .B EPERM
256 The caller is not privileged, but needs privilege
257 .RB ( CAP_IPC_LOCK )
258 to perform the requested operation.
259 .TP
260 .B EPERM
261 .RB ( munlockall ())
262 (Linux 2.6.8 and earlier) The caller was not privileged
263 .RB ( CAP_IPC_LOCK ).
264 .SH VERSIONS
265 .SS Linux
266 Under Linux,
267 .BR mlock (),
268 .BR mlock2 (),
269 and
270 .BR munlock ()
271 automatically round
272 .I addr
273 down to the nearest page boundary.
274 However, the POSIX.1 specification of
275 .BR mlock ()
276 and
277 .BR munlock ()
278 allows an implementation to require that
279 .I addr
280 is page aligned, so portable applications should ensure this.
281 .P
282 The
283 .I VmLck
284 field of the Linux-specific
285 .IR /proc/ pid /status
286 file shows how many kilobytes of memory the process with ID
287 .I PID
288 has locked using
289 .BR mlock (),
290 .BR mlock2 (),
291 .BR mlockall (),
292 and
293 .BR mmap (2)
294 .BR MAP_LOCKED .
295 .SH STANDARDS
296 .TP
297 .BR mlock ()
298 .TQ
299 .BR munlock ()
300 .TQ
301 .BR mlockall ()
302 .TQ
303 .BR munlockall ()
304 POSIX.1-2024.
305 .TP
306 .BR mlock2 ()
307 Linux.
308 .P
309 On POSIX systems on which
310 .BR mlock ()
311 and
312 .BR munlock ()
313 are available,
314 .B _POSIX_MEMLOCK_RANGE
315 is defined in
316 .I <unistd.h>
317 and the number of bytes in a page
318 can be determined from the constant
319 .B PAGESIZE
320 (if defined) in
321 .I <limits.h>
322 or by calling
323 .IR sysconf(_SC_PAGESIZE) .
324 .P
325 On POSIX systems on which
326 .BR mlockall ()
327 and
328 .BR munlockall ()
329 are available,
330 .B _POSIX_MEMLOCK
331 is defined in
332 .I <unistd.h>
333 to a value greater than 0.
334 (See also
335 .BR sysconf (3).)
336 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
337 .\" -1: unavailable, 0: ask using sysconf().
338 .\" glibc defines it to 1.
339 .SH HISTORY
340 .TP
341 .BR mlock ()
342 .TQ
343 .BR munlock ()
344 .TQ
345 .BR mlockall ()
346 .TQ
347 .BR munlockall ()
348 SVr4,
349 POSIX.1-1996.
350 .TP
351 .BR mlock2 ()
352 Linux 4.4,
353 glibc 2.27.
354 .SH NOTES
355 Memory locking has two main applications: real-time algorithms and
356 high-security data processing.
357 Real-time applications require
358 deterministic timing, and, like scheduling, paging is one major cause
359 of unexpected program execution delays.
360 Real-time applications will
361 usually also switch to a real-time scheduler with
362 .BR sched_setscheduler (2).
363 Cryptographic security software often handles critical bytes like
364 passwords or secret keys as data structures.
365 As a result of paging,
366 these secrets could be transferred onto a persistent swap store medium,
367 where they might be accessible to the enemy long after the security
368 software has erased the secrets in RAM and terminated.
369 (But be aware that the suspend mode on laptops and some desktop
370 computers will save a copy of the system's RAM to disk, regardless
371 of memory locks.)
372 .P
373 Real-time processes that are using
374 .BR mlockall ()
375 to prevent delays on page faults should reserve enough
376 locked stack pages before entering the time-critical section,
377 so that no page fault can be caused by function calls.
378 This can be achieved by calling a function that allocates a
379 sufficiently large automatic variable (an array) and writes to the
380 memory occupied by this array in order to touch these stack pages.
381 This way, enough pages will be mapped for the stack and can be
382 locked into RAM.
383 The dummy writes ensure that not even copy-on-write
384 page faults can occur in the critical section.
385 .P
386 Memory locks are not inherited by a child created via
387 .BR fork (2)
388 and are automatically removed (unlocked) during an
389 .BR execve (2)
390 or when the process terminates.
391 The
392 .BR mlockall ()
393 .B MCL_FUTURE
394 and
395 .B MCL_FUTURE | MCL_ONFAULT
396 settings are not inherited by a child created via
397 .BR fork (2)
398 and are cleared during an
399 .BR execve (2).
400 .P
401 Note that
402 .BR fork (2)
403 will prepare the address space for a copy-on-write operation.
404 The consequence is that any write access that follows will cause
405 a page fault that in turn may cause high latencies for a real-time process.
406 Therefore, it is crucial not to invoke
407 .BR fork (2)
408 after an
409 .BR mlockall ()
410 or
411 .BR mlock ()
412 operation\[em]not even from a thread which runs at a low priority within
413 a process which also has a thread running at elevated priority.
414 .P
415 The memory lock on an address range is automatically removed
416 if the address range is unmapped via
417 .BR munmap (2).
418 .P
419 Memory locks do not stack, that is, pages which have been locked several times
420 by calls to
421 .BR mlock (),
422 .BR mlock2 (),
423 or
424 .BR mlockall ()
425 will be unlocked by a single call to
426 .BR munlock ()
427 for the corresponding range or by
428 .BR munlockall ().
429 Pages which are mapped to several locations or by several processes stay
430 locked into RAM as long as they are locked at least at one location or by
431 at least one process.
432 .P
433 If a call to
434 .BR mlockall ()
435 which uses the
436 .B MCL_FUTURE
437 flag is followed by another call that does not specify this flag, the
438 changes made by the
439 .B MCL_FUTURE
440 call will be lost.
441 .P
442 The
443 .BR mlock2 ()
444 .B MLOCK_ONFAULT
445 flag and the
446 .BR mlockall ()
447 .B MCL_ONFAULT
448 flag allow efficient memory locking for applications that deal with
449 large mappings where only a (small) portion of pages in the mapping are touched.
450 In such cases, locking all of the pages in a mapping would incur
451 a significant penalty for memory locking.
452 .SS Limits and permissions
453 In Linux 2.6.8 and earlier,
454 a process must be privileged
455 .RB ( CAP_IPC_LOCK )
456 in order to lock memory and the
457 .B RLIMIT_MEMLOCK
458 soft resource limit defines a limit on how much memory the process may lock.
459 .P
460 Since Linux 2.6.9, no limits are placed on the amount of memory
461 that a privileged process can lock and the
462 .B RLIMIT_MEMLOCK
463 soft resource limit instead defines a limit on how much memory an
464 unprivileged process may lock.
465 .SH BUGS
466 In Linux 4.8 and earlier,
467 a bug in the kernel's accounting of locked memory for unprivileged processes
468 (i.e., without
469 .BR CAP_IPC_LOCK )
470 meant that if the region specified by
471 .I addr
472 and
473 .I size
474 overlapped an existing lock,
475 then the already locked bytes in the overlapping region were counted twice
476 when checking against the limit.
477 Such double accounting could incorrectly calculate a "total locked memory"
478 value for the process that exceeded the
479 .B RLIMIT_MEMLOCK
480 limit, with the result that
481 .BR mlock ()
482 and
483 .BR mlock2 ()
484 would fail on requests that should have succeeded.
485 This bug was fixed
486 .\" commit 0cf2f6f6dc605e587d2c1120f295934c77e810e8
487 in Linux 4.9.
488 .P
489 In Linux 2.4 series of kernels up to and including Linux 2.4.17,
490 a bug caused the
491 .BR mlockall ()
492 .B MCL_FUTURE
493 flag to be inherited across a
494 .BR fork (2).
495 This was rectified in Linux 2.4.18.
496 .P
497 Since Linux 2.6.9, if a privileged process calls
498 .I mlockall(MCL_FUTURE)
499 and later drops privileges (loses the
500 .B CAP_IPC_LOCK
501 capability by, for example,
502 setting its effective UID to a nonzero value),
503 then subsequent memory allocations (e.g.,
504 .BR mmap (2),
505 .BR brk (2))
506 will fail if the
507 .B RLIMIT_MEMLOCK
508 resource limit is encountered.
509 .\" See the following LKML thread:
510 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2
511 .\" "Rationale for RLIMIT_MEMLOCK"
512 .\" 23 Jan 2006
513 .SH SEE ALSO
514 .BR mincore (2),
515 .BR mmap (2),
516 .BR setrlimit (2),
517 .BR shmctl (2),
518 .BR sysconf (3),
519 .BR proc (5),
520 .BR capabilities (7)