393 lines
9.1 KiB
HTML
393 lines
9.1 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of MREMAP</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>MREMAP</H1>
|
|
Section: Linux Programmer's Manual (2)<BR>Updated: 2019-03-06<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
mremap - remap a virtual memory address
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#define _GNU_SOURCE</B> /* See <A HREF="/cgi-bin/man/man2html?7+feature_test_macros">feature_test_macros</A>(7) */
|
|
<B>#include <<A HREF="file:///usr/include/sys/mman.h">sys/mman.h</A>></B>
|
|
|
|
<B>void *mremap(void *</B><I>old_address</I><B>, size_t </B><I>old_size</I><B>,</B>
|
|
<B> size_t </B><I>new_size</I><B>, int </B><I>flags</I><B>, ... /* void *</B><I>new_address</I><B> */);</B>
|
|
</PRE>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>mremap</B>()
|
|
|
|
expands (or shrinks) an existing memory mapping, potentially
|
|
moving it at the same time (controlled by the <I>flags</I> argument and
|
|
the available virtual address space).
|
|
<P>
|
|
|
|
<I>old_address</I> is the old address of the virtual memory block that you
|
|
want to expand (or shrink).
|
|
Note that <I>old_address</I> has to be page
|
|
aligned.
|
|
<I>old_size</I> is the old size of the
|
|
virtual memory block.
|
|
<I>new_size</I> is the requested size of the
|
|
virtual memory block after the resize.
|
|
An optional fifth argument,
|
|
<I>new_address</I>,
|
|
|
|
may be provided; see the description of
|
|
<B>MREMAP_FIXED</B>
|
|
|
|
below.
|
|
<P>
|
|
|
|
If the value of <I>old_size</I> is zero, and <I>old_address</I> refers to
|
|
a shareable mapping (see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+mmap">mmap</A></B>(2)
|
|
|
|
<B>MAP_SHARED</B>),
|
|
|
|
then
|
|
<B>mremap</B>()
|
|
|
|
will create a new mapping of the same pages.
|
|
<I>new_size</I>
|
|
will be the size of the new mapping and the location of the new mapping
|
|
may be specified with <I>new_address</I>; see the description of
|
|
<B>MREMAP_FIXED</B>
|
|
|
|
below.
|
|
If a new mapping is requested via this method, then the
|
|
<B>MREMAP_MAYMOVE</B>
|
|
|
|
flag must also be specified.
|
|
<P>
|
|
|
|
In Linux the memory is divided into pages.
|
|
A user process has (one or)
|
|
several linear virtual memory segments.
|
|
Each virtual memory segment has one
|
|
or more mappings to real memory pages (in the page table).
|
|
Each virtual memory segment has its own
|
|
protection (access rights), which may cause
|
|
a segmentation violation if the memory is accessed incorrectly (e.g.,
|
|
writing to a read-only segment).
|
|
Accessing virtual memory outside of the
|
|
segments will also cause a segmentation violation.
|
|
<P>
|
|
|
|
<B>mremap</B>()
|
|
|
|
uses the Linux page table scheme.
|
|
<B>mremap</B>()
|
|
|
|
changes the
|
|
mapping between virtual addresses and memory pages.
|
|
This can be used to implement a very efficient
|
|
<B><A HREF="/cgi-bin/man/man2html?3+realloc">realloc</A></B>(3).
|
|
|
|
<P>
|
|
|
|
The <I>flags</I> bit-mask argument may be 0, or include the following flag:
|
|
<DL COMPACT>
|
|
<DT id="1"><B>MREMAP_MAYMOVE</B>
|
|
|
|
<DD>
|
|
By default, if there is not sufficient space to expand a mapping
|
|
at its current location, then
|
|
<B>mremap</B>()
|
|
|
|
fails.
|
|
If this flag is specified, then the kernel is permitted to
|
|
relocate the mapping to a new virtual address, if necessary.
|
|
If the mapping is relocated,
|
|
then absolute pointers into the old mapping location
|
|
become invalid (offsets relative to the starting address of
|
|
the mapping should be employed).
|
|
<DT id="2"><B>MREMAP_FIXED</B> (since Linux 2.3.31)
|
|
|
|
<DD>
|
|
This flag serves a similar purpose to the
|
|
<B>MAP_FIXED</B>
|
|
|
|
flag of
|
|
<B><A HREF="/cgi-bin/man/man2html?2+mmap">mmap</A></B>(2).
|
|
|
|
If this flag is specified, then
|
|
<B>mremap</B>()
|
|
|
|
accepts a fifth argument,
|
|
<I>void *new_address</I>,
|
|
|
|
which specifies a page-aligned address to which the mapping must
|
|
be moved.
|
|
Any previous mapping at the address range specified by
|
|
<I>new_address</I>
|
|
|
|
and
|
|
<I>new_size</I>
|
|
|
|
is unmapped.
|
|
If
|
|
<B>MREMAP_FIXED</B>
|
|
|
|
is specified, then
|
|
<B>MREMAP_MAYMOVE</B>
|
|
|
|
must also be specified.
|
|
</DL>
|
|
<P>
|
|
|
|
If the memory segment specified by
|
|
<I>old_address</I>
|
|
|
|
and
|
|
<I>old_size</I>
|
|
|
|
is locked (using
|
|
<B><A HREF="/cgi-bin/man/man2html?2+mlock">mlock</A></B>(2)
|
|
|
|
or similar), then this lock is maintained when the segment is
|
|
resized and/or relocated.
|
|
As a consequence, the amount of memory locked by the process may change.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
On success
|
|
<B>mremap</B>()
|
|
|
|
returns a pointer to the new virtual memory area.
|
|
On error, the value
|
|
<B>MAP_FAILED</B>
|
|
|
|
(that is, <I>(void *) -1</I>) is returned,
|
|
and <I>errno</I> is set appropriately.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="3"><B>EAGAIN</B>
|
|
|
|
<DD>
|
|
The caller tried to expand a memory segment that is locked,
|
|
but this was not possible without exceeding the
|
|
<B>RLIMIT_MEMLOCK</B>
|
|
|
|
resource limit.
|
|
<DT id="4"><B>EFAULT</B>
|
|
|
|
<DD>
|
|
"Segmentation fault." Some address in the range
|
|
<I>old_address</I> to <I>old_address</I>+<I>old_size</I> is an invalid
|
|
virtual memory address for this process.
|
|
You can also get
|
|
<B>EFAULT</B>
|
|
|
|
even if there exist mappings that cover the
|
|
whole address space requested, but those mappings are of different types.
|
|
<DT id="5"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
An invalid argument was given.
|
|
Possible causes are:
|
|
<DL COMPACT><DT id="6"><DD>
|
|
<DL COMPACT>
|
|
<DT id="7">*<DD>
|
|
<I>old_address</I> was not
|
|
page aligned;
|
|
<DT id="8">*<DD>
|
|
a value other than
|
|
<B>MREMAP_MAYMOVE</B>
|
|
|
|
or
|
|
<B>MREMAP_FIXED</B>
|
|
|
|
was specified in
|
|
<I>flags</I>;
|
|
|
|
<DT id="9">*<DD>
|
|
<I>new_size</I>
|
|
|
|
was zero;
|
|
<DT id="10">*<DD>
|
|
<I>new_size</I>
|
|
|
|
or
|
|
<I>new_address</I>
|
|
|
|
was invalid;
|
|
<DT id="11">*<DD>
|
|
the new address range specified by
|
|
<I>new_address</I>
|
|
|
|
and
|
|
<I>new_size</I>
|
|
|
|
overlapped the old address range specified by
|
|
<I>old_address</I>
|
|
|
|
and
|
|
<I>old_size</I>;
|
|
|
|
<DT id="12">*<DD>
|
|
<B>MREMAP_FIXED</B>
|
|
|
|
was specified without also specifying
|
|
<B>MREMAP_MAYMOVE</B>;
|
|
|
|
<DT id="13">*<DD>
|
|
<I>old_size</I> was zero and <I>old_address</I> does not refer to a
|
|
shareable mapping (but see BUGS);
|
|
<DT id="14">*<DD>
|
|
<I>old_size</I> was zero and the
|
|
<B>MREMAP_MAYMOVE</B>
|
|
|
|
flag was not specified.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="15"><B>ENOMEM</B>
|
|
|
|
<DD>
|
|
The memory area cannot be expanded at the current virtual address, and the
|
|
<B>MREMAP_MAYMOVE</B>
|
|
|
|
flag is not set in <I>flags</I>.
|
|
Or, there is not enough (virtual) memory available.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
This call is Linux-specific, and should not be used in programs
|
|
intended to be portable.
|
|
|
|
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
Prior to version 2.4, glibc did not expose the definition of
|
|
<B>MREMAP_FIXED</B>,
|
|
|
|
and the prototype for
|
|
<B>mremap</B>()
|
|
|
|
did not allow for the
|
|
<I>new_address</I>
|
|
|
|
argument.
|
|
<P>
|
|
|
|
If
|
|
<B>mremap</B>()
|
|
|
|
is used to move or expand an area locked with
|
|
<B><A HREF="/cgi-bin/man/man2html?2+mlock">mlock</A></B>(2)
|
|
|
|
or equivalent, the
|
|
<B>mremap</B>()
|
|
|
|
call will make a best effort to populate the new area but will not fail
|
|
with
|
|
<B>ENOMEM</B>
|
|
|
|
if the area cannot be populated.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
Before Linux 4.14,
|
|
if
|
|
<I>old_size</I>
|
|
|
|
was zero and the mapping referred to by
|
|
<I>old_address</I>
|
|
|
|
was a private mapping
|
|
(<B><A HREF="/cgi-bin/man/man2html?2+mmap">mmap</A></B>(2) <B>MAP_PRIVATE</B>),
|
|
|
|
<B>mremap</B>()
|
|
|
|
created a new private mapping unrelated to the original mapping.
|
|
This behavior was unintended
|
|
and probably unexpected in user-space applications
|
|
(since the intention of
|
|
<B>mremap</B>()
|
|
|
|
is to create a new mapping based on the original mapping).
|
|
Since Linux 4.14,
|
|
|
|
<B>mremap</B>()
|
|
|
|
fails with the error
|
|
<B>EINVAL</B>
|
|
|
|
in this scenario.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+brk">brk</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+getpagesize">getpagesize</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+getrlimit">getrlimit</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+mlock">mlock</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+mmap">mmap</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+sbrk">sbrk</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+malloc">malloc</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+realloc">realloc</A></B>(3)
|
|
|
|
<P>
|
|
|
|
Your favorite text book on operating systems
|
|
for more information on paged memory
|
|
(e.g., <I>Modern Operating Systems</I> by Andrew S. Tanenbaum,
|
|
<I>Inside Linux</I> by Randolf Bentson,
|
|
<I>The Design of the UNIX Operating System</I> by Maurice J. Bach)
|
|
<A NAME="lbAK"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="16"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="17"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="18"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="19"><A HREF="#lbAE">RETURN VALUE</A><DD>
|
|
<DT id="20"><A HREF="#lbAF">ERRORS</A><DD>
|
|
<DT id="21"><A HREF="#lbAG">CONFORMING TO</A><DD>
|
|
<DT id="22"><A HREF="#lbAH">NOTES</A><DD>
|
|
<DT id="23"><A HREF="#lbAI">BUGS</A><DD>
|
|
<DT id="24"><A HREF="#lbAJ">SEE ALSO</A><DD>
|
|
<DT id="25"><A HREF="#lbAK">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:33 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|