mmap (3p) - Linux Manuals
mmap: map pages of memory
PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.NAME
mmap - map pages of memory
SYNOPSIS
#include <sys/mman.h>
void *mmap(void *addr, size_t len, int
prot, int flags,
DESCRIPTION
The mmap() function shall establish a mapping between a process'
address space and a file, shared memory object, or
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.
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>:
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_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.
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.
The mmap() function shall fail if:
The implementation does not support the combination of accesses requested
in the prot argument.
The following sections are informative.
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:
becomes:
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.
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>
pa=mmap(addr, len, prot, flags, fildes, off);
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.
Symbolic Constant Description MAP_SHARED Changes are shared. MAP_PRIVATE Changes are private. MAP_FIXED Interpret addr exactly. RETURN VALUE
ERRORS
EXAMPLES
APPLICATION USAGE
fildes = open(...)
lseek(fildes, some_offset)
read(fildes, buf, len)
/* Use data in buf. */
fildes = open(...)
address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
/* Use data at address. */
RATIONALE
FUTURE DIRECTIONS
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 .
SEE ALSO