MMAP(2) System Calls Manual MMAP(2)
mmap - map pages of memory
caddr_t mmap(addr, len, prot, flags, fd, off)
int prot, flags, fd;
mmap() establishes a mapping between the process's address space at an
address pa for len bytes to the memory object represented by fd at off
for len bytes. The value of pa is an implementation-dependent function
of the parameter addr and values of flags, further described below. A
successful mmap() call returns pa as its result. The address ranges
covered by [pa, pa + len) and [off, off + len) must be legitimate for
the possible (not necessarily current) address space of a process and
the object in question, respectively.
The mapping established by mmap() replaces any previous mappings for
the process's pages in the range [pa, pa + len).
close(2V) does not unmap pages of the object referred to by a descrip-
tor. Use munmap(2) to remove a mapping.
The parameter prot determines whether read, write, execute, or some
combination of accesses are permitted to the pages being mapped. The
protection options are defined in <<sys/mman.h>> as:
#define PROT_READ 0x1 /* page can be read */
#define PROT_WRITE 0x2 /* page can be written */
#define PROT_EXEC 0x4 /* page can be executed */
#define PROT_NONE 0x0 /* page can not be accessed */
Not all implementations literally provide all possible combinations.
PROT_WRITE is often implemented as PROT_READ|PROT_WRITE and PROT_EXEC
as PROT_READ|PROT_EXEC. However, no implementation will permit a write
to succeed where PROT_WRITE has not been set. The behavior of
PROT_WRITE can be influenced by setting MAP_PRIVATE in the flags param-
eter, described below.
The parameter flags provides other information about the handling of
the mapped pages. The options are defined in <<sys/mman.h>> as:
#define MAP_SHARED 1 /* Share changes */
#define MAP_PRIVATE 2 /* Changes are private */
#define MAP_TYPE 0xf /* Mask for type of mapping */
#define MAP_FIXED 0x10 /* Interpret addr exactly */
MAP_SHARED and MAP_PRIVATE describe the disposition of write references
to the memory object. If MAP_SHARED is specified, write references
will change the memory object. If MAP_PRIVATE is specified, the ini-
tial write reference will create a private copy of the memory object
page and redirect the mapping to the copy. The mapping type is
retained across a fork(2V).
MAP_FIXED informs the system that the value of pa must be addr,
exactly. The use of MAP_FIXED is discouraged, as it may prevent an
implementation from making the most effective use of system resources.
When MAP_FIXED is not set, the system uses addr as a hint in an imple-
mentation-defined manner to arrive at pa. The pa so chosen will be an
area of the address space which the system deems suitable for a mapping
of len bytes to the specified object. All implementations interpret an
addr value of zero as granting the system complete freedom in selecting
pa, subject to constraints described below. A non-zero value of addr
is taken to be a suggestion of a process address near which the mapping
should be placed. When the system selects a value for pa, it will
never place a mapping at address 0, nor will it replace any extant map-
ping, nor map into areas considered part of the potential data or stack
The parameter off is constrained to be aligned and sized according to
the value returned by getpagesize (2). When MAP_FIXED is specified,
the parameter addr must also meet these constraints. The system per-
forms mapping operations over whole pages. Thus, while the parameter
len need not meet a size or alignment constraint, the system will
include in any mapping operation any partial page specified by the
range [pa, pa + len).
mmap() allows [pa, pa + len) to extend beyond the end of the object,
both at the time of the mmap() and while the mapping persists, for
example if the file was created just prior to the mmap() and has no
contents, or if the file is truncated. Any reference to addresses
beyond the end of the object, however, will result in the delivery of a
The system will always zero-fill any partial page at the end of an
object. Further, the system will never write out any modified portions
of the last page of an object which are beyond its end. References to
whole pages following the end of an object will result in a SIGBUS sig-
nal. SIGBUS may also be delivered on various filesystem conditions,
including quota exceeded errors.
If the process calls mlockall(3) with the MCL_FUTURE flag, the pages
mapped by all future calls to mmap() will be locked in memory. In this
case, if not enough memory could be locked, mmap() fails and sets errno
mmap() returns the address at which the mapping was placed (pa) on suc-
cess. On failure, it returns -1 and sets errno to indicate the error.
EACCES fd was not open for read and PROT_READ or PROT_EXEC were
fd was not open for write and PROT_WRITE was specified
for a MAP_SHARED type mapping.
EAGAIN Some or all of the mapping could not be locked in mem-
EBADF fd was not open.
EINVAL The arguments addr (if MAP_FIXED was specified) and off
were not multiples of the page size as returned by get-
The MAP_TYPE field in flags was invalid (neither
MAP_PRIVATE nor MAP_SHARED).
ENODEV fd refered to an object for which mmap() is meaningless,
such as a terminal.
ENOMEM MAP_FIXED was specified, and the range [addr, addr +
len) exceeded that allowed for the address space of a
MAP_FIXED was not specified and there was insufficient
room in the address space to effect the mapping.
ENXIO Addresses in the range [off, off + len) are invalid for
fork(2V), getpagesize(2), mprotect(2), munmap(2), mlockall(3)
21 January 1990 MMAP(2)