On modern operating systems, it is possible to mmap (pronounced "em-map") a file to a region of memory. When this is done, the file can be accessed just like an array in the program.
This is more efficent than read
or write
, as only the regions
of the file that a program actually accesses are loaded. Accesses to
not-yet-loaded parts of the mmapped region are handled in the same way as
swapped out pages.
Since mmapped pages can be stored back to their file when physical memory is low, it is possible to mmap files orders of magnitude larger than both the physical memory and swap space. The only limit is address space. The theoretical limit is 4GB on a 32-bit machine - however, the actual limit will be smaller since some areas will be reserved for other purposes. If the LFS interface is used the file size on 32-bit systems is not limited to 2GB (offsets are signed which reduces the addressable area of 4GB by half); the full 64-bit are available.
Memory mapping only works on entire pages of memory. Thus, addresses for mapping must be page-aligned, and length values will be rounded up. To determine the size of a page the machine uses one should use
size_t page_size = (size_t) sysconf (_SC_PAGESIZE);
These functions are declared in `sys/mman.h'.
The mmap
function creates a new mapping, connected to bytes
(offset) to (offset + length) in the file open on
filedes.
address gives a preferred starting address for the mapping.
NULL
expresses no preference. Any previous mapping at that
address is automatically removed. The address you give may still be
changed, unless you use the MAP_FIXED
flag.
protect contains flags that control what kind of access is
permitted. They include PROT_READ
, PROT_WRITE
, and
PROT_EXEC
, which permit reading, writing, and execution,
respectively. Inappropriate access will cause a segfault (see section Program Error Signals).
Note that most hardware designs cannot support write permission without
read permission, and many do not distinguish read and execute permission.
Thus, you may receive wider permissions than you ask for, and mappings of
write-only files may be denied even if you do not use PROT_READ
.
flags contains flags that control the nature of the map.
One of MAP_SHARED
or MAP_PRIVATE
must be specified.
They include:
MAP_PRIVATE
PROT_WRITE
.
MAP_SHARED
msync
, described below, if it is important that other processes
using conventional I/O get a consistent view of the file.
MAP_FIXED
MAP_ANONYMOUS
MAP_ANON
malloc
for large blocks. This is not an issue with the GNU C library,
as the included malloc
automatically uses mmap
where appropriate.
mmap
returns the address of the new mapping, or @math{-1} for an
error.
Possible errors include:
EINVAL
EACCES
ENOMEM
ENODEV
ENOEXEC
mmap64
function is equivalent to the mmap
function but
the offset parameter is of type off64_t
. On 32-bit systems
this allows the file associated with the filedes descriptor to be
larger than 2GB. filedes must be a descriptor returned from a
call to open64
or fopen64
and freopen64
where the
descriptor is retrieved with fileno
.
When the sources are translated with _FILE_OFFSET_BITS == 64
this
function is actually available under the name mmap
. I.e., the
new, extended API using 64 bit file sizes and offsets transparently
replaces the old API.
munmap
removes any memory maps from (addr) to (addr +
length). length should be the length of the mapping.
It is safe to unmap multiple mappings in one command, or include unmapped space in the range. It is also possible to unmap only part of an existing mapping. However, only entire pages can be removed. If length is not an even number of pages, it will be rounded up.
It returns @math{0} for success and @math{-1} for an error.
One error is possible:
EINVAL
When using shared mappings, the kernel can write the file at any time before the mapping is removed. To be certain data has actually been written to the file and will be accessible to non-memory-mapped I/O, it is necessary to use this function.
It operates on the region address to (address + length). It may be used on part of a mapping or multiple mappings, however the region given should not contain any unmapped space.
flags can contain some options:
MS_SYNC
msync
only makes sure that accesses to a file with
conventional I/O reflect the recent changes.
MS_ASYNC
msync
to begin the synchronization, but not to wait for
it to complete.
msync
returns @math{0} for success and @math{-1} for
error. Errors include:
EINVAL
EFAULT
This function can be used to change the size of an existing memory
area. address and length must cover a region entirely mapped
in the same mmap
statement. A new mapping with the same
characteristics will be returned with the length new_length.
One option is possible, MREMAP_MAYMOVE
. If it is given in
flags, the system may remove the existing mapping and create a new
one of the desired length in another location.
The address of the resulting mapping is returned, or @math{-1}. Possible error codes include:
EFAULT
EINVAL
EAGAIN
ENOMEM
MREMAP_MAYMOVE
is not given and the extension would collide with
another mapped region.
This function is only available on a few systems. Except for performing optional optimizations one should not rely on this function.
Not all file descriptors may be mapped. Sockets, pipes, and most devices
only allow sequential access and do not fit into the mapping abstraction.
In addition, some regular files may not be mmapable, and older kernels may
not support mapping at all. Thus, programs using mmap
should
have a fallback method to use should it fail. See section `Mmap' in GNU Coding Standards.
Go to the first, previous, next, last section, table of contents.