1MREMAP(2)                  Linux Programmer's Manual                 MREMAP(2)
2
3
4

NAME

6       mremap - remap a virtual memory address
7

SYNOPSIS

9       #define _GNU_SOURCE         /* See feature_test_macros(7) */
10       #include <sys/mman.h>
11
12       void *mremap(void *old_address, size_t old_size,
13                    size_t new_size, int flags, ... /* void *new_address */);
14

DESCRIPTION

16       mremap()  expands  (or shrinks) an existing memory mapping, potentially
17       moving it at the same time (controlled by the flags  argument  and  the
18       available virtual address space).
19
20       old_address  is  the  old  address of the virtual memory block that you
21       want to expand (or shrink).  Note  that  old_address  has  to  be  page
22       aligned.   old_size  is  the  old  size  of  the  virtual memory block.
23       new_size is the requested size of the virtual memory  block  after  the
24       resize.   An optional fifth argument, new_address, may be provided; see
25       the description of MREMAP_FIXED below.
26
27       If the value of old_size is zero, and old_address refers to a shareable
28       mapping  (see mmap(2) MAP_SHARED), then mremap() will create a new map‐
29       ping of the same pages.  new_size will be the size of the  new  mapping
30       and  the location of the new mapping may be specified with new_address;
31       see the description  of  MREMAP_FIXED  below.   If  a  new  mapping  is
32       requested  via  this  method, then the MREMAP_MAYMOVE flag must also be
33       specified.
34
35       In Linux the memory is divided into pages.  A user process has (one or)
36       several  linear  virtual  memory segments.  Each virtual memory segment
37       has one or more mappings to real memory  pages  (in  the  page  table).
38       Each  virtual  memory  segment  has its own protection (access rights),
39       which may cause a segmentation violation  if  the  memory  is  accessed
40       incorrectly  (e.g., writing to a read-only segment).  Accessing virtual
41       memory outside of the segments will also cause  a  segmentation  viola‐
42       tion.
43
44       mremap()  uses  the Linux page table scheme.  mremap() changes the map‐
45       ping between virtual addresses and memory pages.  This can be  used  to
46       implement a very efficient realloc(3).
47
48       The flags bit-mask argument may be 0, or include the following flag:
49
50       MREMAP_MAYMOVE
51              By default, if there is not sufficient space to expand a mapping
52              at its current location, then mremap() fails.  If this  flag  is
53              specified,  then the kernel is permitted to relocate the mapping
54              to a new virtual address, if necessary.  If the mapping is relo‐
55              cated,  then  absolute  pointers  into  the old mapping location
56              become invalid (offsets relative to the starting address of  the
57              mapping should be employed).
58
59       MREMAP_FIXED (since Linux 2.3.31)
60              This  flag  serves  a  similar  purpose to the MAP_FIXED flag of
61              mmap(2).  If this flag is specified,  then  mremap()  accepts  a
62              fifth  argument,  void *new_address,  which  specifies  a  page-
63              aligned address to which the mapping must be moved.  Any  previ‐
64              ous  mapping  at  the address range specified by new_address and
65              new_size  is  unmapped.   If  MREMAP_FIXED  is  specified,  then
66              MREMAP_MAYMOVE must also be specified.
67
68       If  the  memory segment specified by old_address and old_size is locked
69       (using mlock(2) or similar), then this lock is maintained when the seg‐
70       ment is resized and/or relocated.  As a consequence, the amount of mem‐
71       ory locked by the process may change.
72

RETURN VALUE

74       On success mremap() returns a pointer to the new virtual  memory  area.
75       On  error, the value MAP_FAILED (that is, (void *) -1) is returned, and
76       errno is set appropriately.
77

ERRORS

79       EAGAIN The caller tried to expand a memory segment that is locked,  but
80              this  was  not  possible  without  exceeding  the RLIMIT_MEMLOCK
81              resource limit.
82
83       EFAULT "Segmentation fault." Some address in the range  old_address  to
84              old_address+old_size  is  an  invalid virtual memory address for
85              this process.  You can also get EFAULT even if there exist  map‐
86              pings  that  cover  the whole address space requested, but those
87              mappings are of different types.
88
89       EINVAL An invalid argument was given.  Possible causes are:
90
91              *  old_address was not page aligned;
92
93              *  a value other than MREMAP_MAYMOVE or MREMAP_FIXED was  speci‐
94                 fied in flags;
95
96              *  new_size was zero;
97
98              *  new_size or new_address was invalid;
99
100              *  the  new  address range specified by new_address and new_size
101                 overlapped the old address range specified by old_address and
102                 old_size;
103
104              *  MREMAP_FIXED    was   specified   without   also   specifying
105                 MREMAP_MAYMOVE;
106
107              *  old_size was zero and old_address does not refer to a  share‐
108                 able mapping (but see BUGS);
109
110              *  old_size  was zero and the MREMAP_MAYMOVE flag was not speci‐
111                 fied.
112
113       ENOMEM The memory area  cannot  be  expanded  at  the  current  virtual
114              address,  and  the MREMAP_MAYMOVE flag is not set in flags.  Or,
115              there is not enough (virtual) memory available.
116

CONFORMING TO

118       This call is  Linux-specific,  and  should  not  be  used  in  programs
119       intended to be portable.
120

NOTES

122       Prior   to  version  2.4,  glibc  did  not  expose  the  definition  of
123       MREMAP_FIXED, and the prototype for mremap()  did  not  allow  for  the
124       new_address argument.
125
126       If  mremap()  is used to move or expand an area locked with mlock(2) or
127       equivalent, the mremap() call will make a best effort to  populate  the
128       new area but will not fail with ENOMEM if the area cannot be populated.
129

BUGS

131       Before  Linux 4.14, if old_size was zero and the mapping referred to by
132       old_address was a private mapping (mmap(2) MAP_PRIVATE), mremap()  cre‐
133       ated  a  new  private  mapping unrelated to the original mapping.  This
134       behavior was unintended and probably unexpected in user-space  applica‐
135       tions (since the intention of mremap() is to create a new mapping based
136       on the original mapping).  Since Linux 4.14, mremap()  fails  with  the
137       error EINVAL in this scenario.
138

SEE ALSO

140       brk(2),  getpagesize(2), getrlimit(2), mlock(2), mmap(2), sbrk(2), mal‐
141       loc(3), realloc(3)
142
143       Your favorite text book on operating systems for  more  information  on
144       paged  memory  (e.g.,  Modern Operating Systems by Andrew S. Tanenbaum,
145       Inside Linux by Randolf Bentson, The Design of the UNIX Operating  Sys‐
146       tem by Maurice J. Bach)
147

COLOPHON

149       This  page  is  part of release 4.15 of the Linux man-pages project.  A
150       description of the project, information about reporting bugs,  and  the
151       latest     version     of     this    page,    can    be    found    at
152       https://www.kernel.org/doc/man-pages/.
153
154
155
156Linux                             2017-09-25                         MREMAP(2)
Impressum