]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" Copyright (c) 1996 Tom Bjorkholm <tomb@mydata.se> | |
4 | .\" | |
5 | .\" This is free documentation; you can redistribute it and/or | |
6 | .\" modify it under the terms of the GNU General Public License as | |
7 | .\" published by the Free Software Foundation; either version 2 of | |
8 | .\" the License, or (at your option) any later version. | |
9 | .\" | |
10 | .\" The GNU General Public License's references to "object code" | |
11 | .\" and "executables" are to be interpreted as the output of any | |
12 | .\" document formatting or typesetting system, including | |
13 | .\" intermediate and printed output. | |
14 | .\" | |
15 | .\" This manual is distributed in the hope that it will be useful, | |
16 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | .\" GNU General Public License for more details. | |
19 | .\" | |
20 | .\" You should have received a copy of the GNU General Public | |
21 | .\" License along with this manual; if not, write to the Free | |
22 | .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, | |
23 | .\" USA. | |
24 | .\" | |
25 | .\" 1996-04-11 Tom Bjorkholm <tomb@mydata.se> | |
26 | .\" First version written (1.3.86) | |
27 | .\" 1996-04-12 Tom Bjorkholm <tomb@mydata.se> | |
28 | .\" Update for Linux 1.3.87 and later | |
4f76dae0 | 29 | .\" 2005-10-11 mtk: Added NOTES for MREMAP_FIXED; revised EINVAL text. |
fea681da | 30 | .\" |
d9343c5c | 31 | .TH MREMAP 2 2005-09-13 "Linux" "Linux Programmer's Manual" |
fea681da | 32 | .SH NAME |
c13182ef | 33 | mremap \- re-map a virtual memory address |
fea681da | 34 | .SH SYNOPSIS |
3747f397 | 35 | .nf |
ceb6743d MK |
36 | .B #define _GNU_SOURCE |
37 | .br | |
fea681da MK |
38 | .B #include <sys/mman.h> |
39 | .sp | |
3747f397 MK |
40 | .BI "void *mremap(void *" old_address ", size_t " old_size ", |
41 | .BI " size_t " new_size ", int " flags ); | |
fea681da MK |
42 | .fi |
43 | .SH DESCRIPTION | |
60a90ecd MK |
44 | .BR mremap () |
45 | expands (or shrinks) an existing memory mapping, potentially | |
a8d55537 | 46 | moving it at the same time (controlled by the \fIflags\fP argument and |
fea681da MK |
47 | the available virtual address space). |
48 | ||
a8d55537 | 49 | \fIold_address\fP is the old address of the virtual memory block that you |
c13182ef | 50 | want to expand (or shrink). |
a8d55537 MK |
51 | Note that \fIold_address\fP has to be page |
52 | aligned. \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. |
fea681da | 56 | |
c13182ef MK |
57 | In Linux the memory is divided into pages. |
58 | A user process has (one or) | |
59 | several linear virtual memory segments. | |
60 | Each virtual memory segment has one | |
61 | or more mappings to real memory pages (in the page table). | |
62 | Each virtual memory segment has its own | |
63 | protection (access rights), which may cause | |
fea681da | 64 | a segmentation violation if the memory is accessed incorrectly (e.g., |
c13182ef MK |
65 | writing to a read-only segment). |
66 | Accessing virtual memory outside of the | |
fea681da MK |
67 | segments will also cause a segmentation violation. |
68 | ||
60a90ecd MK |
69 | .BR mremap () |
70 | uses the Linux page table scheme. | |
71 | .BR mremap () | |
72 | changes the | |
c13182ef | 73 | mapping between virtual addresses and memory pages. |
60a90ecd MK |
74 | This can be used to implement a very efficient |
75 | .BR realloc (3). | |
fea681da | 76 | |
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, | |
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. | |
c13182ef | 107 | If |
8107e4b7 | 108 | .B MREMAP_FIXED |
c13182ef MK |
109 | is specified, then |
110 | .BR MREMAP_MAYMOVE | |
8107e4b7 | 111 | must also be specified. |
ceb6743d | 112 | .PP |
c13182ef | 113 | If the memory segment specified by |
ceb6743d | 114 | .I old_address |
c13182ef | 115 | and |
ceb6743d MK |
116 | .I old_size |
117 | is locked (using | |
0bfa087b | 118 | .BR mlock (2) |
ceb6743d MK |
119 | or similar), then this lock is maintained when the segment is |
120 | resized and/or relocated. | |
a85a10cb | 121 | As a consequence, the amount of memory locked by the process may change. |
fea681da | 122 | .SH "RETURN VALUE" |
60a90ecd MK |
123 | On success |
124 | .BR mremap () | |
125 | returns a pointer to the new virtual memory area. | |
fea681da MK |
126 | On error, the value |
127 | .B MAP_FAILED | |
7a63e1d7 | 128 | (that is, \fB(void *) \-1)\fP is returned, |
a8d55537 | 129 | and \fIerrno\fP is set appropriately. |
fea681da MK |
130 | .SH ERRORS |
131 | .TP | |
132 | .B EAGAIN | |
c13182ef | 133 | The caller tried to expand a memory segment that is locked, |
ceb6743d | 134 | but this was not possible without exceeding the |
682edefb MK |
135 | .B RLIMIT_MEMLOCK |
136 | resource limit. | |
fea681da MK |
137 | .TP |
138 | .B EFAULT | |
139 | "Segmentation fault." Some address in the range | |
140 | \fIold_address\fP to \fIold_address\fP+\fIold_size\fP is an invalid | |
141 | virtual memory address for this process. | |
682edefb MK |
142 | You can also get |
143 | .B EFAULT | |
144 | even if there exist mappings that cover the | |
fea681da MK |
145 | whole address space requested, but those mappings are of different types. |
146 | .TP | |
147 | .B EINVAL | |
4f76dae0 | 148 | An invalid argument was given. |
a8d55537 | 149 | Possible causes are: \fIold_address\fP was not |
4f76dae0 MK |
150 | page aligned; a value other than |
151 | .B MREMAP_MAYMOVE | |
c13182ef | 152 | or |
4f76dae0 MK |
153 | .B MREMAP_FIXED |
154 | was specified in | |
155 | .IR flags ; | |
156 | .I new_size | |
157 | was zero; | |
158 | .I new_size | |
c13182ef | 159 | or |
4f76dae0 MK |
160 | .I new_address |
161 | was invalid; | |
162 | or the new address range specified by | |
c13182ef MK |
163 | .I new_address |
164 | and | |
4f76dae0 MK |
165 | .I new_size |
166 | overlapped the old address range specified by | |
167 | .I old_address | |
168 | and | |
169 | .IR old_size ; | |
c13182ef | 170 | or |
4f76dae0 MK |
171 | .B MREMAP_FIXED |
172 | was specified without also specifying | |
173 | .BR MREMAP_MAYMOVE . | |
fea681da MK |
174 | .TP |
175 | .B ENOMEM | |
176 | The memory area cannot be expanded at the current virtual address, and the | |
177 | .B MREMAP_MAYMOVE | |
c13182ef | 178 | flag is not set in \fIflags\fP. |
fea681da | 179 | Or, there is not enough (virtual) memory available. |
a1d5f77c MK |
180 | .SH "CONFORMING TO" |
181 | This call is Linux specific, and should not be used in programs | |
b5d63e49 MK |
182 | intended to be portable. |
183 | .\" 4.2BSD had a (never actually implemented) | |
184 | .\" .BR mremap (2) | |
185 | .\" call with completely different semantics. | |
4f76dae0 | 186 | .SH NOTES |
8107e4b7 | 187 | Prior to version 2.4, glibc did not expose the definition of |
4f76dae0 | 188 | .BR MREMAP_FIXED , |
8107e4b7 | 189 | and the prototype for |
4f76dae0 | 190 | .BR mremap () |
8107e4b7 | 191 | did not allow for the |
4f76dae0 | 192 | .I new_address |
8107e4b7 | 193 | argument. |
fea681da MK |
194 | .SH "SEE ALSO" |
195 | .BR brk (2), | |
196 | .BR getpagesize (2), | |
ceb6743d MK |
197 | .BR getrlimit (2), |
198 | .BR mlock (2), | |
fea681da MK |
199 | .BR mmap (2), |
200 | .BR sbrk (2), | |
201 | .BR malloc (3), | |
0a90178c MK |
202 | .BR realloc (3), |
203 | .BR feature_test_macros (7) | |
fea681da MK |
204 | .P |
205 | Your favorite OS text book for more information on paged memory. | |
a8d55537 MK |
206 | (\fIModern Operating Systems\fP by Andrew S. Tannenbaum, |
207 | \fIInside Linux\fP by Randolf Bentson, | |
208 | \fIThe Design of the UNIX Operating System\fP by Maurice J. Bach.) |