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 2019-03-06 "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 The \fIflags\fP bit-mask argument may be 0, or include the following flag:
  78 .TP
  79 .B MREMAP_MAYMOVE
  80 By default, if there is not sufficient space to expand a mapping
  81 at its current location, then
  82 .BR mremap ()
  83 fails.
  84 If this flag is specified, then the kernel is permitted to
  85 relocate the mapping to a new virtual address, if necessary.
  86 If the mapping is relocated,
  87 then absolute pointers into the old mapping location
  88 become invalid (offsets relative to the starting address of
  89 the mapping should be employed).
  90 .TP
  91 .BR MREMAP_FIXED " (since Linux 2.3.31)"
  92 This flag serves a similar purpose to the
  93 .B MAP_FIXED
  94 flag of
  95 .BR mmap (2).
  96 If this flag is specified, then
  97 .BR mremap ()
  98 accepts a fifth argument,
  99 .IR "void\ *new_address" ,
 100 which specifies a page-aligned address to which the mapping must
 101 be moved.
 102 Any previous mapping at the address range specified by
 103 .I new_address
 104 and
 105 .I new_size
 106 is unmapped.
 107 .IP
 108 If
 109 .B MREMAP_FIXED
 110 is specified, then
 111 .B MREMAP_MAYMOVE
 112 must also be specified.
 113 .TP
 114 .BR MREMAP_DONTUNMAP " (since Linux 5.7)"
 115 .\" commit e346b3813067d4b17383f975f197a9aa28a3b077
 116 This flag, which must be used in conjunction with
 117 .BR MREMAP_MAYMOVE ,
 118 remaps a mapping to a new address but does not unmap the mapping at
 119 .IR old_address .
 120 .IP
 121 The
 122 .B MREMAP_DONTUNMAP
 123 flag can be used only with private anonymous mappings
 124 (see the description of
 125 .BR MAP_PRIVATE
 126 and
 127 .BR MAP_ANONYMOUS
 128 in
 129 .BR mmap (2)).
 130 .IP
 131 After completion,
 132 any access to the range specified by
 133 .IR old_address
 134 and
 135 .I old_size
 136 will result in a page fault.
 137 The page fault will be handled by a
 138 .BR userfaultfd (2)
 139 handler
 140 if the address is in a range previously registered with
 141 .BR userfaultfd (2).
 142 Otherwise, the kernel allocates a zero-filled page to handle the fault.
 143 .IP
 144 The
 145 .BR MREMAP_DONTUNMAP
 146 flag may be used to atomically move a mapping while leaving the source
 147 mapped.
 148 Possible applications for this behavior might be garbage collection or
 149 non-cooperative
 150 .BR userfaultfd (2).
 151 .PP
 152 If the memory segment specified by
 153 .I old_address
 154 and
 155 .I old_size
 156 is locked (using
 157 .BR mlock (2)
 158 or similar), then this lock is maintained when the segment is
 159 resized and/or relocated.
 160 As a consequence, the amount of memory locked by the process may change.
 161 .SH RETURN VALUE
 162 On success
 163 .BR mremap ()
 164 returns a pointer to the new virtual memory area.
 165 On error, the value
 166 .B MAP_FAILED
 167 (that is, \fI(void\ *)\ \-1\fP) is returned,
 168 and \fIerrno\fP is set appropriately.
 169 .SH ERRORS
 170 .TP
 171 .B EAGAIN
 172 The caller tried to expand a memory segment that is locked,
 173 but this was not possible without exceeding the
 174 .B RLIMIT_MEMLOCK
 175 resource limit.
 176 .TP
 177 .B EFAULT
 178 Some address in the range
 179 \fIold_address\fP to \fIold_address\fP+\fIold_size\fP is an invalid
 180 virtual memory address for this process.
 181 You can also get
 182 .B EFAULT
 183 even if there exist mappings that cover the
 184 whole address space requested, but those mappings are of different types.
 185 .TP
 186 .B EINVAL
 187 An invalid argument was given.
 188 Possible causes are:
 189 .RS
 190 .IP * 3
 191 \fIold_address\fP was not
 192 page aligned;
 193 .IP *
 194 a value other than
 195 .B MREMAP_MAYMOVE
 196 or
 197 .B MREMAP_FIXED
 198 or
 199 .B MREMAP_DONTUNMAP
 200 was specified in
 201 .IR flags ;
 202 .IP *
 203 .I new_size
 204 was zero;
 205 .IP *
 206 .I new_size
 207 or
 208 .I new_address
 209 was invalid;
 210 .IP *
 211 the new address range specified by
 212 .I new_address
 213 and
 214 .I new_size
 215 overlapped the old address range specified by
 216 .I old_address
 217 and
 218 .IR old_size ;
 219 .IP *
 220 .B MREMAP_FIXED
 221 or
 222 .B MREMAP_DONTUNMAP
 223 was specified without also specifying
 224 .BR MREMAP_MAYMOVE ;
 225 .IP *
 226 .B MREMAP_DONTUNMAP
 227 was specified, but one or more pages in the range specified by
 228 .IR old_address
 229 and
 230 .IR old_size
 231 were not private anonymous;
 232 .IP *
 233 .B MREMAP_DONTUNMAP
 234 was specified and
 235 .IR old_size
 236 was not equal to
 237 .IR new_size ;
 238 .IP *
 239 \fIold_size\fP was zero and \fIold_address\fP does not refer to a
 240 shareable mapping (but see BUGS);
 241 .IP *
 242 \fIold_size\fP was zero and the
 243 .BR MREMAP_MAYMOVE
 244 flag was not specified.
 245 .RE
 246 .TP
 247 .B ENOMEM
 248 Not enough memory was available to complete the operation.
 249 Possible causes are:
 250 .RS
 251 .IP * 3
 252 The memory area cannot be expanded at the current virtual address, and the
 253 .B MREMAP_MAYMOVE
 254 flag is not set in \fIflags\fP.
 255 Or, there is not enough (virtual) memory available.
 256 .IP *
 257 .B MREMAP_DONTUNMAP
 258 was used causing a new mapping to be created that would exceed the
 259 (virtual) memory available.
 260 Or, it would exceed the maximum number of allowed mappings.
 261 .RE
 262 .SH CONFORMING TO
 263 This call is Linux-specific, and should not be used in programs
 264 intended to be portable.
 265 .\" 4.2BSD had a (never actually implemented)
 266 .\" .BR mremap (2)
 267 .\" call with completely different semantics.
 268 .SH NOTES
 269 .PP
 270 .BR mremap ()
 271 changes the
 272 mapping between virtual addresses and memory pages.
 273 This can be used to implement a very efficient
 274 .BR realloc (3).
 275 .PP
 276 In Linux, memory is divided into pages.
 277 A process has (one or)
 278 several linear virtual memory segments.
 279 Each virtual memory segment has one
 280 or more mappings to real memory pages (in the page table).
 281 Each virtual memory segment has its own
 282 protection (access rights), which may cause
 283 a segmentation violation
 284 .RB ( SIGSEGV )
 285 if the memory is accessed incorrectly (e.g.,
 286 writing to a read-only segment).
 287 Accessing virtual memory outside of the
 288 segments will also cause a segmentation violation.
 289 .PP
 290 If
 291 .BR mremap ()
 292 is used to move or expand an area locked with
 293 .BR mlock (2)
 294 or equivalent, the
 295 .BR mremap ()
 296 call will make a best effort to populate the new area but will not fail
 297 with
 298 .B ENOMEM
 299 if the area cannot be populated.
 300 .PP
 301 Prior to version 2.4, glibc did not expose the definition of
 302 .BR MREMAP_FIXED ,
 303 and the prototype for
 304 .BR mremap ()
 305 did not allow for the
 306 .I new_address
 307 argument.
 308 .SH BUGS
 309 Before Linux 4.14,
 310 if
 311 .I old_size
 312 was zero and the mapping referred to by
 313 .I old_address
 314 was a private mapping
 315 .RB ( mmap "(2) " MAP_PRIVATE ),
 316 .BR mremap ()
 317 created a new private mapping unrelated to the original mapping.
 318 This behavior was unintended
 319 and probably unexpected in user-space applications
 320 (since the intention of
 321 .BR mremap ()
 322 is to create a new mapping based on the original mapping).
 323 Since Linux 4.14,
 324 .\" commit dba58d3b8c5045ad89c1c95d33d01451e3964db7
 325 .BR mremap ()
 326 fails with the error
 327 .B EINVAL
 328 in this scenario.
 329 .SH SEE ALSO
 330 .BR brk (2),
 331 .BR getpagesize (2),
 332 .BR getrlimit (2),
 333 .BR mlock (2),
 334 .BR mmap (2),
 335 .BR sbrk (2),
 336 .BR malloc (3),
 337 .BR realloc (3)
 338 .PP
 339 Your favorite text book on operating systems
 340 for more information on paged memory
 341 (e.g., \fIModern Operating Systems\fP by Andrew S.\& Tanenbaum,
 342 \fIInside Linux\fP by Randolf Bentson,
 343 \fIThe Design of the UNIX Operating System\fP by Maurice J.\& Bach)