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 2010-10-30 "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 (Linux 2.6.9 and later) the caller was not privileged
 147 .RB ( CAP_IPC_LOCK )
 148 and its
 149 .B RLIMIT_MEMLOCK
 150 soft resource limit was 0.
 151 .TP
 152 .B EPERM
 153 (Linux 2.6.8 and earlier)
 154 The calling process has insufficient privilege to call
 155 .BR munlockall ().
 156 Under Linux the
 157 .B CAP_IPC_LOCK
 158 capability is required.
 159 .\"SVr4 documents an additional EAGAIN error code.
 160 .LP
 161 For
 162 .BR mlock ()
 163 and
 164 .BR munlock ():
 165 .TP
 166 .B EAGAIN
 167 Some or all of the specified address range could not be locked.
 168 .TP
 169 .B EINVAL
 170 .I len
 171 was negative.
 172 .TP
 173 .B EINVAL
 174 (Not on Linux)
 175 .I addr
 176 was not a multiple of the page size.
 177 .TP
 178 .B ENOMEM
 179 Some of the specified address range does not correspond to mapped
 180 pages in the address space of the process.
 181 .LP
 182 For
 183 .BR mlockall ():
 184 .TP
 185 .B EINVAL
 186 Unknown \fIflags\fP were specified.
 187 .LP
 188 For
 189 .BR munlockall ():
 190 .TP
 191 .B EPERM
 192 (Linux 2.6.8 and earlier) The caller was not privileged
 193 .RB ( CAP_IPC_LOCK ).
 194 .SH "CONFORMING TO"
 195 POSIX.1-2001, SVr4.
 196 .SH AVAILABILITY
 197 On POSIX systems on which
 198 .BR mlock ()
 199 and
 200 .BR munlock ()
 201 are available,
 202 .B _POSIX_MEMLOCK_RANGE
 203 is defined in \fI<unistd.h>\fP and the number of bytes in a page
 204 can be determined from the constant
 205 .B PAGESIZE
 206 (if defined) in \fI<limits.h>\fP or by calling
 207 .IR sysconf(_SC_PAGESIZE) .
 208
 209 On POSIX systems on which
 210 .BR mlockall ()
 211 and
 212 .BR munlockall ()
 213 are available,
 214 .B _POSIX_MEMLOCK
 215 is defined in \fI<unistd.h>\fP to a value greater than 0.
 216 (See also
 217 .BR sysconf (3).)
 218 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
 219 .\" -1: unavailable, 0: ask using sysconf().
 220 .\" glibc defines it to 1.
 221 .SH "NOTES"
 222 Memory locking has two main applications: real-time algorithms and
 223 high-security data processing.
 224 Real-time applications require
 225 deterministic timing, and, like scheduling, paging is one major cause
 226 of unexpected program execution delays.
 227 Real-time applications will
 228 usually also switch to a real-time scheduler with
 229 .BR sched_setscheduler (2).
 230 Cryptographic security software often handles critical bytes like
 231 passwords or secret keys as data structures.
 232 As a result of paging,
 233 these secrets could be transferred onto a persistent swap store medium,
 234 where they might be accessible to the enemy long after the security
 235 software has erased the secrets in RAM and terminated.
 236 (But be aware that the suspend mode on laptops and some desktop
 237 computers will save a copy of the system's RAM to disk, regardless
 238 of memory locks.)
 239
 240 Real-time processes that are using
 241 .BR mlockall ()
 242 to prevent delays on page faults should reserve enough
 243 locked stack pages before entering the time-critical section,
 244 so that no page fault can be caused by function calls.
 245 This can be achieved by calling a function that allocates a
 246 sufficiently large automatic variable (an array) and writes to the
 247 memory occupied by this array in order to touch these stack pages.
 248 This way, enough pages will be mapped for the stack and can be
 249 locked into RAM.
 250 The dummy writes ensure that not even copy-on-write
 251 page faults can occur in the critical section.
 252
 253 Memory locks are not inherited by a child created via
 254 .BR fork (2)
 255 and are automatically removed (unlocked) during an
 256 .BR execve (2)
 257 or when the process terminates.
 258
 259 The memory lock on an address range is automatically removed
 260 if the address range is unmapped via
 261 .BR munmap (2).
 262
 263 Memory locks do not stack, that is, pages which have been locked several times
 264 by calls to
 265 .BR mlock ()
 266 or
 267 .BR mlockall ()
 268 will be unlocked by a single call to
 269 .BR munlock ()
 270 for the corresponding range or by
 271 .BR munlockall ().
 272 Pages which are mapped to several locations or by several processes stay
 273 locked into RAM as long as they are locked at least at one location or by
 274 at least one process.
 275 .SS "Linux Notes"
 276 Under Linux,
 277 .BR mlock ()
 278 and
 279 .BR munlock ()
 280 automatically round
 281 .I addr
 282 down to the nearest page boundary.
 283 However, POSIX.1-2001 allows an implementation to require that
 284 .I addr
 285 is page aligned, so portable applications should ensure this.
 286
 287 The
 288 .I VmLck
 289 field of the Linux-specific
 290 .I /proc/PID/status
 291 file shows how many kilobytes of memory the process with ID
 292 .I PID
 293 has locked using
 294 .BR mlock (),
 295 .BR mlockall (),
 296 and
 297 .BR mmap (2)
 298 .BR MAP_LOCKED .
 299 .SS "Limits and permissions"
 300 In Linux 2.6.8 and earlier,
 301 a process must be privileged
 302 .RB ( CAP_IPC_LOCK )
 303 in order to lock memory and the
 304 .B RLIMIT_MEMLOCK
 305 soft resource limit defines a limit on how much memory the process may lock.
 306
 307 Since Linux 2.6.9, no limits are placed on the amount of memory
 308 that a privileged process can lock and the
 309 .B RLIMIT_MEMLOCK
 310 soft resource limit instead defines a limit on how much memory an
 311 unprivileged process may lock.
 312 .SH "BUGS"
 313 In the 2.4 series Linux kernels up to and including 2.4.17,
 314 a bug caused the
 315 .BR mlockall ()
 316 .B MCL_FUTURE
 317 flag to be inherited across a
 318 .BR fork (2).
 319 This was rectified in kernel 2.4.18.
 320
 321 Since kernel 2.6.9, if a privileged process calls
 322 .I mlockall(MCL_FUTURE)
 323 and later drops privileges (loses the
 324 .B CAP_IPC_LOCK
 325 capability by, for example,
 326 setting its effective UID to a nonzero value),
 327 then subsequent memory allocations (e.g.,
 328 .BR mmap (2),
 329 .BR brk (2))
 330 will fail if the
 331 .B RLIMIT_MEMLOCK
 332 resource limit is encountered.
 333 .\" See the following LKML thread:
 334 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2
 335 .\" "Rationale for RLIMIT_MEMLOCK"
 336 .\" 23 Jan 2006
 337 .SH "SEE ALSO"
 338 .BR mmap (2),
 339 .BR setrlimit (2),
 340 .BR shmctl (2),
 341 .BR sysconf (3),
 342 .BR proc (5),
 343 .BR capabilities (7)