]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1996 Tom Bjorkholm <tomb@mydata.se> |
2 | .\" | |
1dd72f9c | 3 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
fea681da MK |
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 | |
c715f741 MK |
20 | .\" License along with this manual; if not, see |
21 | .\" <http://www.gnu.org/licenses/>. | |
6a8d8745 | 22 | .\" %%%LICENSE_END |
fea681da MK |
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 | |
4f76dae0 | 28 | .\" 2005-10-11 mtk: Added NOTES for MREMAP_FIXED; revised EINVAL text. |
fea681da | 29 | .\" |
9ba01802 | 30 | .TH MREMAP 2 2019-03-06 "Linux" "Linux Programmer's Manual" |
fea681da | 31 | .SH NAME |
3b777aff | 32 | mremap \- remap a virtual memory address |
fea681da | 33 | .SH SYNOPSIS |
3747f397 | 34 | .nf |
b80f966b | 35 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
fea681da | 36 | .B #include <sys/mman.h> |
68e4db0a | 37 | .PP |
da8cb51e | 38 | .BI "void *mremap(void *" old_address ", size_t " old_size , |
ebbb5118 | 39 | .BI " size_t " new_size ", int " flags ", ... /* void *" new_address " */);" |
fea681da MK |
40 | .fi |
41 | .SH DESCRIPTION | |
60a90ecd MK |
42 | .BR mremap () |
43 | expands (or shrinks) an existing memory mapping, potentially | |
a8d55537 | 44 | moving it at the same time (controlled by the \fIflags\fP argument and |
fea681da | 45 | the available virtual address space). |
efeece04 | 46 | .PP |
a8d55537 | 47 | \fIold_address\fP is the old address of the virtual memory block that you |
c13182ef | 48 | want to expand (or shrink). |
a8d55537 | 49 | Note that \fIold_address\fP has to be page |
67da5267 MK |
50 | aligned. |
51 | \fIold_size\fP is the old size of the | |
be7fff26 | 52 | virtual memory block. |
a8d55537 | 53 | \fInew_size\fP is the requested size of the |
c13182ef | 54 | virtual memory block after the resize. |
ebbb5118 MK |
55 | An optional fifth argument, |
56 | .IR new_address , | |
57 | may be provided; see the description of | |
58 | .B MREMAP_FIXED | |
59 | below. | |
efeece04 | 60 | .PP |
aa002e81 MK |
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) | |
dd9e0771 MK |
64 | .BR MAP_SHARED ), |
65 | then | |
aa002e81 | 66 | .BR mremap () |
11e8c314 MK |
67 | will create a new mapping of the same pages. |
68 | \fInew_size\fP | |
aa002e81 | 69 | will be the size of the new mapping and the location of the new mapping |
dd9e0771 | 70 | may be specified with \fInew_address\fP; see the description of |
aa002e81 | 71 | .B MREMAP_FIXED |
11e8c314 MK |
72 | below. |
73 | If a new mapping is requested via this method, then the | |
aa002e81 MK |
74 | .B MREMAP_MAYMOVE |
75 | flag must also be specified. | |
76 | .PP | |
a8d55537 | 77 | The \fIflags\fP bit-mask argument may be 0, or include the following flag: |
fea681da MK |
78 | .TP |
79 | .B MREMAP_MAYMOVE | |
ceb6743d MK |
80 | By default, if there is not sufficient space to expand a mapping |
81 | at its current location, then | |
82 | .BR mremap () | |
83 | fails. | |
c13182ef | 84 | If this flag is specified, then the kernel is permitted to |
ceb6743d MK |
85 | relocate the mapping to a new virtual address, if necessary. |
86 | If the mapping is relocated, | |
c13182ef MK |
87 | then absolute pointers into the old mapping location |
88 | become invalid (offsets relative to the starting address of | |
ceb6743d | 89 | the mapping should be employed). |
8107e4b7 MK |
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, | |
5049da5b | 99 | .IR "void\ *new_address" , |
8107e4b7 MK |
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. | |
cb76d6e5 | 107 | .IP |
c13182ef | 108 | If |
8107e4b7 | 109 | .B MREMAP_FIXED |
c13182ef | 110 | is specified, then |
0daa9e92 | 111 | .B MREMAP_MAYMOVE |
8107e4b7 | 112 | must also be specified. |
8debc4f5 BG |
113 | .TP |
114 | .BR MREMAP_DONTUNMAP " (since Linux 5.7)" | |
115 | .\" commit e346b3813067d4b17383f975f197a9aa28a3b077 | |
452bdc2f MK |
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 | |
0f0993c9 MK |
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)). | |
452bdc2f | 130 | .IP |
0f0993c9 MK |
131 | After completion, |
132 | any access to the range specified by | |
452bdc2f | 133 | .IR old_address |
0f0993c9 MK |
134 | and |
135 | .I old_size | |
136 | will result in a page fault. | |
137 | The page fault will be handled by a | |
8debc4f5 | 138 | .BR userfaultfd (2) |
0f0993c9 MK |
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. | |
4737f0d1 MK |
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). | |
ceb6743d | 151 | .PP |
c13182ef | 152 | If the memory segment specified by |
ceb6743d | 153 | .I old_address |
c13182ef | 154 | and |
ceb6743d MK |
155 | .I old_size |
156 | is locked (using | |
0bfa087b | 157 | .BR mlock (2) |
ceb6743d MK |
158 | or similar), then this lock is maintained when the segment is |
159 | resized and/or relocated. | |
a85a10cb | 160 | As a consequence, the amount of memory locked by the process may change. |
47297adb | 161 | .SH RETURN VALUE |
60a90ecd MK |
162 | On success |
163 | .BR mremap () | |
164 | returns a pointer to the new virtual memory area. | |
fea681da MK |
165 | On error, the value |
166 | .B MAP_FAILED | |
009df872 | 167 | (that is, \fI(void\ *)\ \-1\fP) is returned, |
a8d55537 | 168 | and \fIerrno\fP is set appropriately. |
fea681da MK |
169 | .SH ERRORS |
170 | .TP | |
171 | .B EAGAIN | |
c13182ef | 172 | The caller tried to expand a memory segment that is locked, |
ceb6743d | 173 | but this was not possible without exceeding the |
682edefb MK |
174 | .B RLIMIT_MEMLOCK |
175 | resource limit. | |
fea681da MK |
176 | .TP |
177 | .B EFAULT | |
191dd3b2 | 178 | Some address in the range |
fea681da MK |
179 | \fIold_address\fP to \fIold_address\fP+\fIold_size\fP is an invalid |
180 | virtual memory address for this process. | |
682edefb MK |
181 | You can also get |
182 | .B EFAULT | |
183 | even if there exist mappings that cover the | |
fea681da MK |
184 | whole address space requested, but those mappings are of different types. |
185 | .TP | |
186 | .B EINVAL | |
4f76dae0 | 187 | An invalid argument was given. |
7d4bed40 MK |
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 | |
4f76dae0 | 195 | .B MREMAP_MAYMOVE |
c13182ef | 196 | or |
4f76dae0 | 197 | .B MREMAP_FIXED |
8debc4f5 BG |
198 | or |
199 | .B MREMAP_DONTUNMAP | |
4f76dae0 MK |
200 | was specified in |
201 | .IR flags ; | |
7d4bed40 | 202 | .IP * |
4f76dae0 MK |
203 | .I new_size |
204 | was zero; | |
7d4bed40 | 205 | .IP * |
4f76dae0 | 206 | .I new_size |
c13182ef | 207 | or |
4f76dae0 MK |
208 | .I new_address |
209 | was invalid; | |
7d4bed40 MK |
210 | .IP * |
211 | the new address range specified by | |
c13182ef MK |
212 | .I new_address |
213 | and | |
4f76dae0 MK |
214 | .I new_size |
215 | overlapped the old address range specified by | |
216 | .I old_address | |
217 | and | |
218 | .IR old_size ; | |
7d4bed40 | 219 | .IP * |
4f76dae0 | 220 | .B MREMAP_FIXED |
8debc4f5 BG |
221 | or |
222 | .B MREMAP_DONTUNMAP | |
4f76dae0 | 223 | was specified without also specifying |
aa002e81 | 224 | .BR MREMAP_MAYMOVE ; |
7d4bed40 | 225 | .IP * |
8debc4f5 | 226 | .B MREMAP_DONTUNMAP |
0f0993c9 | 227 | was specified, but one or more pages in the range specified by |
452bdc2f | 228 | .IR old_address |
0f0993c9 MK |
229 | and |
230 | .IR old_size | |
231 | were not private anonymous; | |
8debc4f5 BG |
232 | .IP * |
233 | .B MREMAP_DONTUNMAP | |
234 | was specified and | |
452bdc2f | 235 | .IR old_size |
8debc4f5 | 236 | was not equal to |
452bdc2f | 237 | .IR new_size ; |
8debc4f5 | 238 | .IP * |
7d4bed40 | 239 | \fIold_size\fP was zero and \fIold_address\fP does not refer to a |
2e510f32 | 240 | shareable mapping (but see BUGS); |
7d4bed40 MK |
241 | .IP * |
242 | \fIold_size\fP was zero and the | |
aa002e81 MK |
243 | .BR MREMAP_MAYMOVE |
244 | flag was not specified. | |
7d4bed40 | 245 | .RE |
fea681da MK |
246 | .TP |
247 | .B ENOMEM | |
8debc4f5 BG |
248 | Not enough memory was available to complete the operation. |
249 | Possible causes are: | |
250 | .RS | |
251 | .IP * 3 | |
fea681da MK |
252 | The memory area cannot be expanded at the current virtual address, and the |
253 | .B MREMAP_MAYMOVE | |
c13182ef | 254 | flag is not set in \fIflags\fP. |
fea681da | 255 | Or, there is not enough (virtual) memory available. |
8debc4f5 BG |
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 | |
47297adb | 262 | .SH CONFORMING TO |
8382f16d | 263 | This call is Linux-specific, and should not be used in programs |
b5d63e49 MK |
264 | intended to be portable. |
265 | .\" 4.2BSD had a (never actually implemented) | |
266 | .\" .BR mremap (2) | |
267 | .\" call with completely different semantics. | |
4f76dae0 | 268 | .SH NOTES |
efeece04 | 269 | .PP |
8c97c565 MK |
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 | |
f15e32e3 MK |
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 | |
a0742a27 EM |
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. | |
8debc4f5 | 300 | .PP |
6af75e77 MK |
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. | |
2e510f32 MK |
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. | |
47297adb | 329 | .SH SEE ALSO |
fea681da MK |
330 | .BR brk (2), |
331 | .BR getpagesize (2), | |
ceb6743d MK |
332 | .BR getrlimit (2), |
333 | .BR mlock (2), | |
fea681da MK |
334 | .BR mmap (2), |
335 | .BR sbrk (2), | |
336 | .BR malloc (3), | |
0a4f8b7b | 337 | .BR realloc (3) |
efeece04 | 338 | .PP |
173fe7e7 DP |
339 | Your favorite text book on operating systems |
340 | for more information on paged memory | |
8fb01fde | 341 | (e.g., \fIModern Operating Systems\fP by Andrew S.\& Tanenbaum, |
a8d55537 | 342 | \fIInside Linux\fP by Randolf Bentson, |
8fb01fde | 343 | \fIThe Design of the UNIX Operating System\fP by Maurice J.\& Bach) |