mmap(2) mmap(2)
NAME
mmap, mmap64 - map pages of memory
SYNOPSIS
#include <sys/mman.h>
void *mmap(void *addr, sizet len, int prot, int flags,
int fildes, offt off);
void *mmap64(void *addr, sizet len, int prot, int flags,
int fd, off64t offset);
DESCRIPTION
The mmap() function establishes a mapping between a process' address
space and a file. The format of the call is as follows:
pa=mmap(addr, len, prot, flags, fildes, off);
The mmap() function establishes a mapping between the process' address
space at an address pa for len bytes and the file associated with the
file descriptor fildes at offset off for len bytes. The value of pa is
an unspecified function of the argument 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 file, respectively.
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 is supported for regular files. Support for any
other type of file is unspecified.
The prot argument 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>:
PROTREAD Page can be read.
PROTWRITE Page can be written.
PROTEXEC Page can be executed.
PROTNONE Page can not be accessed.
Implementations need not enforce all combinations of access permis-
sions. However, writes shall only be permitted when PROTWRITE has
been set.
Page 1 Reliant UNIX 5.44 Printed 11/98
mmap(2) mmap(2)
The flags argument provides other information about the handling of
the mapped pages. The options are defined in <sys/mman.h>:
MAPSHARED Share changes.
MAPPRIVATE Changes are private.
MAPFIXED Interpret addr exactly.
The MAPPRIVATE and MAPSHARED flags control the visibility of write
references to the memory region. Exactly one of these flags must be
specified. The mapping type is retained across a fork().
If MAPSHARED is set in flags, write references to the memory region
by the calling process may change the file and are visible in all
MAPSHARED mappings of the same portion of the file by any process.
If MAPPRIVATE is set in flags, write references to the memory region
by the calling process do not change the file and are not visible to
any process in other mappings of the same portion of the file.
It is unspecified whether write references by processes that have
mapped the memory region using MAPSHARED are visible to processes
that have mapped the same portion of the file using MAPPRIVATE.
It is also unspecified whether write references to a memory region
mapped with MAPSHARED are visible to processes reading the file and
whether writes to a file are visible to processes that have mapped the
modified portion of that file, except for the effect of msync().
When MAPFIXED is set in the flags argument, the implementation is
informed that the value of pa must be addr, exactly. If MAPFIXED is
set, mmap() may return (void *)-1 and set errno to EINVAL. If a
MAPFIXED request is successful, the mapping established by mmap()
replaces any previous mappings for the process' pages in the range
[pa, pa + len).
When MAPFIXED is not set, the implementation uses addr in an unspeci-
fied manner to arrive at pa. The pa so chosen will be an area of the
address space which 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, nor map into dynamic memory allocation areas.
Page 2 Reliant UNIX 5.44 Printed 11/98
mmap(2) mmap(2)
The off argument is constrained to be aligned and sized according to
the value returned by sysconf() when passed SCPAGESIZE or
SCPAGESIZE. When MAPFIXED is specified, the argument addr must
also meet 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 will include,
in any mapping operation, any partial page specified by the range
[pa, pa + len)
The implementation always zero-fills any partial page at the end of
the file. Further, the implementation never writes out any modified
portions of the last page of a file that are beyond the end of the
file. If the mapping established by mmap() extends into pages beyond
the page containing the last byte of the file, an application refer-
ence to any of the pages in the mapping that are beyond the last page
results in the delivery of a SIGBUS or SIGSEGV signal.
The mmap() function adds 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 is removed when there
are no more mappings to the file.
The statime 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 will cause the
file's statime field to be marked for update if it has not already
been marked for update.
The stctime and stmtime fields of a file that is mapped with
MAPSHARED and PROTWRITE, will 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 MSASYNC or MSSYNC for that portion of the
file by any process. If there is no such call, these fields may be
marked for update at any time after a write reference if the underly-
ing file is modified as a result.
There may be implementation-dependent 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 implemen-
tation-dependent.
There is no functional difference between mmap() and mmap64(), except
for the interpretation of off64t [see lfs(5)].
RETURN VALUE
Upon successful completion, mmap() returns the address at which the
mapping was placed (pa). Otherwise, it returns a value of -1 and sets
errno to indicate the error.
Page 3 Reliant UNIX 5.44 Printed 11/98
mmap(2) mmap(2)
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
The mmap() function will fail if:
EBADF The fildes argument is not a valid open file descriptor.
EACCES The fildes argument is not open for read, regardless of
the protection specified, or fildes is not open for write
and PROTWRITE was specified for a MAPSHARED type map-
ping.
ENXIO Addresses in the range [off, off + len) are invalid for
fildes.
EINVAL The addr argument (if MAPFIXED was specified) or off is
not a multiple of the page size as returned by sysconf(),
or are considered invalid by the implementation.
EINVAL The value of flags is invalid (neither MAPPRIVATE nor
MAPSHARED is set).
EINVAL This executable is a specially preloaded binary. The argu-
ment addr lies illegally between the text and data
regions.
EMFILE The number of mapped regions would exceed an implementa-
tion-dependent limit (per process or per system).
ENODEV The fildes argument refers to a file whose type is not
supported by mmap().
ENOMEM MAPFIXED was specified and the range [addr, addr + len)
exceeds that allowed for the address space of a process,
or MAPFIXED was not specified and there is insufficient
memory space within the address space to effect the map-
ping.
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.
NOTES
Use of mmap() may reduce the amount of memory available to other
memory allocation functions.
Use of MAPFIXED may result in unspecified behavior in further use of
brk(), sbrk(), malloc() and shmat(). The use of MAPFIXED is
discouraged, as it may prevent an implementation from making the most
effective use of resources.
Page 4 Reliant UNIX 5.44 Printed 11/98
mmap(2) mmap(2)
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 mani-
pulations, 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 follow-
ing:
fildes = open(...)
lseek(fildes, someoffset)
read(fildes, buf, len)
/* use data in buf */
becomes:
fildes = open(...)
address = mmap(0, len, PROTREAD, MAPPRIVATE, fildes, someoffset)
/* use data at address */
For consistency with read() and write(), the mmap() function will fail
when the request extends beyond the offset maximum.
SEE ALSO
exec(2), fcntl(2), fork(2), mprotect(2), munmap(2), plock(2),
shmat(2), lockf(3C), mlockall(3C), sysconf(3C), lfs(5), mman(5),
preload(8).
Page 5 Reliant UNIX 5.44 Printed 11/98