mmap, munmap — map or unmap files or devices into memory
#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); |
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_EXECPages may be executed.
PROT_READPages may be read.
PROT_WRITEPages may be written.
PROT_NONEPages 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_SHAREDShare 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_PRIVATECreate 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_32BITPut 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_ANONSynonym for MAP_ANONYMOUS. Deprecated.
MAP_ANONYMOUSThe 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_DENYWRITEThis 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_EXECUTABLEThis flag is ignored.
MAP_FILECompatibility flag. Ignored.
MAP_FIXEDDon'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_GROWSDOWNUsed 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_NORESERVEDo 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.
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).
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.
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.
The file has been locked, or too much memory has been locked (see setrlimit(2)).
fd is not a
valid file descriptor (and MAP_ANONYMOUS was not set).
We don't like start, length, or offset (e.g., they are
too large, or not aligned on a page boundary).
(since Linux 2.6.12), length was 0.
flags
contained neither MAP_PRIVATE or MAP_SHARED, or contained both of
these values.
The system limit on the total number of open files has been reached.
The underlying filesystem of the specified file does not support memory mapping.
No memory is available, or the process's maximum number of mappings would have been exceeded.
The prot
argument asks for PROT_EXEC but the mapped area belongs
to a file on a filesystem that was mounted no-exec.
MAP_DENYWRITE was set
but the object specified by fd is open for
writing.
Use of a mapped region can result in these signals:
SIGSEGVAttempted write into a region mapped as read-only.
SIGBUSAttempted 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).
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).)
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.
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.
|
|