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