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 overlaps existing
mappings in the process, it might be desirable that an
implementation detect this and inform the application. However,
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 POSIX.1‐2017 specifies that the new mapping replaces any
existing mappings (implying an automatic munmap() on the address
range), following existing practice in this regard. The standard
developers also considered whether there should be a way for new
mappings to overlay existing mappings, but found no existing
practice for this.
It is not expected that all hardware implementations are able to
support all combinations of permissions at all addresses.
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 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 MCL_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 POSIX.1‐2017 defines the symbol
MAP_FAILED, which a conforming implementation does not return as
the result of a successful call.
