man2/mremap.2

   1 .\" Copyright (c) 1996 Tom Bjorkholm <tomb@mydata.se>
   2 .\"
   3 .\" SPDX-License-Identifier: GPL-2.0-or-later
   4 .\"
   5 .\" 1996-04-11 Tom Bjorkholm <tomb@mydata.se>
   6 .\"            First version written (1.3.86)
   7 .\" 1996-04-12 Tom Bjorkholm <tomb@mydata.se>
   8 .\"            Update for Linux 1.3.87 and later
   9 .\" 2005-10-11 mtk: Added NOTES for MREMAP_FIXED; revised EINVAL text.
  10 .\"
  11 .TH MREMAP 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  12 .SH NAME
  13 mremap \- remap a virtual memory address
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  20 .B #include <sys/mman.h>
  21 .PP
  22 .BI "void *mremap(void *" old_address ", size_t " old_size ,
  23 .BI "             size_t " new_size ", int " flags ", ... /* void *" new_address " */);"
  24 .fi
  25 .SH DESCRIPTION
  26 .BR mremap ()
  27 expands (or shrinks) an existing memory mapping, potentially
  28 moving it at the same time (controlled by the \fIflags\fP argument and
  29 the available virtual address space).
  30 .PP
  31 \fIold_address\fP is the old address of the virtual memory block that you
  32 want to expand (or shrink).
  33 Note that \fIold_address\fP has to be page
  34 aligned.
  35 \fIold_size\fP is the old size of the
  36 virtual memory block.
  37 \fInew_size\fP is the requested size of the
  38 virtual memory block after the resize.
  39 An optional fifth argument,
  40 .IR new_address ,
  41 may be provided; see the description of
  42 .B MREMAP_FIXED
  43 below.
  44 .PP
  45 If the value of \fIold_size\fP is zero, and \fIold_address\fP refers to
  46 a shareable mapping (see
  47 .BR mmap (2)
  48 .BR MAP_SHARED ),
  49 then
  50 .BR mremap ()
  51 will create a new mapping of the same pages.
  52 \fInew_size\fP
  53 will be the size of the new mapping and the location of the new mapping
  54 may be specified with \fInew_address\fP; see the description of
  55 .B MREMAP_FIXED
  56 below.
  57 If a new mapping is requested via this method, then the
  58 .B MREMAP_MAYMOVE
  59 flag must also be specified.
  60 .PP
  61 The \fIflags\fP bit-mask argument may be 0, or include the following flags:
  62 .TP
  63 .B MREMAP_MAYMOVE
  64 By default, if there is not sufficient space to expand a mapping
  65 at its current location, then
  66 .BR mremap ()
  67 fails.
  68 If this flag is specified, then the kernel is permitted to
  69 relocate the mapping to a new virtual address, if necessary.
  70 If the mapping is relocated,
  71 then absolute pointers into the old mapping location
  72 become invalid (offsets relative to the starting address of
  73 the mapping should be employed).
  74 .TP
  75 .BR MREMAP_FIXED " (since Linux 2.3.31)"
  76 This flag serves a similar purpose to the
  77 .B MAP_FIXED
  78 flag of
  79 .BR mmap (2).
  80 If this flag is specified, then
  81 .BR mremap ()
  82 accepts a fifth argument,
  83 .IR "void\ *new_address" ,
  84 which specifies a page-aligned address to which the mapping must
  85 be moved.
  86 Any previous mapping at the address range specified by
  87 .I new_address
  88 and
  89 .I new_size
  90 is unmapped.
  91 .IP
  92 If
  93 .B MREMAP_FIXED
  94 is specified, then
  95 .B MREMAP_MAYMOVE
  96 must also be specified.
  97 .TP
  98 .BR MREMAP_DONTUNMAP " (since Linux 5.7)"
  99 .\" commit e346b3813067d4b17383f975f197a9aa28a3b077
 100 This flag, which must be used in conjunction with
 101 .BR MREMAP_MAYMOVE ,
 102 remaps a mapping to a new address but does not unmap the mapping at
 103 .IR old_address .
 104 .IP
 105 The
 106 .B MREMAP_DONTUNMAP
 107 flag can be used only with private anonymous mappings
 108 (see the description of
 109 .B MAP_PRIVATE
 110 and
 111 .B MAP_ANONYMOUS
 112 in
 113 .BR mmap (2)).
 114 .IP
 115 After completion,
 116 any access to the range specified by
 117 .I old_address
 118 and
 119 .I old_size
 120 will result in a page fault.
 121 The page fault will be handled by a
 122 .BR userfaultfd (2)
 123 handler
 124 if the address is in a range previously registered with
 125 .BR userfaultfd (2).
 126 Otherwise, the kernel allocates a zero-filled page to handle the fault.
 127 .IP
 128 The
 129 .B MREMAP_DONTUNMAP
 130 flag may be used to atomically move a mapping while leaving the source
 131 mapped.
 132 See NOTES for some possible applications of
 133 .BR MREMAP_DONTUNMAP .
 134 .PP
 135 If the memory segment specified by
 136 .I old_address
 137 and
 138 .I old_size
 139 is locked (using
 140 .BR mlock (2)
 141 or similar), then this lock is maintained when the segment is
 142 resized and/or relocated.
 143 As a consequence, the amount of memory locked by the process may change.
 144 .SH RETURN VALUE
 145 On success
 146 .BR mremap ()
 147 returns a pointer to the new virtual memory area.
 148 On error, the value
 149 .B MAP_FAILED
 150 (that is, \fI(void\ *)\ \-1\fP) is returned,
 151 and \fIerrno\fP is set to indicate the error.
 152 .SH ERRORS
 153 .TP
 154 .B EAGAIN
 155 The caller tried to expand a memory segment that is locked,
 156 but this was not possible without exceeding the
 157 .B RLIMIT_MEMLOCK
 158 resource limit.
 159 .TP
 160 .B EFAULT
 161 Some address in the range
 162 \fIold_address\fP to \fIold_address\fP+\fIold_size\fP is an invalid
 163 virtual memory address for this process.
 164 You can also get
 165 .B EFAULT
 166 even if there exist mappings that cover the
 167 whole address space requested, but those mappings are of different types.
 168 .TP
 169 .B EINVAL
 170 An invalid argument was given.
 171 Possible causes are:
 172 .RS
 173 .IP * 3
 174 \fIold_address\fP was not
 175 page aligned;
 176 .IP *
 177 a value other than
 178 .B MREMAP_MAYMOVE
 179 or
 180 .B MREMAP_FIXED
 181 or
 182 .B MREMAP_DONTUNMAP
 183 was specified in
 184 .IR flags ;
 185 .IP *
 186 .I new_size
 187 was zero;
 188 .IP *
 189 .I new_size
 190 or
 191 .I new_address
 192 was invalid;
 193 .IP *
 194 the new address range specified by
 195 .I new_address
 196 and
 197 .I new_size
 198 overlapped the old address range specified by
 199 .I old_address
 200 and
 201 .IR old_size ;
 202 .IP *
 203 .B MREMAP_FIXED
 204 or
 205 .B MREMAP_DONTUNMAP
 206 was specified without also specifying
 207 .BR MREMAP_MAYMOVE ;
 208 .IP *
 209 .B MREMAP_DONTUNMAP
 210 was specified, but one or more pages in the range specified by
 211 .I old_address
 212 and
 213 .I old_size
 214 were not private anonymous;
 215 .IP *
 216 .B MREMAP_DONTUNMAP
 217 was specified and
 218 .I old_size
 219 was not equal to
 220 .IR new_size ;
 221 .IP *
 222 \fIold_size\fP was zero and \fIold_address\fP does not refer to a
 223 shareable mapping (but see BUGS);
 224 .IP *
 225 \fIold_size\fP was zero and the
 226 .B MREMAP_MAYMOVE
 227 flag was not specified.
 228 .RE
 229 .TP
 230 .B ENOMEM
 231 Not enough memory was available to complete the operation.
 232 Possible causes are:
 233 .RS
 234 .IP * 3
 235 The memory area cannot be expanded at the current virtual address, and the
 236 .B MREMAP_MAYMOVE
 237 flag is not set in \fIflags\fP.
 238 Or, there is not enough (virtual) memory available.
 239 .IP *
 240 .B MREMAP_DONTUNMAP
 241 was used causing a new mapping to be created that would exceed the
 242 (virtual) memory available.
 243 Or, it would exceed the maximum number of allowed mappings.
 244 .RE
 245 .SH STANDARDS
 246 This call is Linux-specific, and should not be used in programs
 247 intended to be portable.
 248 .\" 4.2BSD had a (never actually implemented)
 249 .\" .BR mremap (2)
 250 .\" call with completely different semantics.
 251 .SH NOTES
 252 .BR mremap ()
 253 changes the
 254 mapping between virtual addresses and memory pages.
 255 This can be used to implement a very efficient
 256 .BR realloc (3).
 257 .PP
 258 In Linux, memory is divided into pages.
 259 A process has (one or)
 260 several linear virtual memory segments.
 261 Each virtual memory segment has one
 262 or more mappings to real memory pages (in the page table).
 263 Each virtual memory segment has its own
 264 protection (access rights), which may cause
 265 a segmentation violation
 266 .RB ( SIGSEGV )
 267 if the memory is accessed incorrectly (e.g.,
 268 writing to a read-only segment).
 269 Accessing virtual memory outside of the
 270 segments will also cause a segmentation violation.
 271 .PP
 272 If
 273 .BR mremap ()
 274 is used to move or expand an area locked with
 275 .BR mlock (2)
 276 or equivalent, the
 277 .BR mremap ()
 278 call will make a best effort to populate the new area but will not fail
 279 with
 280 .B ENOMEM
 281 if the area cannot be populated.
 282 .PP
 283 Prior to version 2.4, glibc did not expose the definition of
 284 .BR MREMAP_FIXED ,
 285 and the prototype for
 286 .BR mremap ()
 287 did not allow for the
 288 .I new_address
 289 argument.
 290 .\"
 291 .SS MREMAP_DONTUNMAP use cases
 292 Possible applications for
 293 .B MREMAP_DONTUNMAP
 294 include:
 295 .IP * 3
 296 Non-cooperative
 297 .BR userfaultfd (2):
 298 an application can yank out a virtual address range using
 299 .B MREMAP_DONTUNMAP
 300 and then employ a
 301 .BR userfaultfd (2)
 302 handler to handle the page faults that subsequently occur
 303 as other threads in the process touch pages in the yanked range.
 304 .IP *
 305 Garbage collection:
 306 .B MREMAP_DONTUNMAP
 307 can be used in conjunction with
 308 .BR userfaultfd (2)
 309 to implement garbage collection algorithms (e.g., in a Java virtual machine).
 310 Such an implementation can be cheaper (and simpler)
 311 than conventional garbage collection techniques that involve
 312 marking pages with protection
 313 .B PROT_NONE
 314 in conjunction with the use of a
 315 .B SIGSEGV
 316 handler to catch accesses to those pages.
 317 .SH BUGS
 318 Before Linux 4.14,
 319 if
 320 .I old_size
 321 was zero and the mapping referred to by
 322 .I old_address
 323 was a private mapping
 324 .RB ( mmap "(2) " MAP_PRIVATE ),
 325 .BR mremap ()
 326 created a new private mapping unrelated to the original mapping.
 327 This behavior was unintended
 328 and probably unexpected in user-space applications
 329 (since the intention of
 330 .BR mremap ()
 331 is to create a new mapping based on the original mapping).
 332 Since Linux 4.14,
 333 .\" commit dba58d3b8c5045ad89c1c95d33d01451e3964db7
 334 .BR mremap ()
 335 fails with the error
 336 .B EINVAL
 337 in this scenario.
 338 .SH SEE ALSO
 339 .BR brk (2),
 340 .BR getpagesize (2),
 341 .BR getrlimit (2),
 342 .BR mlock (2),
 343 .BR mmap (2),
 344 .BR sbrk (2),
 345 .BR malloc (3),
 346 .BR realloc (3)
 347 .PP
 348 Your favorite text book on operating systems
 349 for more information on paged memory
 350 (e.g., \fIModern Operating Systems\fP by Andrew S.\& Tanenbaum,
 351 \fIInside Linux\fP by Randolph Bentson,
 352 \fIThe Design of the UNIX Operating System\fP by Maurice J.\& Bach)