mmap - map memory pages

Syntax

include <sys/mman.h>

void *mmap(void *addr, size_t len, int prot, int flags, int fildes, off_t off); 

Description

mmap() produces a mapping between the address area of a process ( [pa, pa + len)) and a file section ([off, off + len)).

The call has the following format:

pa = mmap(addr, len, prot, flags, fildes, off);

A mapping is produced between the address space of the process at the address pa for len bytes on the one hand and the file described by the file descriptor fildes with the offset off for len bytes on the other.
The value of pa is an implementation-dependent function of addr and the value flags. A successful mmap() call returns pa as the result. The address areas defined by [pa, pa + len) and [off, off + len) must be permissible for the possible (not necessarily the current) address area of the process or the file. mmap() cannot enlarge a file.

The mapping, which is produced by mmap() with MAP_FIXED, replaces all previous mappings for the pages of the process in the area [pa, pa + len).

If the size of the mapped file is changed after the mmap() call, the effect on references to mapping sections which correspond to a newly added or deleted part of the file is undefined.

mmap() is supported for normal files only.

The prot parameter determines whether read, write or execute accesses or combinations of these are to be allowed for the mapped pages. The access permissions are defined in sys/mman.h as follows:

PROT_READ	Page can be read.
PROT_WRITE	Page can be written.
PROT_EXEC	Page can be executed.
PROT_NONE	Page cannot be accessed.

PROT_WRITE is implemented as PROT_WRITE|PROT_EXEC and PROT_EXEC as PROT_READ|PROT_EXEC.

Three states are possible:

• the page cannot be accessed

• access to the page is read-only

• the page can be accessed for both reading and writing

The behavior of PROT_WRITE can be influenced by the MAP_PRIVATE in the flags parameter, as described in more detail below.

The flags parameter contains further information on the handling of the mapped pages. The options are defined in sys/mman.h as follows:

MAP_SHARED	Changes are shareable
MAP_PRIVATE	Changes are private
MAP_FIXED	addr must be interpreted exactly

MAP_SHARED and MAP_PRIVATE control the visibility of write accesses to the memory pages. Either MAP_SHARED or MAP_PRIVATE must be specified. The mapping type is retained after a fork().

If MAP_SHARED is specified, write accesses to the memory pages modify the file, and the changes are visible in all mappings of the relevant file section produced with MAP_SHARED.

If MAP_PRIVATE is specified, write accesses to the memory pages do not modify the file, and the changes are not visible to any other process which maps the relevant file section. The first write access generates a privately kept copy of the memory pages and redirects the mapping to the copy. Note that the privately kept copy is not generated until the first write access; until then, other users who have mapped the file section with MAP_SHARED can modify the file section.

MAP_FIXED defines that the value of pa must match addr exactly. Use of MAP_FIXED is not recommended, as this parameter can prevent effective use of the system resources.

If MAP_FIXED is not set, depending on the implementation an address pa is returned through selection of an area from the address space of the process which the system considers suitable for mapping len bytes. An addr value of zero means that pa can be freely selected in accordance with the conditions described below. If addr has a value other than zero, this is interpreted as a suggestion to select the mapping close to this address. On no account is the value 0 selected for pa, is an existing mapping overwritten or does mapping take place to dynamically assigned memory areas.

The off parameter is subject to restrictions in its size and alignment, which are based on the return value of sysconf() with regard to the _SC_PAGESIZE and _SC_PAGE_SIZE parameters. If MAP_FIXED is specified, the addr parameter must also comply with these restrictions. The system performs mapping operations over entire pages. Because the len parameter is not tied to specific sizes or alignments, the system includes in the mapping operation all page remainders which arise during mapping of the area [pa, pa + len). The system fills such part-pages with zeros at the end of a [pa, pa + len) memory area. Changes to this area are not written back. If the mapping extends over whole pages which are located after the last byte of the file, references to these pages generate a SIGSEGV signal.
SIGSEGV signals can also be sent in the case of various error conditions of the file system, including exceeding of the quota.

mmap() generates an additional reference to the file that is described by fildes. This reference is not deleted when a close() is issued for fildes, but only when no more mappings to the file exist.

Return val.

pa

-1

Address where the mapping was placed.

in the event of an error. errno is set to indicate the error.

Errors

mmap() will fail if:

 

 

EACCES

fildes is not opened for reading, regardless of the specified prot argument, or fildes is not opened for writing and PROT_WRITE was requested in an mapping of type MAP_SHARED.

 

EAGAIN

EBADF

ENXIO

EINVAL

The mapping cannot be locked in the memory.

fildes is not a valid open file descriptor.

Addresses in the [off, off + len) area are invalid for fildes.

The off argument (or addr if MAP_FIXED was specified) does not contain a multiple of the page length returned by sysconf(), or off or addr has an invalid value.

The value in flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is set).

The len argument has a value less than or equal to 0.

 

EMFILE

ENOMEM

The number of mappings exceeds the maximum permissible value.

MAP_FIXED was specified and the [addr, addr + len) area exceeds the address area allowed for a process, or MAP_FIXED was not specified but there is not enough storage space available in the address area for the mapping.

 

ENODEV

fildes refers to a file whose type is not supported by mmap(), e.g. a special file.

 

EOVERFLOW

The value of off plus len exceeds the offset maximum specified in the internal description of the open file assigned to fildes.

Notes

The use of mmap() reduces the space available for other functions which also occupy
storage space.

The specification MAP_FIXED is not recommended, as this parameter can prevent effective
use of the system resources.

The application must make sure that the file accesses are synchronized if mmap() is used
together with other file access methods like read(), write(), standard input/output and
shmat().

mmap() allows access to resources via address area manipulations in place of the
read/write interface. If a file is mapped, a processes need only access the address to
which the file object is mapped. Observe the following (incomplete) code:

fildes = open(...)
lseek(fildes, some_offset)
read(fildes, buf, len)
   /* Use data in buf */

Using mmap(), the code can be rewritten as follows:

fildes = open(...)
address =mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
   /* Use address data */

See also

exec(), fcntl(), fork(), lockf(), munmap(), msync(), mprotect(), shmat(), sysconf(), sys/mman.h.