original/man2/mlock.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (C) Michael Kerrisk, 2004
   4 .\"     using some material drawn from earlier man pages
   5 .\"     written by Thomas Kuhn, Copyright 1996
   6 .\"
   7 .\" This is free documentation; you can redistribute it and/or
   8 .\" modify it under the terms of the GNU General Public License as
   9 .\" published by the Free Software Foundation; either version 2 of
  10 .\" the License, or (at your option) any later version.
  11 .\"
  12 .\" The GNU General Public License's references to "object code"
  13 .\" and "executables" are to be interpreted as the output of any
  14 .\" document formatting or typesetting system, including
  15 .\" intermediate and printed output.
  16 .\"
  17 .\" This manual is distributed in the hope that it will be useful,
  18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 .\" GNU General Public License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU General Public
  23 .\" License along with this manual; if not, write to the Free
  24 .\" Software Foundation, Inc., 59 Temple Place, Suite 330,
  25 .\" Boston, MA 02111, USA.
  26 .\"
  27 .TH MLOCK 2 2011-09-14 "Linux" "Linux Programmer's Manual"
  28 .SH NAME
  29 mlock, munlock, mlockall, munlockall \- lock and unlock memory
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <sys/mman.h>
  33 .sp
  34 .BI "int mlock(const void *" addr ", size_t " len );
  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 and
  43 .BR mlockall ()
  44 respectively lock part or all of the calling process's virtual address
  45 space into RAM, preventing that memory from being paged to the
  46 swap area.
  47 .BR munlock ()
  48 and
  49 .BR munlockall ()
  50 perform the converse operation,
  51 respectively unlocking part or all of the calling process's virtual
  52 address space, so that pages in the specified virtual address range may
  53 once more to be swapped out if required by the kernel memory manager.
  54 Memory locking and unlocking are performed in units of whole pages.
  55 .SS "mlock() and munlock()"
  56 .BR mlock ()
  57 locks pages in the address range starting at
  58 .I addr
  59 and continuing for
  60 .I len
  61 bytes.
  62 All pages that contain a part of the specified address range are
  63 guaranteed to be resident in RAM when the call returns successfully;
  64 the pages are guaranteed to stay in RAM until later unlocked.
  65
  66 .BR munlock ()
  67 unlocks pages in the address range starting at
  68 .I addr
  69 and continuing for
  70 .I len
  71 bytes.
  72 After this call, all pages that contain a part of the specified
  73 memory range can be moved to external swap space again by the kernel.
  74 .SS "mlockall() and munlockall()"
  75 .BR mlockall ()
  76 locks all pages mapped into the address space of the
  77 calling process.
  78 This includes the pages of the code, data and stack
  79 segment, as well as shared libraries, user space kernel data, shared
  80 memory, and memory-mapped files.
  81 All mapped pages are guaranteed
  82 to be resident in RAM when the call returns successfully;
  83 the pages are guaranteed to stay in RAM until later unlocked.
  84
  85 The
  86 .I flags
  87 argument is constructed as the bitwise OR of one or more of the
  88 following constants:
  89 .TP 1.2i
  90 .B MCL_CURRENT
  91 Lock all pages which are currently mapped into the address space of
  92 the process.
  93 .TP
  94 .B MCL_FUTURE
  95 Lock all pages which will become mapped into the address space of the
  96 process in the future.
  97 These could be for instance new pages required
  98 by a growing heap and stack as well as new memory mapped files or
  99 shared memory regions.
 100 .PP
 101 If
 102 .B MCL_FUTURE
 103 has been specified, then a later system call (e.g.,
 104 .BR mmap (2),
 105 .BR sbrk (2),
 106 .BR malloc (3)),
 107 may fail if it would cause the number of locked bytes to exceed
 108 the permitted maximum (see below).
 109 In the same circumstances, stack growth may likewise fail:
 110 the kernel will deny stack expansion and deliver a
 111 .B SIGSEGV
 112 signal to the process.
 113
 114 .BR munlockall ()
 115 unlocks all pages mapped into the address space of the
 116 calling process.
 117 .SH "RETURN VALUE"
 118 On success these system calls return 0.
 119 On error, \-1 is returned,
 120 .I errno
 121 is set appropriately, and no changes are made to any locks in the
 122 address space of the process.
 123 .SH ERRORS
 124 .TP
 125 .B ENOMEM
 126 (Linux 2.6.9 and later) the caller had a nonzero
 127 .B RLIMIT_MEMLOCK
 128 soft resource limit, but tried to lock more memory than the limit
 129 permitted.
 130 This limit is not enforced if the process is privileged
 131 .RB ( CAP_IPC_LOCK ).
 132 .TP
 133 .B ENOMEM
 134 (Linux 2.4 and earlier) the calling process tried to lock more than
 135 half of RAM.
 136 .\" In the case of mlock(), this check is somewhat buggy: it doesn't
 137 .\" take into account whether the to-be-locked range overlaps with
 138 .\" already locked pages.  Thus, suppose we allocate
 139 .\" (num_physpages / 4 + 1) of memory, and lock those pages once using
 140 .\" mlock(), and then lock the *same* page range a second time.
 141 .\" In the case, the second mlock() call will fail, since the check
 142 .\" calculates that the process is trying to lock (num_physpages / 2 + 2)
 143 .\" pages, which of course is not true.  (MTK, Nov 04, kernel 2.4.28)
 144 .TP
 145 .B EPERM
 146 The caller is not privileged, but needs privilege
 147 .RB ( CAP_IPC_LOCK )
 148 to perform the requested operation.
 149 .\"SVr4 documents an additional EAGAIN error code.
 150 .LP
 151 For
 152 .BR mlock ()
 153 and
 154 .BR munlock ():
 155 .TP
 156 .B EAGAIN
 157 Some or all of the specified address range could not be locked.
 158 .TP
 159 .B EINVAL
 160 The result of the addition
 161 .IR start + len
 162 was less than
 163 .IR start
 164 (e.g., the addition may have resulted in an overflow).
 165 .TP
 166 .B EINVAL
 167 (Not on Linux)
 168 .I addr
 169 was not a multiple of the page size.
 170 .TP
 171 .B ENOMEM
 172 Some of the specified address range does not correspond to mapped
 173 pages in the address space of the process.
 174 .LP
 175 For
 176 .BR mlockall ():
 177 .TP
 178 .B EINVAL
 179 Unknown \fIflags\fP were specified.
 180 .LP
 181 For
 182 .BR munlockall ():
 183 .TP
 184 .B EPERM
 185 (Linux 2.6.8 and earlier) The caller was not privileged
 186 .RB ( CAP_IPC_LOCK ).
 187 .SH "CONFORMING TO"
 188 POSIX.1-2001, SVr4.
 189 .SH AVAILABILITY
 190 On POSIX systems on which
 191 .BR mlock ()
 192 and
 193 .BR munlock ()
 194 are available,
 195 .B _POSIX_MEMLOCK_RANGE
 196 is defined in \fI<unistd.h>\fP and the number of bytes in a page
 197 can be determined from the constant
 198 .B PAGESIZE
 199 (if defined) in \fI<limits.h>\fP or by calling
 200 .IR sysconf(_SC_PAGESIZE) .
 201
 202 On POSIX systems on which
 203 .BR mlockall ()
 204 and
 205 .BR munlockall ()
 206 are available,
 207 .B _POSIX_MEMLOCK
 208 is defined in \fI<unistd.h>\fP to a value greater than 0.
 209 (See also
 210 .BR sysconf (3).)
 211 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
 212 .\" -1: unavailable, 0: ask using sysconf().
 213 .\" glibc defines it to 1.
 214 .SH "NOTES"
 215 Memory locking has two main applications: real-time algorithms and
 216 high-security data processing.
 217 Real-time applications require
 218 deterministic timing, and, like scheduling, paging is one major cause
 219 of unexpected program execution delays.
 220 Real-time applications will
 221 usually also switch to a real-time scheduler with
 222 .BR sched_setscheduler (2).
 223 Cryptographic security software often handles critical bytes like
 224 passwords or secret keys as data structures.
 225 As a result of paging,
 226 these secrets could be transferred onto a persistent swap store medium,
 227 where they might be accessible to the enemy long after the security
 228 software has erased the secrets in RAM and terminated.
 229 (But be aware that the suspend mode on laptops and some desktop
 230 computers will save a copy of the system's RAM to disk, regardless
 231 of memory locks.)
 232
 233 Real-time processes that are using
 234 .BR mlockall ()
 235 to prevent delays on page faults should reserve enough
 236 locked stack pages before entering the time-critical section,
 237 so that no page fault can be caused by function calls.
 238 This can be achieved by calling a function that allocates a
 239 sufficiently large automatic variable (an array) and writes to the
 240 memory occupied by this array in order to touch these stack pages.
 241 This way, enough pages will be mapped for the stack and can be
 242 locked into RAM.
 243 The dummy writes ensure that not even copy-on-write
 244 page faults can occur in the critical section.
 245
 246 Memory locks are not inherited by a child created via
 247 .BR fork (2)
 248 and are automatically removed (unlocked) during an
 249 .BR execve (2)
 250 or when the process terminates.
 251
 252 The memory lock on an address range is automatically removed
 253 if the address range is unmapped via
 254 .BR munmap (2).
 255
 256 Memory locks do not stack, that is, pages which have been locked several times
 257 by calls to
 258 .BR mlock ()
 259 or
 260 .BR mlockall ()
 261 will be unlocked by a single call to
 262 .BR munlock ()
 263 for the corresponding range or by
 264 .BR munlockall ().
 265 Pages which are mapped to several locations or by several processes stay
 266 locked into RAM as long as they are locked at least at one location or by
 267 at least one process.
 268 .SS "Linux Notes"
 269 Under Linux,
 270 .BR mlock ()
 271 and
 272 .BR munlock ()
 273 automatically round
 274 .I addr
 275 down to the nearest page boundary.
 276 However, POSIX.1-2001 allows an implementation to require that
 277 .I addr
 278 is page aligned, so portable applications should ensure this.
 279
 280 The
 281 .I VmLck
 282 field of the Linux-specific
 283 .I /proc/PID/status
 284 file shows how many kilobytes of memory the process with ID
 285 .I PID
 286 has locked using
 287 .BR mlock (),
 288 .BR mlockall (),
 289 and
 290 .BR mmap (2)
 291 .BR MAP_LOCKED .
 292 .SS "Limits and permissions"
 293 In Linux 2.6.8 and earlier,
 294 a process must be privileged
 295 .RB ( CAP_IPC_LOCK )
 296 in order to lock memory and the
 297 .B RLIMIT_MEMLOCK
 298 soft resource limit defines a limit on how much memory the process may lock.
 299
 300 Since Linux 2.6.9, no limits are placed on the amount of memory
 301 that a privileged process can lock and the
 302 .B RLIMIT_MEMLOCK
 303 soft resource limit instead defines a limit on how much memory an
 304 unprivileged process may lock.
 305 .SH "BUGS"
 306 In the 2.4 series Linux kernels up to and including 2.4.17,
 307 a bug caused the
 308 .BR mlockall ()
 309 .B MCL_FUTURE
 310 flag to be inherited across a
 311 .BR fork (2).
 312 This was rectified in kernel 2.4.18.
 313
 314 Since kernel 2.6.9, if a privileged process calls
 315 .I mlockall(MCL_FUTURE)
 316 and later drops privileges (loses the
 317 .B CAP_IPC_LOCK
 318 capability by, for example,
 319 setting its effective UID to a nonzero value),
 320 then subsequent memory allocations (e.g.,
 321 .BR mmap (2),
 322 .BR brk (2))
 323 will fail if the
 324 .B RLIMIT_MEMLOCK
 325 resource limit is encountered.
 326 .\" See the following LKML thread:
 327 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2
 328 .\" "Rationale for RLIMIT_MEMLOCK"
 329 .\" 23 Jan 2006
 330 .SH "SEE ALSO"
 331 .BR mmap (2),
 332 .BR setrlimit (2),
 333 .BR shmctl (2),
 334 .BR sysconf (3),
 335 .BR proc (5),
 336 .BR capabilities (7)