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