original/man2/mremap.2

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