man2/mlock.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (C) Markus Kuhn, 1996
   4 .\"
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, write to the Free
  22 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  23 .\" USA.
  24 .\"
  25 .\" 1995-11-26  Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de>
  26 .\"     First version written
  27 .\" 2003-07-09  Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
  28 .\"     Added note on suspend mode on laptops
  29 .\"
  30 .\" Modified, 27 May 2004, Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
  31 .\"     Added notes on capability requirements
  32 .\"
  33 .TH MLOCK 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual"
  34 .SH NAME
  35 mlock \- disable paging for some parts of memory
  36 .SH SYNOPSIS
  37 .nf
  38 .B #include <sys/mman.h>
  39 .sp
  40 \fBint mlock(const void *\fIaddr\fB, size_t \fIlen\fB);
  41 .fi
  42 .SH DESCRIPTION
  43 .B mlock
  44 disables paging for the memory in the range starting at
  45 .I addr
  46 with length
  47 .I len
  48 bytes. All pages which contain a part of the specified memory range
  49 are guaranteed be resident in RAM when the
  50 .B mlock
  51 system call returns successfully and they are guaranteed to stay in RAM
  52 until the pages are unlocked by
  53 .B munlock
  54 or
  55 .BR munlockall ,
  56 until the pages are unmapped via
  57 .BR munmap ,
  58 or until the process terminates or starts another program with
  59 .BR exec .
  60 Child processes do not inherit page locks across a
  61 .BR fork .
  62
  63 Memory locking has two main applications: real-time algorithms and
  64 high-security data processing. Real-time applications require
  65 deterministic timing, and, like scheduling, paging is one major cause
  66 of unexpected program execution delays. Real-time applications will
  67 usually also switch to a real-time scheduler with
  68 .BR sched_setscheduler .
  69 Cryptographic security software often handles critical bytes like
  70 passwords or secret keys as data structures. As a result of paging,
  71 these secrets could be transferred onto a persistent swap store medium,
  72 where they might be accessible to the enemy long after the security
  73 software has erased the secrets in RAM and terminated.
  74 (But be aware that the suspend mode on laptops and some desktop
  75 computers will save a copy of the system's RAM to disk, regardless
  76 of memory locks.)
  77
  78 Memory locks do not stack, i.e., pages which have been locked several times
  79 by calls to
  80 .B mlock
  81 or
  82 .B mlockall
  83 will be unlocked by a single call to
  84 .B munlock
  85 for the corresponding range or by
  86 .BR munlockall .
  87 Pages which are mapped to several locations or by several processes stay
  88 locked into RAM as long as they are locked at least at one location or by
  89 at least one process.
  90
  91 On POSIX systems on which
  92 .B mlock
  93 and
  94 .B munlock
  95 are available,
  96 .B _POSIX_MEMLOCK_RANGE
  97 is defined in <unistd.h> and the value
  98 .B PAGESIZE
  99 from <limits.h> indicates the number of bytes per page.
 100 .SH NOTES
 101 With the Linux system call,
 102 .I addr
 103 is automatically rounded down to the nearest page boundary.
 104 However, POSIX 1003.1-2001 allows an implementation to require that
 105 .I addr
 106 is page aligned, so portable applications should ensure this.
 107 .SH "RETURN VALUE"
 108 On success,
 109 .B mlock
 110 returns zero.  On error, \-1 is returned,
 111 .I errno
 112 is set appropriately, and no changes are made to any locks in the
 113 address space of the process.
 114 .SH ERRORS
 115 .TP
 116 .B EINVAL
 117 (Not on Linux)
 118 .I addr
 119 was not a multiple of the page size.
 120 .TP
 121 .B ENOMEM
 122 Some of the specified address range does not correspond to mapped
 123 pages in the address space of the process or the process tried to
 124 exceed the maximum number of allowed locked pages.
 125 .TP
 126 .B EPERM
 127 The calling process has insufficient privilege to call
 128 .BR mlock .
 129 Under Linux the
 130 .B CAP_IPC_LOCK
 131 capability is required.
 132 .LP
 133 Linux adds
 134 .TP
 135 .B EINVAL
 136 .I len
 137 was negative.
 138 .SH "CONFORMING TO"
 139 POSIX.1b, SVr4.  SVr4 documents an additional EAGAIN error code.
 140 .SH "SEE ALSO"
 141 .BR mlockall (2),
 142 .BR munlock (2),
 143 .BR munlockall (2),
 144 .BR munmap (2),
 145 .BR setrlimit (2),
 146 .BR capabilities (7)