man2/mremap.2

   1 .\" Copyright (c) 1996 Tom Bjorkholm <tomb@mydata.se>
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .\" 1996-04-11 Tom Bjorkholm <tomb@mydata.se>
  25 .\"            First version written (1.3.86)
  26 .\" 1996-04-12 Tom Bjorkholm <tomb@mydata.se>
  27 .\"            Update for Linux 1.3.87 and later
  28 .\" 2005-10-11 mtk: Added NOTES for MREMAP_FIXED; revised EINVAL text.
  29 .\"
  30 .TH MREMAP 2 2017-09-25 "Linux" "Linux Programmer's Manual"
  31 .SH NAME
  32 mremap \- remap a virtual memory address
  33 .SH SYNOPSIS
  34 .nf
  35 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  36 .B #include <sys/mman.h>
  37 .PP
  38 .BI "void *mremap(void *" old_address ", size_t " old_size ,
  39 .BI "             size_t " new_size ", int " flags ", ... /* void *" new_address " */);"
  40 .fi
  41 .SH DESCRIPTION
  42 .BR mremap ()
  43 expands (or shrinks) an existing memory mapping, potentially
  44 moving it at the same time (controlled by the \fIflags\fP argument and
  45 the available virtual address space).
  46 .PP
  47 \fIold_address\fP is the old address of the virtual memory block that you
  48 want to expand (or shrink).
  49 Note that \fIold_address\fP has to be page
  50 aligned.
  51 \fIold_size\fP is the old size of the
  52 virtual memory block.
  53 \fInew_size\fP is the requested size of the
  54 virtual memory block after the resize.
  55 An optional fifth argument,
  56 .IR new_address ,
  57 may be provided; see the description of
  58 .B MREMAP_FIXED
  59 below.
  60 .PP
  61 If the value of \fIold_size\fP is zero, and \fIold_address\fP refers to
  62 a shareable mapping (see
  63 .BR mmap (2)
  64 .BR MAP_SHARED ),
  65 then
  66 .BR mremap ()
  67 will create a new mapping of the same pages.
  68 \fInew_size\fP
  69 will be the size of the new mapping and the location of the new mapping
  70 may be specified with \fInew_address\fP; see the description of
  71 .B MREMAP_FIXED
  72 below.
  73 If a new mapping is requested via this method, then the
  74 .B MREMAP_MAYMOVE
  75 flag must also be specified.
  76 .PP
  77 In Linux the memory is divided into pages.
  78 A user process has (one or)
  79 several linear virtual memory segments.
  80 Each virtual memory segment has one
  81 or more mappings to real memory pages (in the page table).
  82 Each virtual memory segment has its own
  83 protection (access rights), which may cause
  84 a segmentation violation if the memory is accessed incorrectly (e.g.,
  85 writing to a read-only segment).
  86 Accessing virtual memory outside of the
  87 segments will also cause a segmentation violation.
  88 .PP
  89 .BR mremap ()
  90 uses the Linux page table scheme.
  91 .BR mremap ()
  92 changes the
  93 mapping between virtual addresses and memory pages.
  94 This can be used to implement a very efficient
  95 .BR realloc (3).
  96 .PP
  97 The \fIflags\fP bit-mask argument may be 0, or include the following flag:
  98 .TP
  99 .B MREMAP_MAYMOVE
 100 By default, if there is not sufficient space to expand a mapping
 101 at its current location, then
 102 .BR mremap ()
 103 fails.
 104 If this flag is specified, then the kernel is permitted to
 105 relocate the mapping to a new virtual address, if necessary.
 106 If the mapping is relocated,
 107 then absolute pointers into the old mapping location
 108 become invalid (offsets relative to the starting address of
 109 the mapping should be employed).
 110 .TP
 111 .BR MREMAP_FIXED " (since Linux 2.3.31)"
 112 This flag serves a similar purpose to the
 113 .B MAP_FIXED
 114 flag of
 115 .BR mmap (2).
 116 If this flag is specified, then
 117 .BR mremap ()
 118 accepts a fifth argument,
 119 .IR "void\ *new_address" ,
 120 which specifies a page-aligned address to which the mapping must
 121 be moved.
 122 Any previous mapping at the address range specified by
 123 .I new_address
 124 and
 125 .I new_size
 126 is unmapped.
 127 If
 128 .B MREMAP_FIXED
 129 is specified, then
 130 .B MREMAP_MAYMOVE
 131 must also be specified.
 132 .PP
 133 If the memory segment specified by
 134 .I old_address
 135 and
 136 .I old_size
 137 is locked (using
 138 .BR mlock (2)
 139 or similar), then this lock is maintained when the segment is
 140 resized and/or relocated.
 141 As a consequence, the amount of memory locked by the process may change.
 142 .SH RETURN VALUE
 143 On success
 144 .BR mremap ()
 145 returns a pointer to the new virtual memory area.
 146 On error, the value
 147 .B MAP_FAILED
 148 (that is, \fI(void\ *)\ \-1\fP) is returned,
 149 and \fIerrno\fP is set appropriately.
 150 .SH ERRORS
 151 .TP
 152 .B EAGAIN
 153 The caller tried to expand a memory segment that is locked,
 154 but this was not possible without exceeding the
 155 .B RLIMIT_MEMLOCK
 156 resource limit.
 157 .TP
 158 .B EFAULT
 159 "Segmentation fault." Some address in the range
 160 \fIold_address\fP to \fIold_address\fP+\fIold_size\fP is an invalid
 161 virtual memory address for this process.
 162 You can also get
 163 .B EFAULT
 164 even if there exist mappings that cover the
 165 whole address space requested, but those mappings are of different types.
 166 .TP
 167 .B EINVAL
 168 An invalid argument was given.
 169 Possible causes are:
 170 .RS
 171 .IP * 3
 172 \fIold_address\fP was not
 173 page aligned;
 174 .IP *
 175 a value other than
 176 .B MREMAP_MAYMOVE
 177 or
 178 .B MREMAP_FIXED
 179 was specified in
 180 .IR flags ;
 181 .IP *
 182 .I new_size
 183 was zero;
 184 .IP *
 185 .I new_size
 186 or
 187 .I new_address
 188 was invalid;
 189 .IP *
 190 the new address range specified by
 191 .I new_address
 192 and
 193 .I new_size
 194 overlapped the old address range specified by
 195 .I old_address
 196 and
 197 .IR old_size ;
 198 .IP *
 199 .B MREMAP_FIXED
 200 was specified without also specifying
 201 .BR MREMAP_MAYMOVE ;
 202 .IP *
 203 \fIold_size\fP was zero and \fIold_address\fP does not refer to a
 204 shareable mapping (but see BUGS);
 205 .IP *
 206 \fIold_size\fP was zero and the
 207 .BR MREMAP_MAYMOVE
 208 flag was not specified.
 209 .RE
 210 .TP
 211 .B ENOMEM
 212 The memory area cannot be expanded at the current virtual address, and the
 213 .B MREMAP_MAYMOVE
 214 flag is not set in \fIflags\fP.
 215 Or, there is not enough (virtual) memory available.
 216 .SH CONFORMING TO
 217 This call is Linux-specific, and should not be used in programs
 218 intended to be portable.
 219 .\" 4.2BSD had a (never actually implemented)
 220 .\" .BR mremap (2)
 221 .\" call with completely different semantics.
 222 .SH NOTES
 223 Prior to version 2.4, glibc did not expose the definition of
 224 .BR MREMAP_FIXED ,
 225 and the prototype for
 226 .BR mremap ()
 227 did not allow for the
 228 .I new_address
 229 argument.
 230 .PP
 231 If
 232 .BR mremap ()
 233 is used to move or expand an area locked with
 234 .BR mlock (2)
 235 or equivalent, the
 236 .BR mremap ()
 237 call will make a best effort to populate the new area but will not fail
 238 with
 239 .B ENOMEM
 240 if the area cannot be populated.
 241 .SH BUGS
 242 Before Linux 4.14,
 243 if
 244 .I old_size
 245 was zero and the mapping referred to by
 246 .I old_address
 247 was a private mapping
 248 .RB ( mmap "(2) " MAP_PRIVATE ),
 249 .BR mremap ()
 250 created a new private mapping unrelated to the original mapping.
 251 This behavior was unintended
 252 and probably unexpected in user-space applications
 253 (since the intention of
 254 .BR mremap ()
 255 is to create a new mapping based on the original mapping).
 256 Since Linux 4.14,
 257 .\" commit dba58d3b8c5045ad89c1c95d33d01451e3964db7
 258 .BR mremap ()
 259 fails with the error
 260 .B EINVAL
 261 in this scenario.
 262 .SH SEE ALSO
 263 .BR brk (2),
 264 .BR getpagesize (2),
 265 .BR getrlimit (2),
 266 .BR mlock (2),
 267 .BR mmap (2),
 268 .BR sbrk (2),
 269 .BR malloc (3),
 270 .BR realloc (3)
 271 .PP
 272 Your favorite text book on operating systems
 273 for more information on paged memory
 274 (e.g., \fIModern Operating Systems\fP by Andrew S.\& Tanenbaum,
 275 \fIInside Linux\fP by Randolf Bentson,
 276 \fIThe Design of the UNIX Operating System\fP by Maurice J.\& Bach)