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 flags:
  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 See NOTES for some possible applications of
 149 .BR MREMAP_DONTUNMAP .
 150 .PP
 151 If the memory segment specified by
 152 .I old_address
 153 and
 154 .I old_size
 155 is locked (using
 156 .BR mlock (2)
 157 or similar), then this lock is maintained when the segment is
 158 resized and/or relocated.
 159 As a consequence, the amount of memory locked by the process may change.
 160 .SH RETURN VALUE
 161 On success
 162 .BR mremap ()
 163 returns a pointer to the new virtual memory area.
 164 On error, the value
 165 .B MAP_FAILED
 166 (that is, \fI(void\ *)\ \-1\fP) is returned,
 167 and \fIerrno\fP is set appropriately.
 168 .SH ERRORS
 169 .TP
 170 .B EAGAIN
 171 The caller tried to expand a memory segment that is locked,
 172 but this was not possible without exceeding the
 173 .B RLIMIT_MEMLOCK
 174 resource limit.
 175 .TP
 176 .B EFAULT
 177 Some address in the range
 178 \fIold_address\fP to \fIold_address\fP+\fIold_size\fP is an invalid
 179 virtual memory address for this process.
 180 You can also get
 181 .B EFAULT
 182 even if there exist mappings that cover the
 183 whole address space requested, but those mappings are of different types.
 184 .TP
 185 .B EINVAL
 186 An invalid argument was given.
 187 Possible causes are:
 188 .RS
 189 .IP * 3
 190 \fIold_address\fP was not
 191 page aligned;
 192 .IP *
 193 a value other than
 194 .B MREMAP_MAYMOVE
 195 or
 196 .B MREMAP_FIXED
 197 or
 198 .B MREMAP_DONTUNMAP
 199 was specified in
 200 .IR flags ;
 201 .IP *
 202 .I new_size
 203 was zero;
 204 .IP *
 205 .I new_size
 206 or
 207 .I new_address
 208 was invalid;
 209 .IP *
 210 the new address range specified by
 211 .I new_address
 212 and
 213 .I new_size
 214 overlapped the old address range specified by
 215 .I old_address
 216 and
 217 .IR old_size ;
 218 .IP *
 219 .B MREMAP_FIXED
 220 or
 221 .B MREMAP_DONTUNMAP
 222 was specified without also specifying
 223 .BR MREMAP_MAYMOVE ;
 224 .IP *
 225 .B MREMAP_DONTUNMAP
 226 was specified, but one or more pages in the range specified by
 227 .IR old_address
 228 and
 229 .IR old_size
 230 were not private anonymous;
 231 .IP *
 232 .B MREMAP_DONTUNMAP
 233 was specified and
 234 .IR old_size
 235 was not equal to
 236 .IR new_size ;
 237 .IP *
 238 \fIold_size\fP was zero and \fIold_address\fP does not refer to a
 239 shareable mapping (but see BUGS);
 240 .IP *
 241 \fIold_size\fP was zero and the
 242 .BR MREMAP_MAYMOVE
 243 flag was not specified.
 244 .RE
 245 .TP
 246 .B ENOMEM
 247 Not enough memory was available to complete the operation.
 248 Possible causes are:
 249 .RS
 250 .IP * 3
 251 The memory area cannot be expanded at the current virtual address, and the
 252 .B MREMAP_MAYMOVE
 253 flag is not set in \fIflags\fP.
 254 Or, there is not enough (virtual) memory available.
 255 .IP *
 256 .B MREMAP_DONTUNMAP
 257 was used causing a new mapping to be created that would exceed the
 258 (virtual) memory available.
 259 Or, it would exceed the maximum number of allowed mappings.
 260 .RE
 261 .SH CONFORMING TO
 262 This call is Linux-specific, and should not be used in programs
 263 intended to be portable.
 264 .\" 4.2BSD had a (never actually implemented)
 265 .\" .BR mremap (2)
 266 .\" call with completely different semantics.
 267 .SH NOTES
 268 .PP
 269 .BR mremap ()
 270 changes the
 271 mapping between virtual addresses and memory pages.
 272 This can be used to implement a very efficient
 273 .BR realloc (3).
 274 .PP
 275 In Linux, memory is divided into pages.
 276 A process has (one or)
 277 several linear virtual memory segments.
 278 Each virtual memory segment has one
 279 or more mappings to real memory pages (in the page table).
 280 Each virtual memory segment has its own
 281 protection (access rights), which may cause
 282 a segmentation violation
 283 .RB ( SIGSEGV )
 284 if the memory is accessed incorrectly (e.g.,
 285 writing to a read-only segment).
 286 Accessing virtual memory outside of the
 287 segments will also cause a segmentation violation.
 288 .PP
 289 If
 290 .BR mremap ()
 291 is used to move or expand an area locked with
 292 .BR mlock (2)
 293 or equivalent, the
 294 .BR mremap ()
 295 call will make a best effort to populate the new area but will not fail
 296 with
 297 .B ENOMEM
 298 if the area cannot be populated.
 299 .PP
 300 Prior to version 2.4, glibc did not expose the definition of
 301 .BR MREMAP_FIXED ,
 302 and the prototype for
 303 .BR mremap ()
 304 did not allow for the
 305 .I new_address
 306 argument.
 307 .\"
 308 .SS MREMAP_DONTUNMAP use cases
 309 Possible applications for
 310 .BR MREMAP_DONTUNMAP
 311 include:
 312 .IP * 3
 313 Non-cooperative
 314 .BR userfaultfd (2):
 315 an application can yank out a virtual address range using
 316 .BR MREMAP_DONTUNMAP
 317 and then employ a
 318 .BR userfaultfd (2)
 319 handler to handle the page faults that subsequently occur
 320 as other threads in the process touch pages in the yanked range.
 321 .IP *
 322 Garbage collection:
 323 .BR MREMAP_DONTUNMAP
 324 can be used in conjunction with
 325 .BR userfaultfd (2)
 326 to implement garbage collection algorithms (e.g., in a Java virtual machine).
 327 Such an implementation can be cheaper (and simpler)
 328 than conventional garbage collection techniques that involve
 329 marking pages with protection
 330 .BR PROT_NONE
 331 in conjunction with the of a
 332 .BR SIGSEGV
 333 handler to catch accesses to those pages.
 334 .SH BUGS
 335 Before Linux 4.14,
 336 if
 337 .I old_size
 338 was zero and the mapping referred to by
 339 .I old_address
 340 was a private mapping
 341 .RB ( mmap "(2) " MAP_PRIVATE ),
 342 .BR mremap ()
 343 created a new private mapping unrelated to the original mapping.
 344 This behavior was unintended
 345 and probably unexpected in user-space applications
 346 (since the intention of
 347 .BR mremap ()
 348 is to create a new mapping based on the original mapping).
 349 Since Linux 4.14,
 350 .\" commit dba58d3b8c5045ad89c1c95d33d01451e3964db7
 351 .BR mremap ()
 352 fails with the error
 353 .B EINVAL
 354 in this scenario.
 355 .SH SEE ALSO
 356 .BR brk (2),
 357 .BR getpagesize (2),
 358 .BR getrlimit (2),
 359 .BR mlock (2),
 360 .BR mmap (2),
 361 .BR sbrk (2),
 362 .BR malloc (3),
 363 .BR realloc (3)
 364 .PP
 365 Your favorite text book on operating systems
 366 for more information on paged memory
 367 (e.g., \fIModern Operating Systems\fP by Andrew S.\& Tanenbaum,
 368 \fIInside Linux\fP by Randolf Bentson,
 369 \fIThe Design of the UNIX Operating System\fP by Maurice J.\& Bach)