mmap(2) UNIX System V mmap(2)
NAME
mmap - map pages of memory
SYNOPSIS
#include <sys/types.h>
#include <sys/mman.h>
caddrt mmap(caddrt addr, sizet len, int prot, int flags, int fd, offt
off);
DESCRIPTION
The function mmap establishes 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.
mmap cannot grow a file.
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, write, 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. However, no implementation will permit a write 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.
10/89 Page 1
mmap(2) UNIX System V mmap(2)
MAPSHARED and MAPPRIVATE describe the disposition of write references
to the memory object. If MAPSHARED is specified, write references will
change the memory object. If MAPPRIVATE is specified, the initial write
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).
Note that the private copy is not created until the first write; until
then, other users who have the object mapped MAPSHARED can change the
object.
MAPFIXED informs the system that the value of pa must be addr, exactly.
The use of MAPFIXED is discouraged, as it may prevent an implementation
from making the most effective use of system resources.
When MAPFIXED is not set, the system uses addr in an implementation-
defined 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. 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, nor map into areas
considered part of the potential data or stack segments.
The parameter off is constrained to be aligned and sized according to the
value returned by sysconf. When MAPFIXED is specified, the parameter
addr must also meet these constraints. 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.
RETURN VALUE
On success, mmap returns the address at which the mapping was placed
(pa). On failure it returns (caddrt)-1 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 or MAPFIXED was not
specified and there is insufficient room in the address space to
effect the mapping.
Page 2 10/89
mmap(2) UNIX System V mmap(2)
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.
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 page size as returned by sysconf.
EINVAL The field in flags is invalid (neither MAPPRIVATE or MAPSHARED).
EINVAL The argument len has a value less than or equal to 0.
ENODEV fd refers to an object for which mmap is meaningless, such as a
terminal.
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 room in the address space
to effect 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((caddrt) 0, len, (PROTREAD | PROTWRITE),
MAPPRIVATE, fd, offset)
/* use data at address */
SEE ALSO
fcntl(2), fork(2), lockf(3C), mlockall(3C), mprotect(2), munmap(2),
plock(2), sysconf(2).
10/89 Page 3