mremap(2)

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

NAME

6       mremap - re-map a virtual memory address
7

SYNOPSIS

9       #define _GNU_SOURCE
10       #include <sys/mman.h>
11
12       void *mremap(void *old_address, size_t old_size,
13                    size_t new_size, int flags);
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.
25
26       In Linux the memory is divided into pages.  A user process has (one or)
27       several linear virtual memory segments.  Each  virtual  memory  segment
28       has  one  or  more  mappings  to real memory pages (in the page table).
29       Each virtual memory segment has its  own  protection  (access  rights),
30       which  may  cause  a  segmentation  violation if the memory is accessed
31       incorrectly (e.g., writing to a read-only segment).  Accessing  virtual
32       memory  outside  of  the segments will also cause a segmentation viola‐
33       tion.
34
35       mremap() uses the Linux page table scheme.  mremap() changes  the  map‐
36       ping  between  virtual addresses and memory pages.  This can be used to
37       implement a very efficient realloc().
38
39       The flags bit-mask argument may be 0, or include the following flag:
40
41       MREMAP_MAYMOVE
42              By default, if there is not sufficient space to expand a mapping
43              at  its  current location, then mremap() fails.  If this flag is
44              specified, then the kernel is permitted to relocate the  mapping
45              to a new virtual address, if necessary.  If the mapping is relo‐
46              cated, then absolute pointers  into  the  old  mapping  location
47              become  invalid (offsets relative to the starting address of the
48              mapping should be employed).
49
50       MREMAP_FIXED (since Linux 2.3.31)
51              This flag serves a similar purpose  to  the  MAP_FIXED  flag  of
52              mmap(2).   If  this  flag  is specified, then mremap() accepts a
53              fifth argument,  void  *new_address,  which  specifies  a  page-
54              aligned  address to which the mapping must be moved.  Any previ‐
55              ous mapping at the address range specified  by  new_address  and
56              new_size  is  unmapped.   If  MREMAP_FIXED  is  specified,  then
57              MREMAP_MAYMOVE must also be specified.
58
59       If the memory segment specified by old_address and old_size  is  locked
60       (using  mlock() or similar), then this lock is maintained when the seg‐
61       ment is resized and/or relocated.  As a consequence, the amount of mem‐
62       ory locked by the process may change.
63

RETURN VALUE

65       On  success  mremap() returns a pointer to the new virtual memory area.
66       On error, the value MAP_FAILED (that is, (void *) -1) is returned,  and
67       errno is set appropriately.
68

ERRORS

70       EAGAIN The  caller tried to expand a memory segment that is locked, but
71              this was  not  possible  without  exceeding  the  RLIMIT_MEMLOCK
72              resource limit.
73
74       EFAULT "Segmentation  fault."  Some address in the range old_address to
75              old_address+old_size is an invalid virtual  memory  address  for
76              this  process.  You can also get EFAULT even if there exist map‐
77              pings that cover the whole address space  requested,  but  those
78              mappings are of different types.
79
80       EINVAL An invalid argument was given.  Possible causes are: old_address
81              was not page aligned;  a  value  other  than  MREMAP_MAYMOVE  or
82              MREMAP_FIXED was specified in flags; new_size was zero; new_size
83              or new_address was invalid; or the new address  range  specified
84              by  new_address  and  new_size  overlapped the old address range
85              specified by old_address and old_size; or MREMAP_FIXED was spec‐
86              ified without also specifying MREMAP_MAYMOVE.
87
88       ENOMEM The  memory  area  cannot  be  expanded  at  the current virtual
89              address, and the MREMAP_MAYMOVE flag is not set in  flags.   Or,
90              there is not enough (virtual) memory available.
91

NOTES

93       Prior   to  version  2.4,  glibc  did  not  expose  the  definition  of
94       MREMAP_FIXED, and the prototype for mremap()  did  not  allow  for  the
95       new_address argument.
96

CONFORMING TO

98       This  call  is  Linux  specific,  and  should  not  be used in programs
99       intended to be portable.  4.2BSD had  a  (never  actually  implemented)
100       mremap(2) call with completely different semantics.
101