Provided by: manpages-posix-dev_2.16-1_all 
NAME
mmap - map pages of memory
SYNOPSIS
#include <sys/mman.h>
void *mmap(void *addr, size_t len, int prot, int flags,
int fildes, off_t off);
DESCRIPTION
The mmap() function shall establish a mapping between a process' address space and a file, shared memory
object, or typed memory object. The format of the call is as follows:
pa=mmap(addr, len, prot, flags, fildes, off);
The mmap() function shall establish a mapping between the address space of the process at an address pa
for len bytes to the memory object represented by the file descriptor fildes at offset off for len bytes.
The value of pa is an implementation-defined function of the parameter addr and the values of flags,
further described below. A successful mmap() call shall return pa as its result. The address range
starting at pa and continuing for len bytes shall be legitimate for the possible (not necessarily
current) address space of the process. The range of bytes starting at off and continuing for len bytes
shall be legitimate for the possible (not necessarily current) offsets in the file, shared memory object,
or typed memory object represented by fildes.
If fildes represents a typed memory object opened with either the POSIX_TYPED_MEM_ALLOCATE flag or the
POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, the memory object to be mapped shall be that portion of the typed
memory object allocated by the implementation as specified below. In this case, if off is non-zero, the
behavior of mmap() is undefined. If fildes refers to a valid typed memory object that is not accessible
from the calling process, mmap() shall fail.
The mapping established by mmap() shall replace any previous mappings for those whole pages containing
any part of the address space of the process starting at pa and continuing for len bytes.
If the size of the mapped file changes after the call to mmap() as a result of some other operation on
the mapped file, the effect of references to portions of the mapped region that correspond to added or
removed portions of the file is unspecified.
The mmap() function shall be supported for regular files, shared memory objects, and typed memory
objects. Support for any other type of file is unspecified.
The parameter prot determines whether read, write, execute, or some combination of accesses are permitted
to the data being mapped. The prot shall be either PROT_NONE or the bitwise-inclusive OR of one or more
of the other flags in the following table, defined in the <sys/mman.h> header.
Symbolic Constant Description
PROT_READ Data can be read.
PROT_WRITE Data can be written.
PROT_EXEC Data can be executed.
PROT_NONE Data cannot be accessed.
If an implementation cannot support the combination of access types specified by prot, the call to mmap()
shall fail.
An implementation may permit accesses other than those specified by prot; however, if the Memory
Protection option is supported, the implementation shall not permit a write to succeed where PROT_WRITE
has not been set or shall not permit any access where PROT_NONE alone has been set. The implementation
shall support at least the following values of prot: PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-
inclusive OR of PROT_READ and PROT_WRITE. If the Memory Protection option is not supported, the result
of any access that conflicts with the specified protection is undefined. The file descriptor fildes shall
have been opened with read permission, regardless of the protection options specified. If PROT_WRITE is
specified, the application shall ensure that it has opened the file descriptor fildes with write
permission unless MAP_PRIVATE is specified in the flags parameter as described below.
The parameter flags provides other information about the handling of the mapped data. The value of flags
is the bitwise-inclusive OR of these options, defined in <sys/mman.h>:
Symbolic Constant Description
MAP_SHARED Changes are shared.
MAP_PRIVATE Changes are private.
MAP_FIXED Interpret addr exactly.
Implementations that do not support the Memory Mapped Files option are not required to support
MAP_PRIVATE.
It is implementation-defined whether MAP_FIXED shall be supported. MAP_FIXED shall be supported on XSI-
conformant systems.
MAP_SHARED and MAP_PRIVATE describe the disposition of write references to the memory object. If
MAP_SHARED is specified, write references shall change the underlying object. If MAP_PRIVATE is
specified, modifications to the mapped data by the calling process shall be visible only to the calling
process and shall not change the underlying object. It is unspecified whether modifications to the
underlying object done after the MAP_PRIVATE mapping is established are visible through the MAP_PRIVATE
mapping. Either MAP_SHARED or MAP_PRIVATE can be specified, but not both. The mapping type is retained
across fork().
When fildes represents a typed memory object opened with either the POSIX_TYPED_MEM_ALLOCATE flag or the
POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, mmap() shall, if there are enough resources available, map len
bytes allocated from the corresponding typed memory object which were not previously allocated to any
process in any processor that may access that typed memory object. If there are not enough resources
available, the function shall fail. If fildes represents a typed memory object opened with the
POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, these allocated bytes shall be contiguous within the typed memory
object. If fildes represents a typed memory object opened with the POSIX_TYPED_MEM_ALLOCATE flag, these
allocated bytes may be composed of non-contiguous fragments within the typed memory object. If fildes
represents a typed memory object opened with neither the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the
POSIX_TYPED_MEM_ALLOCATE flag, len bytes starting at offset off within the typed memory object are
mapped, exactly as when mapping a file or shared memory object. In this case, if two processes map an
area of typed memory using the same off and len values and using file descriptors that refer to the same
memory pool (either from the same port or from a different port), both processes shall map the same
region of storage.
When MAP_FIXED is set in the flags argument, the implementation is informed that the value of pa shall be
addr, exactly. If MAP_FIXED is set, mmap() may return MAP_FAILED and set errno to [EINVAL]. If a
MAP_FIXED request is successful, the mapping established by mmap() replaces any previous mappings for the
process' pages in the range [pa,pa+len).
When MAP_FIXED is not set, the implementation uses addr in an implementation-defined manner to arrive at
pa. The pa so chosen shall be an area of the address space that the implementation deems suitable for a
mapping of len bytes to the file. All implementations interpret an addr value of 0 as granting the
implementation 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 implementation selects a value for pa, it never places a mapping at address 0, nor does it replace
any extant mapping.
The off argument is constrained to be aligned and sized according to the value returned by sysconf() when
passed _SC_PAGESIZE or _SC_PAGE_SIZE. When MAP_FIXED is specified, the application shall ensure that the
argument addr also meets these constraints. The implementation performs mapping operations over whole
pages. Thus, while the argument len need not meet a size or alignment constraint, the implementation
shall include, in any mapping operation, any partial page specified by the range [pa,pa+len).
The system shall always zero-fill any partial page at the end of an object. Further, the system shall
never write out any modified portions of the last page of an object which are beyond its end.
References within the address range starting at pa and continuing for len bytes to whole pages following
the end of an object shall result in delivery of a SIGBUS signal.
An implementation may generate SIGBUS signals when a reference would cause an error in the mapped object,
such as out-of-space condition.
The mmap() function shall add an extra reference to the file associated with the file descriptor fildes
which is not removed by a subsequent close() on that file descriptor. This reference shall be removed
when there are no more mappings to the file.
The st_atime field of the mapped file may be marked for update at any time between the mmap() call and
the corresponding munmap() call. The initial read or write reference to a mapped region shall cause the
file's st_atime field to be marked for update if it has not already been marked for update.
The st_ctime and st_mtime fields of a file that is mapped with MAP_SHARED and PROT_WRITE shall be marked
for update at some point in the interval between a write reference to the mapped region and the next call
to msync() with MS_ASYNC or MS_SYNC for that portion of the file by any process. If there is no such call
and if the underlying file is modified as a result of a write reference, then these fields shall be
marked for update at some time after the write reference.
There may be implementation-defined limits on the number of memory regions that can be mapped (per
process or per system).
If such a limit is imposed, whether the number of memory regions that can be mapped by a process is
decreased by the use of shmat() is implementation-defined.
If mmap() fails for reasons other than [EBADF], [EINVAL], or [ENOTSUP], some of the mappings in the
address range starting at addr and continuing for len bytes may have been unmapped.
RETURN VALUE
Upon successful completion, the mmap() function shall return the address at which the mapping was placed
( pa); otherwise, it shall return a value of MAP_FAILED and set errno to indicate the error. The symbol
MAP_FAILED is defined in the <sys/mman.h> header. No successful return from mmap() shall return the value
MAP_FAILED.
ERRORS
The mmap() function shall fail if:
EACCES The fildes argument is not open for read, regardless of the protection specified, or fildes is not
open for write and PROT_WRITE was specified for a MAP_SHARED type mapping.
EAGAIN The mapping could not be locked in memory, if required by mlockall(), due to a lack of resources.
EBADF The fildes argument is not a valid open file descriptor.
EINVAL The addr argument (if MAP_FIXED was specified) or off is not a multiple of the page size as
returned by sysconf(), or is considered invalid by the implementation.
EINVAL The value of flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is set).
EMFILE The number of mapped regions would exceed an implementation-defined limit (per process or per
system).
ENODEV The fildes argument refers to a file whose type is not supported by mmap().
ENOMEM MAP_FIXED was specified, and the range [addr,addr+len) exceeds that allowed for the address space
of a process; or, if MAP_FIXED was not specified and there is insufficient room in the address
space to effect the mapping.
ENOMEM The mapping could not be locked in memory, if required by mlockall(), because it would require
more space than the system is able to supply.
ENOMEM Not enough unallocated memory resources remain in the typed memory object designated by fildes to
allocate len bytes.
ENOTSUP
MAP_FIXED or MAP_PRIVATE was specified in the flags argument and the implementation does not
support this functionality.
The implementation does not support the combination of accesses requested in the prot argument.
ENXIO Addresses in the range [off,off+len) are invalid for the object specified by fildes.
ENXIO MAP_FIXED was specified in flags and the combination of addr, len, and off is invalid for the
object specified by fildes.
ENXIO The fildes argument refers to a typed memory object that is not accessible from the calling
process.
EOVERFLOW
The file is a regular file and the value of off plus len exceeds the offset maximum established in
the open file description associated with fildes.
The following sections are informative.
EXAMPLES
None.
APPLICATION USAGE
Use of mmap() may reduce the amount of memory available to other memory allocation functions.
Use of MAP_FIXED may result in unspecified behavior in further use of malloc() and shmat(). The use of
MAP_FIXED is discouraged, as it may prevent an implementation from making the most effective use of
resources.
The application must ensure correct synchronization when using mmap() in conjunction with any other file
access method, such as read() and write(), standard input/output, and shmat().
The mmap() function allows access to resources via address space manipulations, instead of read()/
write(). Once a file is mapped, all a process has to do to access it is use the data at the address to
which the file was mapped. So, using pseudo-code to illustrate the way in which an existing program might
be changed to use mmap(), the following:
fildes = open(...)
lseek(fildes, some_offset)
read(fildes, buf, len)
/* Use data in buf. */
becomes:
fildes = open(...)
address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
/* Use data at address. */
RATIONALE
After considering several other alternatives, it was decided to adopt the mmap() definition found in SVR4
for mapping memory objects into process address spaces. The SVR4 definition is minimal, in that it
describes only what has been built, and what appears to be necessary for a general and portable mapping
facility.
Note that while mmap() was first designed for mapping files, it is actually a general-purpose mapping
facility. It can be used to map any appropriate object, such as memory, files, devices, and so on, into
the address space of a process.
When a mapping is established, it is possible that the implementation may need to map more than is
requested into the address space of the process because of hardware requirements. An application,
however, cannot count on this behavior. Implementations that do not use a paged architecture may simply
allocate a common memory region and return the address of it; such implementations probably do not
allocate any more than is necessary. References past the end of the requested area are unspecified.
If an application requests a mapping that would overlay existing mappings in the process, it might be
desirable that an implementation detect this and inform the application. However, the default, portable
(not MAP_FIXED) operation does not overlay existing mappings. On the other hand, if the program specifies
a fixed address mapping (which requires some implementation knowledge to determine a suitable address, if
the function is supported at all), then the program is presumed to be successfully managing its own
address space and should be trusted when it asks to map over existing data structures. Furthermore, it is
also desirable to make as few system calls as possible, and it might be considered onerous to require an
munmap() before an mmap() to the same address range. This volume of IEEE Std 1003.1-2001 specifies that
the new mappings replace any existing mappings, following existing practice in this regard.
It is not expected, when the Memory Protection option is supported, that all hardware implementations are
able to support all combinations of permissions at all addresses. When this option is supported,
implementations are required to disallow write access to mappings without write permission and to
disallow access to mappings without any access permission. Other than these restrictions, implementations
may allow access types other than those requested by the application. For example, if the application
requests only PROT_WRITE, the implementation may also allow read access. A call to mmap() fails if the
implementation cannot support allowing all the access requested by the application. For example, some
implementations cannot support a request for both write access and execute access simultaneously. All
implementations supporting the Memory Protection option must support requests for no access, read access,
write access, and both read and write access. Strictly conforming code must only rely on the required
checks. These restrictions allow for portability across a wide range of hardware.
The MAP_FIXED address treatment is likely to fail for non-page-aligned values and for certain
architecture-dependent address ranges. Conforming implementations cannot count on being able to choose
address values for MAP_FIXED without utilizing non-portable, implementation-defined knowledge.
Nonetheless, MAP_FIXED is provided as a standard interface conforming to existing practice for utilizing
such knowledge when it is available.
Similarly, in order to allow implementations that do not support virtual addresses, support for directly
specifying any mapping addresses via MAP_FIXED is not required and thus a conforming application may not
count on it.
The MAP_PRIVATE function can be implemented efficiently when memory protection hardware is available.
When such hardware is not available, implementations can implement such "mappings" by simply making a
real copy of the relevant data into process private memory, though this tends to behave similarly to
read().
The function has been defined to allow for many different models of using shared memory. However, all
uses are not equally portable across all machine architectures. In particular, the mmap() function allows
the system as well as the application to specify the address at which to map a specific region of a
memory object. The most portable way to use the function is always to let the system choose the address,
specifying NULL as the value for the argument addr and not to specify MAP_FIXED.
If it is intended that a particular region of a memory object be mapped at the same address in a group of
processes (on machines where this is even possible), then MAP_FIXED can be used to pass in the desired
mapping address. The system can still be used to choose the desired address if the first such mapping is
made without specifying MAP_FIXED, and then the resulting mapping address can be passed to subsequent
processes for them to pass in via MAP_FIXED. The availability of a specific address range cannot be
guaranteed, in general.
The mmap() function can be used to map a region of memory that is larger than the current size of the
object. Memory access within the mapping but beyond the current end of the underlying objects may result
in SIGBUS signals being sent to the process. The reason for this is that the size of the object can be
manipulated by other processes and can change at any moment. The implementation should tell the
application that a memory reference is outside the object where this can be detected; otherwise, written
data may be lost and read data may not reflect actual data in the object.
Note that references beyond the end of the object do not extend the object as the new end cannot be
determined precisely by most virtual memory hardware. Instead, the size can be directly manipulated by
ftruncate().
Process memory locking does apply to shared memory regions, and the MEMLOCK_FUTURE argument to mlockall()
can be relied upon to cause new shared memory regions to be automatically locked.
Existing implementations of mmap() return the value -1 when unsuccessful. Since the casting of this value
to type void * cannot be guaranteed by the ISO C standard to be distinct from a successful value, this
volume of IEEE Std 1003.1-2001 defines the symbol MAP_FAILED, which a conforming implementation does not
return as the result of a successful call.
FUTURE DIRECTIONS
None.
SEE ALSO
exec() , fcntl() , fork() , lockf() , msync() , munmap() , mprotect() , posix_typed_mem_open() , shmat()
, sysconf() , the Base Definitions volume of IEEE Std 1003.1-2001, <sys/mman.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition,
Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers,
Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The
original Standard can be obtained online at http://www.opengroup.org/unix/online.html .
IEEE/The Open Group 2003 MMAP(P)