Debian Codegraph @

upstream/debian-trixie/man2/mlock.2

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