Name
mmap, munmap — map or unmap files or devices into
memory
Synopsis
#include <sys/mman.h>
void
*mmap( |
void * |
start, |
| |
size_t |
length, |
| |
int |
prot, |
| |
int |
flags, |
| |
int |
fd, |
| |
off_t |
offset); |
int
munmap( |
void * |
start, |
| |
size_t |
length); |
DESCRIPTION
mmap() creates a new mapping
in the virtual address space of the calling process. The
starting address for the new mapping is specified in
start. The length argument specifies the
length of the mapping.
If start is NULL,
then the kernel chooses the address at which to create the
mapping; this is the most portable method of creating a new
mapping. If start is
not NULL, then the kernel takes it as a hint about where to
place the mapping; on Linux, the mapping will be created at
the next higher page boundary. The address of the new mapping
is returned as the result of the call.
The contents of a file mapping (as opposed to an anonymous
mapping; see MAP_ANONYMOUS
below), are initialised using length bytes starting at offset
offset in the file
(or other object) referred to by the file descriptor
fd. offset must be a multiple of
the page size as returned by sysconf(_SC_PAGE_SIZE).
The prot argument
describes the desired memory protection of the mapping (and
must not conflict with the open mode of the file). It is
either PROT_NONE or the bitwise
OR of one or more of the following flags:
PROT_EXEC-
Pages may be executed.
PROT_READ-
Pages may be read.
PROT_WRITE-
Pages may be written.
PROT_NONE-
Pages may not be accessed.
The flags argument
determines whether updates to the mapping are visible to
other processes mapping the same region, and whether updates
are caried through to the underlying file. This behaviour is
determined by including exactly one of the following values
in flags:
MAP_SHARED-
Share this mapping. Updates to the mapping are
visible to other processes that map this file, and are
carried through to the underlying file. The file may
not actually be updated until msync(2) or munmap(2) is
called.
MAP_PRIVATE-
Create a private copy-on-write mapping. Updates to
the mapping are not visible to other processes mapping
the same file, and are not carried through to the
underlying file. It is unspecified whether changes made
to the file after the mmap() call are visible in the mapped
region.
Both of these flags are described in POSIX.1-2001.
In addition, zero or more of the following values can be
ORed in flags:
MAP_32BIT-
Put the mapping into the first 2GB of the process
address space. Ignored when MAP_FIXED is set. This flag is
currently only supported on x86-64 for 64bit
programs.
MAP_ANON-
Synonym for MAP_ANONYMOUS. Deprecated.
MAP_ANONYMOUS-
The mapping is not backed by any file; its contents
are initialised to zero. The fd and offset arguments are
ignored; however, some implementations require
fd to be
−1 if MAP_ANONYMOUS
(or MAP_ANON) is
specified, and portable applications should ensure
this. The use of MAP_ANONYMOUS in conjunction with
MAP_SHARED is only
supported on Linux since kernel 2.4.
MAP_DENYWRITE-
This flag is ignored. (Long ago, it signalled that
attempts to write to the underlying file should fail
with ETXTBUSY. But this
was a source of denial-of-service attacks.)
MAP_EXECUTABLE-
This flag is ignored.
MAP_FILE-
Compatibility flag. Ignored.
MAP_FIXED-
Don't interpret start as a hint: place
the mapping at exactly that address. start must be a multiple
of the page size. If the memory region specified by
start and
len overlaps
pages of any existing mapping(s), then the overlapped
part of the existing mapping(s) will be discarded. If
the specified address cannot be used, mmap() will fail. Because requiring a
fixed address for a mapping is less portable, the use
of this option is discouraged.
MAP_GROWSDOWN-
Used for stacks. Indicates to the kernel virtual
memory system that the mapping should extend downwards
in memory.
MAP_LOCKED (since Linux
2.5.37)-
Lock the pages of the mapped region into memory in
the manner of mlock(2). This flag
is ignored in older kernels.
MAP_NONBLOCK (since Linux
2.5.46)-
Only meaningful in conjunction with MAP_POPULATE. Don't perform
read-ahead: only create page tables entries for pages
that are already present in RAM.
MAP_NORESERVE-
Do not reserve swap space for this mapping. When
swap space is reserved, one has the guarantee that it
is possible to modify the mapping. When swap space is
not reserved one might get SIGSEGV upon a write if no
physical memory is available. See also the discussion
of the file /proc/sys/vm/overcommit_memory in
proc(5). In kernels
before 2.6, this flag only had effect for private
writable mappings.
MAP_POPULATE (since Linux
2.5.46)-
Populate (prefault) page tables for a file mapping,
by performing read-ahead on the file. Later accesses to
the mapping will not be blocked by page faults.
Of the above flags, only MAP_FIXED is specified in POSIX.1-2001.
However, most systems also support MAP_ANONYMOUS (or its synonym MAP_ANON).
Some systems document the additional flags MAP_AUTOGROW,
MAP_AUTORESRV, MAP_COPY, and MAP_LOCAL.
Memory mapped by mmap() is
preserved across fork(2), with the same
attributes.
A file is mapped in multiples of the page size. For a file
that is not a multiple of the page size, the remaining memory
is zeroed when mapped, and writes to that region are not
written out to the file. The effect of changing the size of
the underlying file of a mapping on the pages that correspond
to added or removed regions of the file is unspecified.
The munmap() system call
deletes the mappings for the specified address range, and
causes further references to addresses within the range to
generate invalid memory references. The region is also
automatically unmapped when the process is terminated. On the
other hand, closing the file descriptor does not unmap the
region.
The address start
must be a multiple of the page size. All pages containing a
part of the indicated range are unmapped, and subsequent
references to these pages will generate SIGSEGV. It is not an
error if the indicated range does not contain any mapped
pages.
For file-backed mappings, the st_atime field for the mapped
file may be updated at any time between the mmap() and the corresponding unmapping; the
first reference to a mapped page will update the field if it
has not been already.
The st_ctime and
st_mtime field for
a file mapped with PROT_WRITE
and MAP_SHARED will be updated
after a write to the mapped region, and before a subsequent
msync(2) with the
MS_SYNC or MS_ASYNC flag, if one occurs.
RETURN VALUE
On success, mmap() returns a
pointer to the mapped area. On error, the value MAP_FAILED (that is, (void *) −1) is returned,
and errno is set appropriately.
On success, munmap() returns 0,
on failure −1, and errno
is set (probably to EINVAL).
ERRORS
- EACCES
-
A file descriptor refers to a non-regular file. Or
MAP_PRIVATE was
requested, but fd is not open for
reading. Or MAP_SHARED
was requested and PROT_WRITE is set, but fd is not open in
read/write (O_RDWR) mode. Or PROT_WRITE is set, but the file is
append-only.
- EAGAIN
-
The file has been locked, or too much memory has
been locked (see setrlimit(2)).
- EBADF
-
fd is not a
valid file descriptor (and MAP_ANONYMOUS was not set).
- EINVAL
-
We don't like start, length, or offset (e.g., they are
too large, or not aligned on a page boundary).
- EINVAL
-
(since Linux 2.6.12), length was 0.
- EINVAL
-
flags
contained neither MAP_PRIVATE or MAP_SHARED, or contained both of
these values.
- ENFILE
-
The system limit on the total number of open files
has been reached.
- ENODEV
-
The underlying filesystem of the specified file does
not support memory mapping.
- ENOMEM
-
No memory is available, or the process's maximum
number of mappings would have been exceeded.
- EPERM
-
The prot
argument asks for PROT_EXEC but the mapped area belongs
to a file on a filesystem that was mounted no-exec.
- ETXTBSY
-
MAP_DENYWRITE was set
but the object specified by fd is open for
writing.
Use of a mapped region can result in these signals:
SIGSEGV-
Attempted write into a region mapped as
read-only.
SIGBUS-
Attempted access to a portion of the buffer that
does not correspond to the file (for example, beyond
the end of the file, including the case where another
process has truncated the file).
CONFORMING TO
SVr4, 4.4BSD, POSIX.1-2001.
AVAILABILITY
On POSIX systems on which mmap(), msync(2) and munmap() are available, _POSIX_MAPPED_FILES is defined in
<unistd.h> to a value greater than 0. (See also
sysconf(3).)
NOTES
It is architecture dependent whether PROT_READ implies PROT_EXEC or not. Portable programs should
always set PROT_EXEC if they
intend to execute code in the new mapping.
BUGS
On Linux there are no guarantees like those suggested
above under MAP_NORESERVE. By
default, any process can be killed at any moment when the
system runs out of memory.
In kernels before 2.6.7, the MAP_POPULATE flag only has effect if
prot is specified as
PROT_NONE.
SUSv3 specifies that mmap()
should fail if length
is 0. However, in kernels before 2.6.12, mmap() succeeded in this case: no mapping
was created and the call returned start. Since kernel 2.6.12,
mmap() fails with the error
EINVAL for this case.
SEE ALSO
getpagesize(2), mincore(2), mlock(2), mmap2(2), mremap(2), msync(2), remap_file_pages(2),
setrlimit(2), shm_open(3)
B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and
389-391.
Copyright (C) 1996 Andries Brouwer <aeb@cwi.nl>
and Copyright (C) 2006 Michael Kerrisk <mtk-manpages@gmx.net>
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Since the Linux kernel and libraries are constantly changing, this
manual page may be incorrect or out-of-date. The author(s) assume no
responsibility for errors or omissions, or for damages resulting from
the use of the information contained herein. The author(s) may not
have taken the same level of care in the production of this manual,
which is licensed free of charge, as they might when working
professionally.
Formatted or processed versions of this manual, if unaccompanied by
the source, must acknowledge the copyright and authors of this work.
Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
Modified 2000-03-25 by Jim Van Zandt <jrv@vanzandt.mv.com>
Modified 2001-10-04 by John Levon <moz@compsoc.man.ac.uk>
Modified 2003-02-02 by Andi Kleen <ak@muc.de>
Modified 2003-05-21 by Michael Kerrisk <mtk-manpages@gmx.net>
MAP_LOCKED works from 2.5.37
Modified 2004-06-17 by Michael Kerrisk <mtk-manpages@gmx.net>
Modified 2004-09-11 by aeb
Modified 2004-12-08, from Eric Estievenart <eric.estievenart@free.fr>
Modified 2004-12-08, mtk, formatting tidy-ups
Modified 2006-12-04, mtk, various parts rewritten
|
