original/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 2011-09-14 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 mlock, 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 munlock(const void *" addr ", size_t " len );
  35 .sp
  36 .BI "int mlockall(int " flags );
  37 .B int munlockall(void);
  38 .fi
  39 .SH DESCRIPTION
  40 .BR mlock ()
  41 and
  42 .BR mlockall ()
  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
  45 swap area.
  46 .BR munlock ()
  47 and
  48 .BR munlockall ()
  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()
  55 .BR mlock ()
  56 locks pages in the address range starting at
  57 .I addr
  58 and continuing for
  59 .I len
  60 bytes.
  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.
  64
  65 .BR munlock ()
  66 unlocks pages in the address range starting at
  67 .I addr
  68 and continuing for
  69 .I len
  70 bytes.
  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()
  74 .BR mlockall ()
  75 locks all pages mapped into the address space of the
  76 calling process.
  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.
  83
  84 The
  85 .I flags
  86 argument is constructed as the bitwise OR of one or more of the
  87 following constants:
  88 .TP 1.2i
  89 .B MCL_CURRENT
  90 Lock all pages which are currently mapped into the address space of
  91 the process.
  92 .TP
  93 .B MCL_FUTURE
  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.
  99 .PP
 100 If
 101 .B MCL_FUTURE
 102 has been specified, then a later system call (e.g.,
 103 .BR mmap (2),
 104 .BR sbrk (2),
 105 .BR malloc (3)),
 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
 110 .B SIGSEGV
 111 signal to the process.
 112
 113 .BR munlockall ()
 114 unlocks all pages mapped into the address space of the
 115 calling process.
 116 .SH RETURN VALUE
 117 On success these system calls return 0.
 118 On error, \-1 is returned,
 119 .I errno
 120 is set appropriately, and no changes are made to any locks in the
 121 address space of the process.
 122 .SH ERRORS
 123 .TP
 124 .B ENOMEM
 125 (Linux 2.6.9 and later) the caller had a nonzero
 126 .B RLIMIT_MEMLOCK
 127 soft resource limit, but tried to lock more memory than the limit
 128 permitted.
 129 This limit is not enforced if the process is privileged
 130 .RB ( CAP_IPC_LOCK ).
 131 .TP
 132 .B ENOMEM
 133 (Linux 2.4 and earlier) the calling process tried to lock more than
 134 half of RAM.
 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)
 143 .TP
 144 .B EPERM
 145 The caller is not privileged, but needs privilege
 146 .RB ( CAP_IPC_LOCK )
 147 to perform the requested operation.
 148 .\"SVr4 documents an additional EAGAIN error code.
 149 .LP
 150 For
 151 .BR mlock ()
 152 and
 153 .BR munlock ():
 154 .TP
 155 .B EAGAIN
 156 Some or all of the specified address range could not be locked.
 157 .TP
 158 .B EINVAL
 159 The result of the addition
 160 .IR start + len
 161 was less than
 162 .IR start
 163 (e.g., the addition may have resulted in an overflow).
 164 .TP
 165 .B EINVAL
 166 (Not on Linux)
 167 .I addr
 168 was not a multiple of the page size.
 169 .TP
 170 .B ENOMEM
 171 Some of the specified address range does not correspond to mapped
 172 pages in the address space of the process.
 173 .LP
 174 For
 175 .BR mlockall ():
 176 .TP
 177 .B EINVAL
 178 Unknown \fIflags\fP were specified.
 179 .LP
 180 For
 181 .BR munlockall ():
 182 .TP
 183 .B EPERM
 184 (Linux 2.6.8 and earlier) The caller was not privileged
 185 .RB ( CAP_IPC_LOCK ).
 186 .SH CONFORMING TO
 187 POSIX.1-2001, SVr4.
 188 .SH AVAILABILITY
 189 On POSIX systems on which
 190 .BR mlock ()
 191 and
 192 .BR munlock ()
 193 are available,
 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
 197 .B PAGESIZE
 198 (if defined) in \fI<limits.h>\fP or by calling
 199 .IR sysconf(_SC_PAGESIZE) .
 200
 201 On POSIX systems on which
 202 .BR mlockall ()
 203 and
 204 .BR munlockall ()
 205 are available,
 206 .B _POSIX_MEMLOCK
 207 is defined in \fI<unistd.h>\fP to a value greater than 0.
 208 (See also
 209 .BR sysconf (3).)
 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.
 213 .SH NOTES
 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
 230 of memory locks.)
 231
 232 Real-time processes that are using
 233 .BR mlockall ()
 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
 241 locked into RAM.
 242 The dummy writes ensure that not even copy-on-write
 243 page faults can occur in the critical section.
 244
 245 Memory locks are not inherited by a child created via
 246 .BR fork (2)
 247 and are automatically removed (unlocked) during an
 248 .BR execve (2)
 249 or when the process terminates.
 250
 251 The memory lock on an address range is automatically removed
 252 if the address range is unmapped via
 253 .BR munmap (2).
 254
 255 Memory locks do not stack, that is, pages which have been locked several times
 256 by calls to
 257 .BR mlock ()
 258 or
 259 .BR mlockall ()
 260 will be unlocked by a single call to
 261 .BR munlock ()
 262 for the corresponding range or by
 263 .BR munlockall ().
 264 Pages which are mapped to several locations or by several processes stay
 265 locked into RAM as long as they are locked at least at one location or by
 266 at least one process.
 267 .SS Linux notes
 268 Under Linux,
 269 .BR mlock ()
 270 and
 271 .BR munlock ()
 272 automatically round
 273 .I addr
 274 down to the nearest page boundary.
 275 However, POSIX.1-2001 allows an implementation to require that
 276 .I addr
 277 is page aligned, so portable applications should ensure this.
 278
 279 The
 280 .I VmLck
 281 field of the Linux-specific
 282 .I /proc/PID/status
 283 file shows how many kilobytes of memory the process with ID
 284 .I PID
 285 has locked using
 286 .BR mlock (),
 287 .BR mlockall (),
 288 and
 289 .BR mmap (2)
 290 .BR MAP_LOCKED .
 291 .SS Limits and permissions
 292 In Linux 2.6.8 and earlier,
 293 a process must be privileged
 294 .RB ( CAP_IPC_LOCK )
 295 in order to lock memory and the
 296 .B RLIMIT_MEMLOCK
 297 soft resource limit defines a limit on how much memory the process may lock.
 298
 299 Since Linux 2.6.9, no limits are placed on the amount of memory
 300 that a privileged process can lock and the
 301 .B RLIMIT_MEMLOCK
 302 soft resource limit instead defines a limit on how much memory an
 303 unprivileged process may lock.
 304 .SH BUGS
 305 In the 2.4 series Linux kernels up to and including 2.4.17,
 306 a bug caused the
 307 .BR mlockall ()
 308 .B MCL_FUTURE
 309 flag to be inherited across a
 310 .BR fork (2).
 311 This was rectified in kernel 2.4.18.
 312
 313 Since kernel 2.6.9, if a privileged process calls
 314 .I mlockall(MCL_FUTURE)
 315 and later drops privileges (loses the
 316 .B CAP_IPC_LOCK
 317 capability by, for example,
 318 setting its effective UID to a nonzero value),
 319 then subsequent memory allocations (e.g.,
 320 .BR mmap (2),
 321 .BR brk (2))
 322 will fail if the
 323 .B RLIMIT_MEMLOCK
 324 resource limit is encountered.
 325 .\" See the following LKML thread:
 326 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2
 327 .\" "Rationale for RLIMIT_MEMLOCK"
 328 .\" 23 Jan 2006
 329 .SH SEE ALSO
 330 .BR mmap (2),
 331 .BR setrlimit (2),
 332 .BR shmctl (2),
 333 .BR sysconf (3),
 334 .BR proc (5),
 335 .BR capabilities (7)
 336 .SH COLOPHON
 337 This page is part of release 3.64 of the Linux
 338 .I man-pages
 339 project.
 340 A description of the project,
 341 and information about reporting bugs,
 342 can be found at
 343 \%http://www.kernel.org/doc/man\-pages/.