original/man2/mremap.2

   1 .\" Copyright (c) 1996 Tom Bjorkholm <tomb@mydata.se>
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   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
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  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
  28 .\" 2005-10-11 mtk: Added NOTES for MREMAP_FIXED; revised EINVAL text.
  29 .\"
  30 .TH MREMAP 2 2010-06-10 "Linux" "Linux Programmer's Manual"
  31 .SH NAME
  32 mremap \- remap a virtual memory address
  33 .SH SYNOPSIS
  34 .nf
  35 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  36 .br
  37 .B #include <sys/mman.h>
  38 .sp
  39 .BI "void *mremap(void *" old_address ", size_t " old_size ,
  40 .BI "             size_t " new_size ", int " flags ", ... /* void *" new_address " */);"
  41 .fi
  42 .SH DESCRIPTION
  43 .BR mremap ()
  44 expands (or shrinks) an existing memory mapping, potentially
  45 moving it at the same time (controlled by the \fIflags\fP argument and
  46 the available virtual address space).
  47
  48 \fIold_address\fP is the old address of the virtual memory block that you
  49 want to expand (or shrink).
  50 Note that \fIold_address\fP has to be page
  51 aligned.
  52 \fIold_size\fP is the old size of the
  53 virtual memory block.
  54 \fInew_size\fP is the requested size of the
  55 virtual memory block after the resize.
  56 An optional fifth argument,
  57 .IR new_address ,
  58 may be provided; see the description of
  59 .B MREMAP_FIXED
  60 below.
  61
  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
  69 a segmentation violation if the memory is accessed incorrectly (e.g.,
  70 writing to a read-only segment).
  71 Accessing virtual memory outside of the
  72 segments will also cause a segmentation violation.
  73
  74 .BR mremap ()
  75 uses the Linux page table scheme.
  76 .BR mremap ()
  77 changes the
  78 mapping between virtual addresses and memory pages.
  79 This can be used to implement a very efficient
  80 .BR realloc (3).
  81
  82 The \fIflags\fP bit-mask argument may be 0, or include the following flag:
  83 .TP
  84 .B MREMAP_MAYMOVE
  85 By default, if there is not sufficient space to expand a mapping
  86 at its current location, then
  87 .BR mremap ()
  88 fails.
  89 If this flag is specified, then the kernel is permitted to
  90 relocate the mapping to a new virtual address, if necessary.
  91 If the mapping is relocated,
  92 then absolute pointers into the old mapping location
  93 become invalid (offsets relative to the starting address of
  94 the mapping should be employed).
  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.
 112 If
 113 .B MREMAP_FIXED
 114 is specified, then
 115 .B MREMAP_MAYMOVE
 116 must also be specified.
 117 .PP
 118 If the memory segment specified by
 119 .I old_address
 120 and
 121 .I old_size
 122 is locked (using
 123 .BR mlock (2)
 124 or similar), then this lock is maintained when the segment is
 125 resized and/or relocated.
 126 As a consequence, the amount of memory locked by the process may change.
 127 .SH RETURN VALUE
 128 On success
 129 .BR mremap ()
 130 returns a pointer to the new virtual memory area.
 131 On error, the value
 132 .B MAP_FAILED
 133 (that is, \fI(void\ *)\ \-1\fP) is returned,
 134 and \fIerrno\fP is set appropriately.
 135 .SH ERRORS
 136 .TP
 137 .B EAGAIN
 138 The caller tried to expand a memory segment that is locked,
 139 but this was not possible without exceeding the
 140 .B RLIMIT_MEMLOCK
 141 resource limit.
 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.
 147 You can also get
 148 .B EFAULT
 149 even if there exist mappings that cover the
 150 whole address space requested, but those mappings are of different types.
 151 .TP
 152 .B EINVAL
 153 An invalid argument was given.
 154 Possible causes are: \fIold_address\fP was not
 155 page aligned; a value other than
 156 .B MREMAP_MAYMOVE
 157 or
 158 .B MREMAP_FIXED
 159 was specified in
 160 .IR flags ;
 161 .I new_size
 162 was zero;
 163 .I new_size
 164 or
 165 .I new_address
 166 was invalid;
 167 or the new address range specified by
 168 .I new_address
 169 and
 170 .I new_size
 171 overlapped the old address range specified by
 172 .I old_address
 173 and
 174 .IR old_size ;
 175 or
 176 .B MREMAP_FIXED
 177 was specified without also specifying
 178 .BR MREMAP_MAYMOVE .
 179 .TP
 180 .B ENOMEM
 181 The memory area cannot be expanded at the current virtual address, and the
 182 .B MREMAP_MAYMOVE
 183 flag is not set in \fIflags\fP.
 184 Or, there is not enough (virtual) memory available.
 185 .SH CONFORMING TO
 186 This call is Linux-specific, and should not be used in programs
 187 intended to be portable.
 188 .\" 4.2BSD had a (never actually implemented)
 189 .\" .BR mremap (2)
 190 .\" call with completely different semantics.
 191 .SH NOTES
 192 Prior to version 2.4, glibc did not expose the definition of
 193 .BR MREMAP_FIXED ,
 194 and the prototype for
 195 .BR mremap ()
 196 did not allow for the
 197 .I new_address
 198 argument.
 199 .SH SEE ALSO
 200 .BR brk (2),
 201 .BR getpagesize (2),
 202 .BR getrlimit (2),
 203 .BR mlock (2),
 204 .BR mmap (2),
 205 .BR sbrk (2),
 206 .BR malloc (3),
 207 .BR realloc (3)
 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,
 212 \fIInside Linux\fP by Randolf Bentson,
 213 \fIThe Design of the UNIX Operating System\fP by Maurice J. Bach)
 214 .SH COLOPHON
 215 This page is part of release 3.67 of the Linux
 216 .I man-pages
 217 project.
 218 A description of the project,
 219 information about reporting bugs,
 220 and the latest version of this page,
 221 can be found at
 222 \%http://www.kernel.org/doc/man\-pages/.