|
Packit |
7cfc04 |
.\" Copyright (c) 1996 Tom Bjorkholm <tomb@mydata.se>
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
|
|
Packit |
7cfc04 |
.\" This is free documentation; you can redistribute it and/or
|
|
Packit |
7cfc04 |
.\" modify it under the terms of the GNU General Public License as
|
|
Packit |
7cfc04 |
.\" published by the Free Software Foundation; either version 2 of
|
|
Packit |
7cfc04 |
.\" the License, or (at your option) any later version.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" The GNU General Public License's references to "object code"
|
|
Packit |
7cfc04 |
.\" and "executables" are to be interpreted as the output of any
|
|
Packit |
7cfc04 |
.\" document formatting or typesetting system, including
|
|
Packit |
7cfc04 |
.\" intermediate and printed output.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" This manual is distributed in the hope that it will be useful,
|
|
Packit |
7cfc04 |
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
Packit |
7cfc04 |
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
Packit |
7cfc04 |
.\" GNU General Public License for more details.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" You should have received a copy of the GNU General Public
|
|
Packit |
7cfc04 |
.\" License along with this manual; if not, see
|
|
Packit |
7cfc04 |
.\" <http://www.gnu.org/licenses/>.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" 1996-04-11 Tom Bjorkholm <tomb@mydata.se>
|
|
Packit |
7cfc04 |
.\" First version written (1.3.86)
|
|
Packit |
7cfc04 |
.\" 1996-04-12 Tom Bjorkholm <tomb@mydata.se>
|
|
Packit |
7cfc04 |
.\" Update for Linux 1.3.87 and later
|
|
Packit |
7cfc04 |
.\" 2005-10-11 mtk: Added NOTES for MREMAP_FIXED; revised EINVAL text.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH MREMAP 2 2017-09-25 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
mremap \- remap a virtual memory address
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
|
|
Packit |
7cfc04 |
.B #include <sys/mman.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "void *mremap(void *" old_address ", size_t " old_size ,
|
|
Packit |
7cfc04 |
.BI " size_t " new_size ", int " flags ", ... /* void *" new_address " */);"
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
.BR mremap ()
|
|
Packit |
7cfc04 |
expands (or shrinks) an existing memory mapping, potentially
|
|
Packit |
7cfc04 |
moving it at the same time (controlled by the \fIflags\fP argument and
|
|
Packit |
7cfc04 |
the available virtual address space).
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
\fIold_address\fP is the old address of the virtual memory block that you
|
|
Packit |
7cfc04 |
want to expand (or shrink).
|
|
Packit |
7cfc04 |
Note that \fIold_address\fP has to be page
|
|
Packit |
7cfc04 |
aligned.
|
|
Packit |
7cfc04 |
\fIold_size\fP is the old size of the
|
|
Packit |
7cfc04 |
virtual memory block.
|
|
Packit |
7cfc04 |
\fInew_size\fP is the requested size of the
|
|
Packit |
7cfc04 |
virtual memory block after the resize.
|
|
Packit |
7cfc04 |
An optional fifth argument,
|
|
Packit |
7cfc04 |
.IR new_address ,
|
|
Packit |
7cfc04 |
may be provided; see the description of
|
|
Packit |
7cfc04 |
.B MREMAP_FIXED
|
|
Packit |
7cfc04 |
below.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If the value of \fIold_size\fP is zero, and \fIold_address\fP refers to
|
|
Packit |
7cfc04 |
a shareable mapping (see
|
|
Packit |
7cfc04 |
.BR mmap (2)
|
|
Packit |
7cfc04 |
.BR MAP_SHARED ),
|
|
Packit |
7cfc04 |
then
|
|
Packit |
7cfc04 |
.BR mremap ()
|
|
Packit |
7cfc04 |
will create a new mapping of the same pages.
|
|
Packit |
7cfc04 |
\fInew_size\fP
|
|
Packit |
7cfc04 |
will be the size of the new mapping and the location of the new mapping
|
|
Packit |
7cfc04 |
may be specified with \fInew_address\fP; see the description of
|
|
Packit |
7cfc04 |
.B MREMAP_FIXED
|
|
Packit |
7cfc04 |
below.
|
|
Packit |
7cfc04 |
If a new mapping is requested via this method, then the
|
|
Packit |
7cfc04 |
.B MREMAP_MAYMOVE
|
|
Packit |
7cfc04 |
flag must also be specified.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
In Linux the memory is divided into pages.
|
|
Packit |
7cfc04 |
A user process has (one or)
|
|
Packit |
7cfc04 |
several linear virtual memory segments.
|
|
Packit |
7cfc04 |
Each virtual memory segment has one
|
|
Packit |
7cfc04 |
or more mappings to real memory pages (in the page table).
|
|
Packit |
7cfc04 |
Each virtual memory segment has its own
|
|
Packit |
7cfc04 |
protection (access rights), which may cause
|
|
Packit |
7cfc04 |
a segmentation violation if the memory is accessed incorrectly (e.g.,
|
|
Packit |
7cfc04 |
writing to a read-only segment).
|
|
Packit |
7cfc04 |
Accessing virtual memory outside of the
|
|
Packit |
7cfc04 |
segments will also cause a segmentation violation.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BR mremap ()
|
|
Packit |
7cfc04 |
uses the Linux page table scheme.
|
|
Packit |
7cfc04 |
.BR mremap ()
|
|
Packit |
7cfc04 |
changes the
|
|
Packit |
7cfc04 |
mapping between virtual addresses and memory pages.
|
|
Packit |
7cfc04 |
This can be used to implement a very efficient
|
|
Packit |
7cfc04 |
.BR realloc (3).
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The \fIflags\fP bit-mask argument may be 0, or include the following flag:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MREMAP_MAYMOVE
|
|
Packit |
7cfc04 |
By default, if there is not sufficient space to expand a mapping
|
|
Packit |
7cfc04 |
at its current location, then
|
|
Packit |
7cfc04 |
.BR mremap ()
|
|
Packit |
7cfc04 |
fails.
|
|
Packit |
7cfc04 |
If this flag is specified, then the kernel is permitted to
|
|
Packit |
7cfc04 |
relocate the mapping to a new virtual address, if necessary.
|
|
Packit |
7cfc04 |
If the mapping is relocated,
|
|
Packit |
7cfc04 |
then absolute pointers into the old mapping location
|
|
Packit |
7cfc04 |
become invalid (offsets relative to the starting address of
|
|
Packit |
7cfc04 |
the mapping should be employed).
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR MREMAP_FIXED " (since Linux 2.3.31)"
|
|
Packit |
7cfc04 |
This flag serves a similar purpose to the
|
|
Packit |
7cfc04 |
.B MAP_FIXED
|
|
Packit |
7cfc04 |
flag of
|
|
Packit |
7cfc04 |
.BR mmap (2).
|
|
Packit |
7cfc04 |
If this flag is specified, then
|
|
Packit |
7cfc04 |
.BR mremap ()
|
|
Packit |
7cfc04 |
accepts a fifth argument,
|
|
Packit |
7cfc04 |
.IR "void\ *new_address" ,
|
|
Packit |
7cfc04 |
which specifies a page-aligned address to which the mapping must
|
|
Packit |
7cfc04 |
be moved.
|
|
Packit |
7cfc04 |
Any previous mapping at the address range specified by
|
|
Packit |
7cfc04 |
.I new_address
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I new_size
|
|
Packit |
7cfc04 |
is unmapped.
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.B MREMAP_FIXED
|
|
Packit |
7cfc04 |
is specified, then
|
|
Packit |
7cfc04 |
.B MREMAP_MAYMOVE
|
|
Packit |
7cfc04 |
must also be specified.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If the memory segment specified by
|
|
Packit |
7cfc04 |
.I old_address
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I old_size
|
|
Packit |
7cfc04 |
is locked (using
|
|
Packit |
7cfc04 |
.BR mlock (2)
|
|
Packit |
7cfc04 |
or similar), then this lock is maintained when the segment is
|
|
Packit |
7cfc04 |
resized and/or relocated.
|
|
Packit |
7cfc04 |
As a consequence, the amount of memory locked by the process may change.
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
On success
|
|
Packit |
7cfc04 |
.BR mremap ()
|
|
Packit |
7cfc04 |
returns a pointer to the new virtual memory area.
|
|
Packit |
7cfc04 |
On error, the value
|
|
Packit |
7cfc04 |
.B MAP_FAILED
|
|
Packit |
7cfc04 |
(that is, \fI(void\ *)\ \-1\fP) is returned,
|
|
Packit |
7cfc04 |
and \fIerrno\fP is set appropriately.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EAGAIN
|
|
Packit |
7cfc04 |
The caller tried to expand a memory segment that is locked,
|
|
Packit |
7cfc04 |
but this was not possible without exceeding the
|
|
Packit |
7cfc04 |
.B RLIMIT_MEMLOCK
|
|
Packit |
7cfc04 |
resource limit.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EFAULT
|
|
Packit |
7cfc04 |
"Segmentation fault." Some address in the range
|
|
Packit |
7cfc04 |
\fIold_address\fP to \fIold_address\fP+\fIold_size\fP is an invalid
|
|
Packit |
7cfc04 |
virtual memory address for this process.
|
|
Packit |
7cfc04 |
You can also get
|
|
Packit |
7cfc04 |
.B EFAULT
|
|
Packit |
7cfc04 |
even if there exist mappings that cover the
|
|
Packit |
7cfc04 |
whole address space requested, but those mappings are of different types.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
An invalid argument was given.
|
|
Packit |
7cfc04 |
Possible causes are:
|
|
Packit |
7cfc04 |
.RS
|
|
Packit |
7cfc04 |
.IP * 3
|
|
Packit |
7cfc04 |
\fIold_address\fP was not
|
|
Packit |
7cfc04 |
page aligned;
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
a value other than
|
|
Packit |
7cfc04 |
.B MREMAP_MAYMOVE
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.B MREMAP_FIXED
|
|
Packit |
7cfc04 |
was specified in
|
|
Packit |
7cfc04 |
.IR flags ;
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
.I new_size
|
|
Packit |
7cfc04 |
was zero;
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
.I new_size
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.I new_address
|
|
Packit |
7cfc04 |
was invalid;
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
the new address range specified by
|
|
Packit |
7cfc04 |
.I new_address
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I new_size
|
|
Packit |
7cfc04 |
overlapped the old address range specified by
|
|
Packit |
7cfc04 |
.I old_address
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.IR old_size ;
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
.B MREMAP_FIXED
|
|
Packit |
7cfc04 |
was specified without also specifying
|
|
Packit |
7cfc04 |
.BR MREMAP_MAYMOVE ;
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
\fIold_size\fP was zero and \fIold_address\fP does not refer to a
|
|
Packit |
7cfc04 |
shareable mapping (but see BUGS);
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
\fIold_size\fP was zero and the
|
|
Packit |
7cfc04 |
.BR MREMAP_MAYMOVE
|
|
Packit |
7cfc04 |
flag was not specified.
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ENOMEM
|
|
Packit |
7cfc04 |
The memory area cannot be expanded at the current virtual address, and the
|
|
Packit |
7cfc04 |
.B MREMAP_MAYMOVE
|
|
Packit |
7cfc04 |
flag is not set in \fIflags\fP.
|
|
Packit |
7cfc04 |
Or, there is not enough (virtual) memory available.
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
This call is Linux-specific, and should not be used in programs
|
|
Packit |
7cfc04 |
intended to be portable.
|
|
Packit |
7cfc04 |
.\" 4.2BSD had a (never actually implemented)
|
|
Packit |
7cfc04 |
.\" .BR mremap (2)
|
|
Packit |
7cfc04 |
.\" call with completely different semantics.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
Prior to version 2.4, glibc did not expose the definition of
|
|
Packit |
7cfc04 |
.BR MREMAP_FIXED ,
|
|
Packit |
7cfc04 |
and the prototype for
|
|
Packit |
7cfc04 |
.BR mremap ()
|
|
Packit |
7cfc04 |
did not allow for the
|
|
Packit |
7cfc04 |
.I new_address
|
|
Packit |
7cfc04 |
argument.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.BR mremap ()
|
|
Packit |
7cfc04 |
is used to move or expand an area locked with
|
|
Packit |
7cfc04 |
.BR mlock (2)
|
|
Packit |
7cfc04 |
or equivalent, the
|
|
Packit |
7cfc04 |
.BR mremap ()
|
|
Packit |
7cfc04 |
call will make a best effort to populate the new area but will not fail
|
|
Packit |
7cfc04 |
with
|
|
Packit |
7cfc04 |
.B ENOMEM
|
|
Packit |
7cfc04 |
if the area cannot be populated.
|
|
Packit |
7cfc04 |
.SH BUGS
|
|
Packit |
7cfc04 |
Before Linux 4.14,
|
|
Packit |
7cfc04 |
if
|
|
Packit |
7cfc04 |
.I old_size
|
|
Packit |
7cfc04 |
was zero and the mapping referred to by
|
|
Packit |
7cfc04 |
.I old_address
|
|
Packit |
7cfc04 |
was a private mapping
|
|
Packit |
7cfc04 |
.RB ( mmap "(2) " MAP_PRIVATE ),
|
|
Packit |
7cfc04 |
.BR mremap ()
|
|
Packit |
7cfc04 |
created a new private mapping unrelated to the original mapping.
|
|
Packit |
7cfc04 |
This behavior was unintended
|
|
Packit |
7cfc04 |
and probably unexpected in user-space applications
|
|
Packit |
7cfc04 |
(since the intention of
|
|
Packit |
7cfc04 |
.BR mremap ()
|
|
Packit |
7cfc04 |
is to create a new mapping based on the original mapping).
|
|
Packit |
7cfc04 |
Since Linux 4.14,
|
|
Packit |
7cfc04 |
.\" commit dba58d3b8c5045ad89c1c95d33d01451e3964db7
|
|
Packit |
7cfc04 |
.BR mremap ()
|
|
Packit |
7cfc04 |
fails with the error
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
in this scenario.
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR brk (2),
|
|
Packit |
7cfc04 |
.BR getpagesize (2),
|
|
Packit |
7cfc04 |
.BR getrlimit (2),
|
|
Packit |
7cfc04 |
.BR mlock (2),
|
|
Packit |
7cfc04 |
.BR mmap (2),
|
|
Packit |
7cfc04 |
.BR sbrk (2),
|
|
Packit |
7cfc04 |
.BR malloc (3),
|
|
Packit |
7cfc04 |
.BR realloc (3)
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Your favorite text book on operating systems
|
|
Packit |
7cfc04 |
for more information on paged memory
|
|
Packit |
7cfc04 |
(e.g., \fIModern Operating Systems\fP by Andrew S. Tanenbaum,
|
|
Packit |
7cfc04 |
\fIInside Linux\fP by Randolf Bentson,
|
|
Packit |
7cfc04 |
\fIThe Design of the UNIX Operating System\fP by Maurice J. Bach)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|