MMAP(2) RISC/os Reference Manual 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 func-
tion 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 map-
pings 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:
PROT_READ Page can be read.
PROT_WRITE Page can be written.
PROT_EXEC Page can be executed.
PROT_NONE Page can not be accessed.
Not all implementations literally provide all possible com-
binations. PROT_WRITE is often implemented as PROT_READ |
PROT_WRITE and PROT_EXEC as PROT_READ | PROT_EXEC. However,
no implementation will permit a write to succeed where
PROT_WRITE has not been set. The behavior of PROT_WRITE can
be influenced by setting MAP_PRIVATE 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:
Printed 11/19/92 Page 1
MMAP(2) RISC/os Reference Manual MMAP(2)
MAP_SHARED Share changes.
MAP_PRIVATE Changes are private.
MAP_FIXED Interpret addr exactly.
MAP_SHARED and MAP_PRIVATE describe the disposition of write
references to the memory object. If MAP_SHARED is speci-
fied, write references will change the memory object. If
MAP_PRIVATE is specified, the initial write reference will
create a private copy of the memory object page and redirect
the mapping to the copy. Either MAP_SHARED or MAP_PRIVATE
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
MAP_SHARED can change the object.
MAP_FIXED informs the system that the value of pa must be
addr, exactly. The use of MAP_FIXED is discouraged, as it
may prevent an implementation from making the most effective
use of system resources.
When MAP_FIXED 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. For systypes svr3
and bsd43 addr is set at all times implicitly to non-zero
and implies MAP-FIXED. 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 MAP_FIXED
is specified, the parameter addr must also meet these con-
straints. 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
Page 2 Printed 11/19/92
MMAP(2) RISC/os Reference Manual MMAP(2)
conditions, including quota exceeded errors.
Note that mmap can sometimes be used to install memory-
mapped devices without writing a device driver. However,
this does not always work. In particular, devices that are
mmap'ed into user space and then accessed by user programs
will see those accesses in user mode. If the device con-
tains registers that must be accessed in supervisor mode,
mmap cannot be used to drive it.
RETURN VALUE
On success, mmap returns the address at which the mapping
was placed (pa). On failure it returns (caddr_t)-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.
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 PROT_WRITE
was specified for a MAP_SHARED type mapping.
ENXIO Addresses in the range [off, off + len) are invalid
for fd.
EINVAL The arguments addr (if MAP_FIXED was specified) or
off are not multiples of the page size as returned by
sysconf.
EINVAL The field in flags is invalid (neither MAP_PRIVATE or
MAP_SHARED).
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.
Printed 11/19/92 Page 3
MMAP(2) RISC/os Reference Manual MMAP(2)
ENOMEM MAP_FIXED was specified and the range [addr, addr +
len) exceeds that allowed for the address space of a
process, or MAP_FIXED was not specified and there is
insufficient room in the address space to effect the
mapping.
EINVAL The argument address or length is not a multiple of
the page size as returned by getpagesize(2), or the
length is negative.
EINVAL The entire range of pages specified in the call is
not part of data space.
EINVAL The sharing mode was not specified as MAP_SHARED.
EINVAL Another file mapped by mmap is open.
EINVAL An attempt was made to map a page that is being
shared with another process.
NOTES
mmap allows access to resources via address space manipula-
tions 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((caddr_t) 0, len, (PROT_READ | PROT_WRITE),
MAP_PRIVATE, fd, offset)
/* use data at address */
SEE ALSO
fcntl(2), fork(2), lockf(3C), mlockall(3C), mprotect(2),
munmap(2), plock(2), sysconf(2), close(2), getpagesize(2),
malloc(3).
Page 4 Printed 11/19/92