mmap(2) mmap(2)
NAME
mmap - map pages of memory
SYNOPSIS
#include <sys/types.h>
#include <sys/mman.h>
caddr_t mmap(caddr_t addr, size_t len, int prot, int flags, int fd,
off_t off);
DESCRIPTION
mmap establishes a mapping between a process's address space
and a virtual memory object (a file). The mapping allows you
to perform I/O without using read(2) and write(2): when you
retrieve or store data in the mapped region, the system reads
from or writes to the corresponding file.
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 and the file 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.
fd Parameter
fd is the file descriptor for the file to be mapped. The file
must be a virtual memory object, that is, it must be able to
be treated as storage. Some devices can be mapped, but their
behavior is device-specific and sometimes implementation-
specific. However, some devices, such as /dev/zero and
/dev/dzero, are generic. Typically file systems do not allow
directories to be mapped.
prot Parameter
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.
Copyright 1994 Novell, Inc. Page 1
mmap(2) mmap(2)
Not all implementations literally provide all possible
combinations. 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.
flags Parameter
The parameter flags provides other information about the
handling of the mapped pages. The options are defined in
sys/mman.h as:
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 file. If MAP_SHARED is specified, write
references will change the file. If MAP_PRIVATE is specified,
the initial write reference will create a private copy of the
modified file 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 either the
first write or the page is locked for write access [see
memcntl(2)]; until then, other users who have the file mapped
MAP_SHARED can change the image of the file observed in the
mapped page.
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.
addr Parameter
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
file. 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
Copyright 1994 Novell, Inc. Page 2
mmap(2) mmap(2)
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. pa will be aligned
on a page boundary. When MAP_FIXED is specified, addr must be
aligned on a page boundary.
off Parameter
off is the offset into the file to be mapped. off is
constrained to be aligned on a page boundary.
len Parameter
The system performs mapping operations over whole pages.
Therefore, if len is not a multiple of the page size [as
returned by sysconf(3C)], the system will include in the
mapped region the remainder of any partial page specified by
the range [pa, pa + len). (The notation [start, end) denotes
the interval from start to end, including start but excluding
end.)
Further Details
The address range covered by [pa, pa + len) must be legitimate
for the address space of a process. 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).
In the case where off + len exceeds the length of the file,
the system will zero-fill the mapping from the end of the file
to the next page boundary. If the process modifies any
portion of the mapped region beyond the end of the file, there
is no guarantee that the system will write those changes out
to the file; the results are file system dependent.
References to pages in a mapped region which are beyond the
page containing the end of a file will result in the delivery
of a SIGBUS signal. SIGBUS signals may also be delivered on
various file system conditions, including quota exceeded
errors.
mmap adds an extra reference to the file associated with the
file descriptor fd which is not removed by a subsequent close
on that file descriptor. This reference is removed when the
entire range is unmapped (explicitly or implicitly). A
mapping is unmapped explicitly with munmap, or implicitly with
exit(2), exec(2), or by an mmap MAP_FIXED to the same range.
Copyright 1994 Novell, Inc. Page 3
mmap(2) mmap(2)
Return Values
On success, mmap returns the address at which the mapping was
placed (pa). On failure, mmap returns (caddr_t)-1 and sets
errno to identify the error.
Errors
In the following conditions, mmap fails and sets errno to:
EAGAIN The mapping could not be locked in memory or MAP_FIXED
was not specified and there is insufficient room in the
address space to effect the mapping.
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.
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).
ENODEV fd refers to a file for which mmap is meaningless, such
as a terminal.
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.
USAGE
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 file was mapped.
Consider the following pseudo-code:
fd = open(...)
lseek(fd, offset)
read(fd, buf, len)
/* use data in buf */
Copyright 1994 Novell, Inc. Page 4
mmap(2) mmap(2)
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 */
REFERENCES
exec(2), exit(2), fcntl(2), fork(2), lockf(3C), mlockall(3C),
mprotect(2), munmap(2), plock(2), read(2) sysconf(3C),
write(2)
NOTICES
Considerations for Threads Programming
Sibling threads share (by definition) the same address space;
modifications to the address space by one can be perceived by
the others.
Copyright 1994 Novell, Inc. Page 5