Debian Codegraph @

upstream/debian-unstable/man2/mremap.2

raw
1 .\" Copyright 1996, Tom Bjorkholm <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH mremap 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 mremap \- remap a virtual memory address
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
15 .B #include <sys/mman.h>
16 .P
17 .BR "void *mremap(" "size_t old_size;"
18 .BI " void " old_address [ old_size "], size_t " old_size ,
19 .BI " size_t " new_size ", int " flags ", ... /* void *" new_address " */);"
20 .fi
21 .SH DESCRIPTION
22 .BR mremap ()
23 expands (or shrinks) an existing memory mapping,
24 potentially moving it at the same time
25 (controlled by the
26 .I flags
27 argument and
28 the available virtual address space).
29 .P
30 Mappings can also simply be moved
31 (without any resizing)
32 by specifying equal
33 .I old_size
34 and
35 .I new_size
36 and using the
37 .B MREMAP_FIXED
38 flag
39 (see below).
40 Since Linux 6.17,
41 while
42 .I old_address
43 must be mapped,
44 .I old_size
45 may span multiple mappings
46 including unmapped areas between
47 them when performing a simple move.
48 The
49 .B MREMAP_DONTUNMAP
50 flag may also be specified.
51 .P
52 Similarly,
53 if the operation performs a shrink,
54 that is,
55 if
56 .I old_size
57 is greater than
58 .IR new_size ,
59 then
60 .I old_size
61 may also span multiple mappings,
62 which do not have to be
63 adjacent to one another.
64 If this shrink is performed
65 in-place,
66 that is,
67 neither
68 .BR MREMAP_FIXED ,
69 nor
70 .B MREMAP_DONTUNMAP
71 are specified,
72 .I new_size
73 may also span multiple VMAs.
74 However, if the range is moved,
75 then
76 .I new_size
77 must span only a single mapping.
78 .P
79 If the operation is neither a
80 .B MREMAP_FIXED
81 move
82 nor a shrink,
83 then
84 .I old_size
85 must span only a single mapping.
86 .P
87 .I old_address
88 is the old address of the first virtual memory block that you
89 want to expand, shrink, and/or move.
90 Note that
91 .I old_address
92 has to be page aligned.
93 .I old_size
94 is the size of the range containing
95 virtual memory blocks to be manipulated.
96 .I new_size
97 is the requested size of the
98 virtual memory blocks after the resize.
99 An optional fifth argument,
100 .IR new_address ,
101 may be provided;
102 see the description of
103 .B MREMAP_FIXED
104 below.
105 .P
106 If the value of
107 .I old_size
108 is zero, and
109 .I old_address
110 refers to
111 a shareable mapping
112 (see the description of
113 .B MAP_SHARED
114 in
115 .BR mmap (2)),
116 then
117 .BR mremap ()
118 will create a new mapping of the same pages.
119 .I new_size
120 will be the size of the new mapping and the location of the new mapping
121 may be specified with
122 .IR new_address ;
123 see the description of
124 .B MREMAP_FIXED
125 below.
126 If a new mapping is requested via this method, then the
127 .B MREMAP_MAYMOVE
128 flag must also be specified.
129 .P
130 The
131 .I flags
132 bit-mask argument may be 0, or include the following flags:
133 .TP
134 .B MREMAP_MAYMOVE
135 By default, if there is not sufficient space to expand a mapping
136 at its current location, then
137 .BR mremap ()
138 fails.
139 If this flag is specified, then the kernel is permitted to
140 relocate the mapping to a new virtual address, if necessary.
141 If the mapping is relocated,
142 then absolute pointers into the old mapping location
143 become invalid (offsets relative to the starting address of
144 the mapping should be employed).
145 .TP
146 .BR MREMAP_FIXED " (since Linux 2.3.31)"
147 This flag serves a similar purpose to the
148 .B MAP_FIXED
149 flag of
150 .BR mmap (2).
151 If this flag is specified, then
152 .BR mremap ()
153 accepts a fifth argument,
154 .IR "void\ *new_address" ,
155 which specifies a page-aligned address to which the mapping must
156 be moved.
157 Any previous mapping at the address range specified by
158 .I new_address
159 and
160 .I new_size
161 is unmapped.
162 .IP
163 If
164 .B MREMAP_FIXED
165 is specified, then
166 .B MREMAP_MAYMOVE
167 must also be specified.
168 .IP
169 Since Linux 6.17,
170 if
171 .I old_size
172 is equal to
173 .I new_size
174 and
175 .B MREMAP_FIXED
176 is specified, then
177 .I old_size
178 may span beyond the mapping in which
179 .I old_address
180 resides.
181 In this case,
182 gaps between mappings in the original range
183 are maintained in the new range.
184 The whole operation is performed atomically
185 unless an error arises,
186 in which case the operation may be partially
187 completed,
188 that is,
189 some mappings may be moved and others not.
190 .IP
191 Moving multiple mappings is not permitted if
192 any of those mappings have either
193 been registered with
194 .BR userfaultfd (2),
195 or map drivers that
196 specify their own custom address mapping logic.
197 .TP
198 .BR MREMAP_DONTUNMAP " (since Linux 5.7)"
199 .\" commit e346b3813067d4b17383f975f197a9aa28a3b077
200 This flag, which must be used in conjunction with
201 .BR MREMAP_MAYMOVE ,
202 remaps mappings to a new address but does not unmap them
203 from their original address.
204 .IP
205 The
206 .B MREMAP_DONTUNMAP
207 flag can be used only with mappings that are not
208 .B VM_DONTEXPAND
209 or
210 .BR VM_PFNMAP .
211 Before Linux 5.13, the
212 .B MREMAP_DONTUNMAP
213 flag could be used only with private anonymous mappings
214 (see the description of
215 .B MAP_PRIVATE
216 and
217 .B MAP_ANONYMOUS
218 in
219 .BR mmap (2)).
220 .IP
221 After completion,
222 any access to the range specified by
223 .I old_address
224 and
225 .I old_size
226 will result in a page fault.
227 The page fault will be handled by a
228 .BR userfaultfd (2)
229 handler
230 if the address is in a range previously registered with
231 .BR userfaultfd (2).
232 Otherwise, the kernel allocates a zero-filled page to handle the fault.
233 .IP
234 The
235 .B MREMAP_DONTUNMAP
236 flag may be used to atomically move a mapping while leaving the source
237 mapped.
238 See NOTES for some possible applications of
239 .BR MREMAP_DONTUNMAP .
240 .P
241 If the memory segments specified by
242 .I old_address
243 and
244 .I old_size
245 are locked (using
246 .BR mlock (2)
247 or similar), then this lock is maintained when the segments are
248 resized and/or relocated.
249 As a consequence, the amount of memory locked by the process may change.
250 .SH RETURN VALUE
251 On success
252 .BR mremap ()
253 returns a pointer to the new virtual memory area.
254 On error, the value
255 .B MAP_FAILED
256 (that is,
257 .IR "(void\ *)\ \-1" )
258 is returned,
259 and
260 .I errno
261 is set to indicate the error.
262 .SH ERRORS
263 .TP
264 .B EAGAIN
265 The caller tried to expand a memory segment that is locked,
266 but this was not possible without exceeding the
267 .B RLIMIT_MEMLOCK
268 resource limit.
269 .TP
270 .B EFAULT
271 Some address in the range
272 .I old_address
273 to
274 .IR old_address + old_size
275 is an invalid
276 virtual memory address for this process.
277 You can also get
278 .B EFAULT
279 even if there exist mappings that cover the
280 whole address space requested, but those mappings are of different types,
281 and the
282 .BR mremap ()
283 operation being performed does not support this.
284 .TP
285 .B EINVAL
286 An invalid argument was given.
287 Possible causes are:
288 .RS
289 .IP \[bu] 3
290 .I old_address
291 was not page aligned;
292 .IP \[bu]
293 a value other than
294 .B MREMAP_MAYMOVE
295 or
296 .B MREMAP_FIXED
297 or
298 .B MREMAP_DONTUNMAP
299 was specified in
300 .IR flags ;
301 .IP \[bu]
302 .I new_size
303 was zero;
304 .IP \[bu]
305 .I new_size
306 or
307 .I new_address
308 was invalid;
309 .IP \[bu]
310 the new address range specified by
311 .I new_address
312 and
313 .I new_size
314 overlapped the old address range specified by
315 .I old_address
316 and
317 .IR old_size ;
318 .IP \[bu]
319 .B MREMAP_FIXED
320 or
321 .B MREMAP_DONTUNMAP
322 was specified without also specifying
323 .BR MREMAP_MAYMOVE ;
324 .IP \[bu]
325 .B MREMAP_DONTUNMAP
326 was specified, but one or more pages in the range specified by
327 .I old_address
328 and
329 .I old_size
330 were not private anonymous;
331 .IP \[bu]
332 .B MREMAP_DONTUNMAP
333 was specified and
334 .I old_size
335 was not equal to
336 .IR new_size ;
337 .IP \[bu]
338 .I old_size
339 was zero and
340 .I old_address
341 does not refer to a
342 shareable mapping (but see BUGS);
343 .IP \[bu]
344 .I old_size
345 was zero and the
346 .B MREMAP_MAYMOVE
347 flag was not specified.
348 .RE
349 .TP
350 .B ENOMEM
351 Not enough memory was available to complete the operation.
352 Possible causes are:
353 .RS
354 .IP \[bu] 3
355 The memory area cannot be expanded at the current virtual address, and the
356 .B MREMAP_MAYMOVE
357 flag is not set in
358 .IR flags .
359 Or, there is not enough (virtual) memory available.
360 .IP \[bu]
361 .B MREMAP_DONTUNMAP
362 was used causing a new mapping to be created that would exceed the
363 (virtual) memory available.
364 Or, it would exceed the maximum number of allowed mappings.
365 .RE
366 .SH STANDARDS
367 Linux.
368 .SH HISTORY
369 .\" 4.2BSD had a (never actually implemented)
370 .\" .BR mremap (2)
371 .\" call with completely different semantics.
372 .\" .P
373 Prior to glibc 2.4, glibc did not expose the definition of
374 .BR MREMAP_FIXED ,
375 and the prototype for
376 .BR mremap ()
377 did not allow for the
378 .I new_address
379 argument.
380 .SH NOTES
381 .BR mremap ()
382 changes the
383 mapping between virtual addresses and memory pages.
384 This can be used to implement a very efficient
385 .BR realloc (3).
386 .P
387 In Linux, memory is divided into pages.
388 A process has (one or)
389 several linear virtual memory segments.
390 Each virtual memory segment has one
391 or more mappings to real memory pages (in the page table).
392 Each virtual memory segment has its own
393 protection (access rights), which may cause
394 a segmentation violation
395 .RB ( SIGSEGV )
396 if the memory is accessed incorrectly (e.g.,
397 writing to a read-only segment).
398 Accessing virtual memory outside of the
399 segments will also cause a segmentation violation.
400 .P
401 If
402 .BR mremap ()
403 is used to move or expand an area locked with
404 .BR mlock (2)
405 or equivalent, the
406 .BR mremap ()
407 call will make a best effort to populate the new area but will not fail
408 with
409 .B ENOMEM
410 if the area cannot be populated.
411 .\"
412 .SS MREMAP_DONTUNMAP use cases
413 Possible applications for
414 .B MREMAP_DONTUNMAP
415 include:
416 .IP \[bu] 3
417 Non-cooperative
418 .BR userfaultfd (2):
419 an application can yank out a virtual address range using
420 .B MREMAP_DONTUNMAP
421 and then employ a
422 .BR userfaultfd (2)
423 handler to handle the page faults that subsequently occur
424 as other threads in the process touch pages in the yanked range.
425 .IP \[bu]
426 Garbage collection:
427 .B MREMAP_DONTUNMAP
428 can be used in conjunction with
429 .BR userfaultfd (2)
430 to implement garbage collection algorithms (e.g., in a Java virtual machine).
431 Such an implementation can be cheaper (and simpler)
432 than conventional garbage collection techniques that involve
433 marking pages with protection
434 .B PROT_NONE
435 in conjunction with the use of a
436 .B SIGSEGV
437 handler to catch accesses to those pages.
438 .SH BUGS
439 Before Linux 4.14,
440 if
441 .I old_size
442 was zero and the mapping referred to by
443 .I old_address
444 was a private mapping
445 (see the description of
446 .B MAP_PRIVATE
447 in
448 .BR mmap (2)),
449 .BR mremap ()
450 created a new private mapping unrelated to the original mapping.
451 This behavior was unintended
452 and probably unexpected in user-space applications
453 (since the intention of
454 .BR mremap ()
455 is to create a new mapping based on the original mapping).
456 Since Linux 4.14,
457 .\" commit dba58d3b8c5045ad89c1c95d33d01451e3964db7
458 .BR mremap ()
459 fails with the error
460 .B EINVAL
461 in this scenario.
462 .SH SEE ALSO
463 .BR brk (2),
464 .BR getpagesize (2),
465 .BR getrlimit (2),
466 .BR mlock (2),
467 .BR mmap (2),
468 .BR sbrk (2),
469 .BR malloc (3),
470 .BR realloc (3)
471 .P
472 Your favorite text book on operating systems
473 for more information on paged memory
474 (e.g.,
475 .I Modern Operating Systems
476 by Andrew S.\& Tanenbaum,
477 .I Inside Linux
478 by Randolph Bentson,
479 .I The Design of the UNIX Operating System
480 by Maurice J.\& Bach)