man2/mlock.2

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