]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1996 Tom Bjorkholm <tomb@mydata.se> |
2 | .\" | |
6a8d8745 | 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 | .\" |
ebbb5118 | 30 | .TH MREMAP 2 2010-06-10 "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) */" |
ceb6743d | 36 | .br |
fea681da MK |
37 | .B #include <sys/mman.h> |
38 | .sp | |
da8cb51e | 39 | .BI "void *mremap(void *" old_address ", size_t " old_size , |
ebbb5118 | 40 | .BI " size_t " new_size ", int " flags ", ... /* void *" new_address " */);" |
fea681da MK |
41 | .fi |
42 | .SH DESCRIPTION | |
60a90ecd MK |
43 | .BR mremap () |
44 | expands (or shrinks) an existing memory mapping, potentially | |
a8d55537 | 45 | moving it at the same time (controlled by the \fIflags\fP argument and |
fea681da MK |
46 | the available virtual address space). |
47 | ||
a8d55537 | 48 | \fIold_address\fP is the old address of the virtual memory block that you |
c13182ef | 49 | want to expand (or shrink). |
a8d55537 | 50 | Note that \fIold_address\fP has to be page |
67da5267 MK |
51 | aligned. |
52 | \fIold_size\fP is the old size of the | |
be7fff26 | 53 | virtual memory block. |
a8d55537 | 54 | \fInew_size\fP is the requested size of the |
c13182ef | 55 | virtual memory block after the resize. |
ebbb5118 MK |
56 | An optional fifth argument, |
57 | .IR new_address , | |
58 | may be provided; see the description of | |
59 | .B MREMAP_FIXED | |
60 | below. | |
fea681da | 61 | |
c13182ef MK |
62 | In Linux the memory is divided into pages. |
63 | A user process has (one or) | |
64 | several linear virtual memory segments. | |
65 | Each virtual memory segment has one | |
66 | or more mappings to real memory pages (in the page table). | |
67 | Each virtual memory segment has its own | |
68 | protection (access rights), which may cause | |
fea681da | 69 | a segmentation violation if the memory is accessed incorrectly (e.g., |
c13182ef MK |
70 | writing to a read-only segment). |
71 | Accessing virtual memory outside of the | |
fea681da MK |
72 | segments will also cause a segmentation violation. |
73 | ||
60a90ecd MK |
74 | .BR mremap () |
75 | uses the Linux page table scheme. | |
76 | .BR mremap () | |
77 | changes the | |
c13182ef | 78 | mapping between virtual addresses and memory pages. |
60a90ecd MK |
79 | This can be used to implement a very efficient |
80 | .BR realloc (3). | |
fea681da | 81 | |
a8d55537 | 82 | The \fIflags\fP bit-mask argument may be 0, or include the following flag: |
fea681da MK |
83 | .TP |
84 | .B MREMAP_MAYMOVE | |
ceb6743d MK |
85 | By default, if there is not sufficient space to expand a mapping |
86 | at its current location, then | |
87 | .BR mremap () | |
88 | fails. | |
c13182ef | 89 | If this flag is specified, then the kernel is permitted to |
ceb6743d MK |
90 | relocate the mapping to a new virtual address, if necessary. |
91 | If the mapping is relocated, | |
c13182ef MK |
92 | then absolute pointers into the old mapping location |
93 | become invalid (offsets relative to the starting address of | |
ceb6743d | 94 | the mapping should be employed). |
8107e4b7 MK |
95 | .TP |
96 | .BR MREMAP_FIXED " (since Linux 2.3.31)" | |
97 | This flag serves a similar purpose to the | |
98 | .B MAP_FIXED | |
99 | flag of | |
100 | .BR mmap (2). | |
101 | If this flag is specified, then | |
102 | .BR mremap () | |
103 | accepts a fifth argument, | |
104 | .IR "void *new_address" , | |
105 | which specifies a page-aligned address to which the mapping must | |
106 | be moved. | |
107 | Any previous mapping at the address range specified by | |
108 | .I new_address | |
109 | and | |
110 | .I new_size | |
111 | is unmapped. | |
c13182ef | 112 | If |
8107e4b7 | 113 | .B MREMAP_FIXED |
c13182ef | 114 | is specified, then |
0daa9e92 | 115 | .B MREMAP_MAYMOVE |
8107e4b7 | 116 | must also be specified. |
ceb6743d | 117 | .PP |
c13182ef | 118 | If the memory segment specified by |
ceb6743d | 119 | .I old_address |
c13182ef | 120 | and |
ceb6743d MK |
121 | .I old_size |
122 | is locked (using | |
0bfa087b | 123 | .BR mlock (2) |
ceb6743d MK |
124 | or similar), then this lock is maintained when the segment is |
125 | resized and/or relocated. | |
a85a10cb | 126 | As a consequence, the amount of memory locked by the process may change. |
47297adb | 127 | .SH RETURN VALUE |
60a90ecd MK |
128 | On success |
129 | .BR mremap () | |
130 | returns a pointer to the new virtual memory area. | |
fea681da MK |
131 | On error, the value |
132 | .B MAP_FAILED | |
009df872 | 133 | (that is, \fI(void\ *)\ \-1\fP) is returned, |
a8d55537 | 134 | and \fIerrno\fP is set appropriately. |
fea681da MK |
135 | .SH ERRORS |
136 | .TP | |
137 | .B EAGAIN | |
c13182ef | 138 | The caller tried to expand a memory segment that is locked, |
ceb6743d | 139 | but this was not possible without exceeding the |
682edefb MK |
140 | .B RLIMIT_MEMLOCK |
141 | resource limit. | |
fea681da MK |
142 | .TP |
143 | .B EFAULT | |
144 | "Segmentation fault." Some address in the range | |
145 | \fIold_address\fP to \fIold_address\fP+\fIold_size\fP is an invalid | |
146 | virtual memory address for this process. | |
682edefb MK |
147 | You can also get |
148 | .B EFAULT | |
149 | even if there exist mappings that cover the | |
fea681da MK |
150 | whole address space requested, but those mappings are of different types. |
151 | .TP | |
152 | .B EINVAL | |
4f76dae0 | 153 | An invalid argument was given. |
a8d55537 | 154 | Possible causes are: \fIold_address\fP was not |
4f76dae0 MK |
155 | page aligned; a value other than |
156 | .B MREMAP_MAYMOVE | |
c13182ef | 157 | or |
4f76dae0 MK |
158 | .B MREMAP_FIXED |
159 | was specified in | |
160 | .IR flags ; | |
161 | .I new_size | |
162 | was zero; | |
163 | .I new_size | |
c13182ef | 164 | or |
4f76dae0 MK |
165 | .I new_address |
166 | was invalid; | |
167 | or the new address range specified by | |
c13182ef MK |
168 | .I new_address |
169 | and | |
4f76dae0 MK |
170 | .I new_size |
171 | overlapped the old address range specified by | |
172 | .I old_address | |
173 | and | |
174 | .IR old_size ; | |
c13182ef | 175 | or |
4f76dae0 MK |
176 | .B MREMAP_FIXED |
177 | was specified without also specifying | |
178 | .BR MREMAP_MAYMOVE . | |
fea681da MK |
179 | .TP |
180 | .B ENOMEM | |
181 | The memory area cannot be expanded at the current virtual address, and the | |
182 | .B MREMAP_MAYMOVE | |
c13182ef | 183 | flag is not set in \fIflags\fP. |
fea681da | 184 | Or, there is not enough (virtual) memory available. |
47297adb | 185 | .SH CONFORMING TO |
8382f16d | 186 | This call is Linux-specific, and should not be used in programs |
b5d63e49 MK |
187 | intended to be portable. |
188 | .\" 4.2BSD had a (never actually implemented) | |
189 | .\" .BR mremap (2) | |
190 | .\" call with completely different semantics. | |
4f76dae0 | 191 | .SH NOTES |
8107e4b7 | 192 | Prior to version 2.4, glibc did not expose the definition of |
4f76dae0 | 193 | .BR MREMAP_FIXED , |
8107e4b7 | 194 | and the prototype for |
4f76dae0 | 195 | .BR mremap () |
8107e4b7 | 196 | did not allow for the |
4f76dae0 | 197 | .I new_address |
8107e4b7 | 198 | argument. |
47297adb | 199 | .SH SEE ALSO |
fea681da MK |
200 | .BR brk (2), |
201 | .BR getpagesize (2), | |
ceb6743d MK |
202 | .BR getrlimit (2), |
203 | .BR mlock (2), | |
fea681da MK |
204 | .BR mmap (2), |
205 | .BR sbrk (2), | |
206 | .BR malloc (3), | |
0a4f8b7b | 207 | .BR realloc (3) |
173fe7e7 DP |
208 | |
209 | Your favorite text book on operating systems | |
210 | for more information on paged memory | |
211 | (e.g., \fIModern Operating Systems\fP by Andrew S. Tanenbaum, | |
a8d55537 | 212 | \fIInside Linux\fP by Randolf Bentson, |
173fe7e7 | 213 | \fIThe Design of the UNIX Operating System\fP by Maurice J. Bach) |