mmap(2) mmap(2)
NAME
mmap, mmap64 - map pages of memory
SYNOPSIS
#include <sys/types.h>
#include <sys/mman.h>
void *mmap(void *addr, sizet len, int prot, int flags, int fd, offt
off);
void *mmap64(void *addr, sizet len, int prot, int flags, int fd, off64t
off);
DESCRIPTION
The functions mmap and mmap64 establish a mapping between a process's
address space and a virtual memory object. The format of the call is as
follows:
pa = mmap(addr, len, prot, flags, fd, off);
mmap establishes a mapping between the process's address space at an
address pa for len bytes to the memory object represented by the file
descriptor fd at offset 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 only difference between mmap and mmap64 is that in mmap64 the off
parameter is 64 bits long, so that the file offset can be greater than 2
gigabytes. This is useful for certain filesystem types that support such
file offsets.
The mapping established by mmap replaces any previous mappings for the
process's pages in the range [pa, pa + len).
The parameter prot determines whether read (load), write (store),
execute, or some combination of accesses are permitted to the pages being
mapped. The protection options are defined in <sys/mman.h> as:
PROTREAD Page can be read.
PROTWRITE Page can be written.
PROTEXEC Page can be executed.
PROTNONE Page can not be accessed.
Not all implementations literally provide all possible combinations.
PROTWRITE is often implemented as PROTREAD|PROTWRITE and PROTEXEC as
PROTREAD|PROTEXEC. This is true for all SGI implementations. In
particular, MIPS processors do not support a separate execute permission.
Any page that can be read can be executed from, even if PROTEXEC is not
specified. Instead, the operating system uses PROTEXEC as a flag to
indicate it may need to perform certain platform dependent functions
Page 1
mmap(2) mmap(2)
(such as cache flushing) that may be needed to properly execute
instructions from the associated page. See mprotect(2) for further
details. However, no implementation will permit a store to succeed where
PROTWRITE has not been set. The behavior of PROTWRITE can be
influenced by setting MAPPRIVATE in the flags parameter, described
below.
The parameter flags provides other information about the handling of the
mapped pages. The options are defined in <sys/mman.h> as:
MAPSHARED Share changes
MAPPRIVATE Changes are private
MAPFIXED Interpret addr exactly
MAPAUTOGROW Implicitly grow object
MAPLOCAL Do not share with share group
MAPAUTORESRV Reserve logical swap on demand
MAPSHARED and MAPPRIVATE describe the disposition of store references
to the memory object. If MAPSHARED is specified, store references will
change the memory object. If MAPPRIVATE is specified, the initial store
reference will create a private copy of the memory object page and
redirect the mapping to the copy. Either MAPSHARED or MAPPRIVATE must
be specified, but not both. The mapping type is retained across a
fork(2).
When MAPSHARED is specified, and initially in all pages when MAPPRIVATE
is specified, the contents of the mapped segment change to reflect
changes in the underlying memory object. Changes can be caused by other
processes that map the same object with MAPSHARED, or by processes using
write(2) or ftruncate(2). If the file is shortened, an attempt to access
a page of memory that is mapped to a part of the file that no longer
exists will cause a Bus Error (SIGBUS) signal.
When MAPPRIVATE is used, a private copy of a page is created only when
the process stores into the page. This prevents changes from being seen
by other processes that map the same object, and prevents further changes
made by other processes from being visible. However, changes that occur
before the page is stored into are visible.
To protect the contents of a mapped file from changes or truncation you
can either use chmod(2) and lockf(3) to enforce a mandatory file lock, or
you can specify MAPPRIVATE and store into every page of the segment in
order to create a complete private copy of the data.
MAPFIXED informs the system that the value of pa must be addr, exactly.
When MAPFIXED is not set, the system uses addr in an implementation-
specific 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.
Page 2
mmap(2) mmap(2)
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 mapping, and it will attempt to map away from areas
considered part of the potential data or stack segments.
The MAPFIXED directive should be used with caution. When MAPFIXED is
set, any mappings (including text, heap, data, and stack) in the range
[addr, addr + len) will be replaced with the new mapping.
To ensure best system hardware cache behaviour, objects should be mapped
such that the low sixteen bits of the file offset of the object match the
low bits of the mapped address.
The address range from 0x30000000 to 0x40000000 is reserved for MAPFIXED
mappings. Note, though, that this space may not be useful for programs
which require a very large heap, since, by default, program heaps start
near 0x10000000 and grow toward higher addresses.
If MAPAUTOGROW is specified with MAPSHARED, the mapped object will be
implicitly grown when referenced by a store operation to a page which
maps beyond the current end of the object; the object will be grown and
zero-filled to fulfill the mapping up to the next page boundary or to the
end of the mapping, whichever is less. If used with MAPPRIVATE,
MAPAUTOGROW allocates private zero-filled pages for references beyond
the end of the object, but does not grow the object.
MAPAUTOGROW requires that the object is mapped with PROTWRITE
permission. Load references to mapped pages following the end of a
object will result in the delivery of a SIGSEGV signal, as will various
filesystem conditions on stores. Whenever a SIGSEGV signal is delivered,
the second argument to the signal handler contains a value that indicates
the reason for the delivery of the signal; these values are defined in
/usr/include/sys/errno.h.
If MAPLOCAL is used and the process does an sproc(2) each process will
receive a private copy of the object's mapping. All subsequent load
reference of objects mapped MAPPRIVATE will cause private copies of the
object to be created. In addition, the share group processes will be
able to independently unmap the object from their address spaces.
The system reserves len bytes of logical swap space when MAPPRIVATE
mappings of regular files are created, as well as for all mappings of
/dev/zero. (See swap(1m) for a discussion of logical swap space.) If
insufficient logical swap space is available, mmap fails with EAGAIN.
The MAPAUTORESRV flag causes logical swap space to be automatically
reserved as each page is first referenced with a store operation instead
of when the mapping is created. When this flag is used, no logical swap
space is reserved when the mapping is created. Therefore, the system
cannot guarantee that space will be available when needed. If all the
Page 3
mmap(2) mmap(2)
logical swap space has been taken by other processes when a page in a
MAPAUTORESRV mapping is first stored to, then the process will be sent
SIGBUS.
The parameter off is constrained to be aligned and sized according to the
value returned by getpagesize(2) or sysconf(_SC_PAGESIZE). When
MAPFIXED is specified, the parameter addr as well as off must be aligned
according to the value returned by sysconf(_SC_MMAP_FIXED_ALIGNMENT).
The system performs 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).
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 the delivery of
a SIGBUS signal. SIGBUS signals may also be delivered on various file
system conditions, including quota exceeded errors, and for physical
device errors (such as unreadable disk blocks). The signal handler may
examine the sicode and sierrno fields of the siginfo structure for
information about the nature of the error.
RETURN VALUE
On success, mmap returns the address at which the mapping was placed
(pa). On failure it returns MAPFAILED and sets errno to indicate an
error.
ERRORS
Under the following conditions, mmap fails and sets errno to:
EAGAIN The mapping could not be locked in memory.
EAGAIN The amount of logical swap space required is temporarily
unavailable.
EBADF fd is not open.
EACCES fd is not open for read, regardless of the protection specified,
or fd is not open for write and PROTWRITE was specified for a
MAPSHARED type mapping.
EACCES prot has extraneous bits set.
ENXIO Addresses in the range [off, off + len) are invalid for fd.
EINVAL The arguments addr (if MAPFIXED was specified) or off are not
multiples of the value returned by
sysconf(_SC_MMAP_FIXED_ALIGNMENT).
Page 4
mmap(2) mmap(2)
EINVAL The arguments
EINVAL The field in flags is invalid (neither MAPPRIVATE or MAPSHARED).
ENXIO The argument len has a value less than or equal to 0.
EINVAL The argument addr specifies an unmappable address.
ENODEV fd refers to an object for which mmap is meaningless, such as a
terminal.
ENOSYS fd refers to an object for which mmap is not permitted.
ENOMEM MAPFIXED was specified and the range [addr, addr + len) is
invalid or exceeds that allowed for the address space of a
process, or MAPFIXED was not specified and there is insufficient
room in the address space to effect the mapping.
ENOMEM The calling process has the automatic memory locking of future
mappings enabled [see mlockall(3C)] and there is insufficient
physical memory available for the mapping.
NOTES
mmap allows access to resources via address space manipulations instead
of the read/write interface. Once a file is mapped, all a process has to
do to access it is use the data at the address to which the object was
mapped. Consider the following pseudo-code:
fd = open(...)
lseek(fd, offset)
read(fd, buf, len)
/* use data in buf */
Here is a rewrite using mmap:
fd = open(...)
address = mmap(NULL, len, (PROTREAD | PROTWRITE),
MAPPRIVATE, fd, offset)
/* use data at address */
Previous IRIX releases have only required MAPFIXED address alignment to
the system page size returned with getpagesize(2). This is no longer
true for the MIPS R4000PC, R4600 and R5000 processors. Requests now must
be aligned to the size returned by sysconf(_SC_MMAP_FIXED_ALIGNMENT).
SEE ALSO
fcntl(2), fork(2), lockf(3C), madvise(2), mprotect(2), msync(2),
munmap(2), plock(2), sproc(2), sysconf(2).
Page 5