MMAP(2) SysV MMAP(2)
NAME
mmap, msync, munmap - map file system object into virtual memory
SYNOPSIS
#include <sys/mman.h>
mmaddr = mmap(addr, len, prot, flags, fd, pos)
caddr_t maddr, addr;
int *len, prot, flags, fd;
off_t pos;
In the AES variant of this call, len is passed differently, as follows:
size_t len
msync(addr, len, flags)
caddr_t addr;
int len;
int flags;
The flag argument is passed only in the AES variant of the msync call.
munmap(addr, len)
caddr_t addr;
int len, prot;
maddr = mremap(addr, len, pos)
caddr_t maddr, addr;
int *len;
off_t pos;
DESCRIPTION
mmap creates a new mapped file or shared memory region. The arguments are
defined as follows:
addr Specifies the starting address of the new region.
len Specifies the length in bytes of the new region.
prot Specifies access permissions as any combination of PROT_READ,
PROT_WRITE and PROT_EXEC ORed together, or PROT_NONE.
flags
Specifies attributes of the mapped region. AES includes any
combination of the following MAP_FILE, MAP_ANONYMOUS, MAP_VARIABLE,
MAP_FIXED, MAP_SHARED, or MAP_PRIVATE, ORed together.
Additional Domain/OS flags include: MAP_TYPE, MAP_INHERIT,
MAP_HASSEMAPHORE, and MAP_NOEXTEND.
fd Specifies the file to be mapped to the new mapped file region.
pos Specifies the offset for the address. In an AES environment, pos
must be a multiple of the system page size.
The addr and len arguments specify the requested starting address and
length in bytes of the region.
The pos and addr arguments must be the same distance from a multiple of
the system segment size. That is,
(pos mod seg_size) == (addr mod seg_size)
where
seg_size=32K for Apollo M68K (M68010, M68020, M68030) workstations
seg_size=512K for Apollo M88K (AT) workstations
seg_size=256K for Apollo M68K (M68040) workstations.
The flags argument specifies the type of object to be mapped, mapping
options, and whether modifications made to this mapped copy of the
segment are to be kept "private" or are to be "shared" with other
references. <sys/mman.h> defines the possible settings for flags:
/* flags contain mapping type, sharing type, and options */
/* mapping type; choose one */
#define MAP_FILE 0x0001 /* mapped from a file or device */
#define MAP_ANONYMOUS 0x0002 /* create an unnamed virtual memory region */
#define MAP_TYPE 0x000f /* mask for type field */
Note that MAP_ANON is an obsolete alias; sys/mman.h defines MAP_ANON as follows:
#define MAP_ANON MAP_ANONYMOUS
/* sharing types; choose one */
#define MAP_SHARED 0x0010 /* share changes */
#define MAP_PRIVATE 0x0000 /* changes are private */
/* placement types; chose one: */
#define MAP_VARIABLE 0x0000 /* Place region at the computed address */
#define MAP_FIXED 0x0020 /* map addr must be exactly as requested */
/* other flags */
#define MAP_INHERIT 0x0040/* region is retained after exec */
#define MAP_HASSEMAPHORE 0x0080 /* region may contain semaphores */
#define MAP_NOEXTEND 0x0100/* backing file may not be extended */
The MAP_FILE and MAP_ANONYMOUS flags control whether the region to be
mapped is a mapped file region or an anonymous shared memory region.
Exactly one of these flags must be selected.
If MAP_FILE is set in the flags argument:
+ A new mapped file region is created, mapping the file associated
with the fd argument.
+ The pos argument specifies the file byte offset at which the mapping
starts. In an AES environment, this offset must be a multiple of the
system page size.
If MAP_ANONYMOUS is set in the flags argument:
+ A new anonymous virtual memory a region is created. This memory
region can be shared only with descendents of the current process.
The pos argument is not used and should not be specified as zero.
+ The MAP_SHARED, MAP_PRIVATE, and MAP_NOEXTEND flags have no affect.
mmap returns the address at which this mapping is established. This
address may not be the same as addr, unless the MAP_FIXED flag is given
(see description of MAP_FIXED below). In this case, the exact address
specified by addr will be used or the call will fail.
On return, the len argument is set to the size of the mapping that is
actually established. Unless MAP_NOEXTEND is specified, it may be
greater than the specified size since it is rounded up to include the
entire segment in which the mapping ends (see description of MAP_NOEXTEND
below). Note that in an AES environment, len is an input only argument;
nothing is returned. In addition, the MAP_NOEXTEND flag has no effect;
that is, the call behaves as if the flag was specified.
The MAP_VARIABLE and MAP_FIXED flags control the placement of the region
when the requested address is null or the region cannot be placed at the
requested address. A region is never placed at address zero, or at an
address where it would overlap with an existing region. Exactly one of
these flags must be selected.
If MAP_VARIABLE is set in the flags argument:
In a non-AES environment, the system will choose an address at which
to establish the mapping.
In an AES environment, the system will first attempt to establish
the mapping at the requested address. If this requested address is
null or the mapping cannot be placed there, the system will choose
an address at which to establish the mapping.
If MAP_FIXED is set in the flags argument:
+ If the requested address is null, the behavior is dependent on the
environment. In an AES environment, the system will choose an
address at which to establish the mapping. In a non-AES
environment, the mmap call fails.
+ Otherwise, if it is not possible for the region to be placed at this
address, the mmap function fails. In a non-AES environment, mmap
first removes anything mapped within the specified address range.
The MAP_PRIVATE and MAP_SHARED flags control the visibility of
modifications to the mapped file or shared memory region. Exactly one of
these flags must be selected.
If MAP_SHARED is set in the flags argument:
+ If the region is a mapped file region, modifications to the region
are visible to other processes which have mapped the same region
using MAP_SHARED.
+ If the region is a mapped file region, modifications to the region
are written to the file.
In a non-AES environment, The MAP_SHARED flag is ignored: descendents of
the process share the mapping instead of getting a copy of the region.
If MAP_PRIVATE is set in the flags argument:
+ Modifications to the mapped region by the calling process are not
visible to other processes which have mapped the same region using
either MAP_PRIVATE or MAP_SHARED.
+ Modifications to the mapped region by the calling process are not
written to the file.
The MAP_NOEXTEND flag prevents the mapped file from being extended to
include references beyond the current file size, in cases where it is
smaller than the map size. This flag is ignored in an AES environment;
the call behaves as if MAP_NOEXTEND had been specified.
The MAP_HASSEMAPHORE flag allows special handling for regions that may
contain semaphores. Under Domain/OS, this flag is ignored.
The MAP_INHERIT flag allows a region to be inherited after an exec.
The prot argument specifies the mapped region's access permissions. The
sys/mman.h header file defines the following access options:
PROT_READ The mapped region can be read.
PROT_WRITE The mapped region can be written.
PROT_EXEC The mapped region can be executed.
PROT_NONE The mapped region cannot be accessed.
The prot argument can be PROT_NONE or any combination of PROT_READ,
PROT_WRITE, and PROT_EXEC ORed together. If PROT_NONE is not specified,
access permissions may be granted to the region in addition to those
explicitly requested, except that write access is not granted unless
PROT_WRITE is specified.
In a non-AES environment, Domain/OS does not support copy-on-write
mappings (FLAGS == MAP_PRIVATE and PROT == PROT_WRITE). Under these
condition, mmap returns an [EINVAL] error.
If the region is a mapped file that was mapped with MAP_SHARED, the mmap
function grants read or execute access permission only if the file
descriptor used to map the file is open for reading, and grants write
access permission only if the file descriptor used to map the file is
open for writing. If the region is a mapped file which was mapped with
MAP_PRIVATE, the mmap function grants read, write, or execute access
permission only if the file descriptor used to map the file is open for
reading. If the region is a shared memory region which was mapped with
MAP_ANONYMOUS, the mmap function grants all requested access permissions.
After the successful completion of the mmap function, the fd argument may
be closed without effect on the mapped region or on the contents of the
mapped file. Each mapped region creates a file reference, similar to an
open file descriptor, which prevents the file data from being
deallocated.
If the contents of a file are changed via a modification to a mapped
region to it, that change will be visible to subsequent read() functions.
If the contents of a file are changed via a write() function, that change
is visible within any mapped regions to it.
After a call to the fork function, the child process inherits all mapped
regions with the same sharing and protection attributes as in the parent
process. Each mapped file and shared memory region created with the mmap
function is unmapped by a successful call to any of the exec functions,
unless that region is made inheritable across exec (see MAP_INHERIT).
Use msync to synchronize a mapped region with the file it maps. It
writes any modified segments back to the file system and updates the file
modification time. The arguments are defined as follows:
addr Specifies the address of the region to be synchronized.
len Specifies the length in bytes of the region to be synchronized.
flags
Specifies one of the following symbolic constants defined in the
sys/mman.h file:
MS_SYNC
Synchronous cache flush
MS_ASYNC
Asynchronous cache flush
MS_INVALIDATE
Invalidate cached pages
The flag argument is passed only in the AES variant of the call.
In an non-AES environment, the call behaves as if MS_SYNC was
specified.
If len is 0, all modified segments within the region containing addr will
be flushed; if len is nonzero, only the segments containing addr and len
succeeding locations will be examined. Any required invalidation of
memory caches will also take place at this time. File system operations
on a file which is mapped for shared modifications are unpredictable
except after a call to msync.
If the flags argument is set to MS_SYNC, the msync function does not
return until the system completes all I/O operations. If the flags
argument is set to MS_ASYNC, the msync function returns after the system
schedules all I/O operations. If the flags argument is set to
MS_INVALIDATE, the msync function invalidates all cached copies of the
pages. New copies of the pages then must be obtained from the file
system the next time they are referenced.
munmap unmaps whatever mappings exist within the specified address space
range. munmap deletes the region containing the address given, and causes
further references to addresses within the region to generate invalid
memory references.
mremap maps new segments of the object currently mapped at addr into the
process' address space. The new mapping will have the same protections,
map type, and flags as the old mapping. The starting address of the
newly mapped region is returned, and the actual amount mapped is returned
in len. mremap attempts to establish the new mapping at the same virtual
memory address as the mapping region which is being released
NOTES
The Domain/OS implementation of the mmap functions differs from the AES
specification as follows:
In Domain/OS, the unit of mapping and protection is the segment.
According to the AES, the unit of mapping is the page size, returned
by sysconf(_SC_PAGE_SIZE).
Only regular files may be mapped (not directories, pipes, or device
special files). It currently is not possible to map a file named using
extended naming (an NFS* or Domain/Access file, for example).
*NFS is a registered trademark of Sun Microsystems Inc.
DIAGNOSTICS
In a non-AES environment, if successful, mmap returns the starting
address of the mapping. Otherwise, it returns NULL and sets errno as
indicated below.
In an AES environment: if successful, mmap returns the starting address
of the mapping. Otherwise, it returns CADDR_T(-1) and sets errno as
indicated below.
ERRORS
mmap will fail if any of the following is true:
[EINVAL] An invalid argument was specified: undefined protection mode,
unknown mapping type, not a regular file, attempt to MAP_FIXED
with a segment boundary mismatch; a bad length was specified.
[EINVAL] Tried to use an unimplemented feature: copy-on-write, file
descriptor for MAP_ANONYMOUS, map a file with an extended
name.
[EINVAL] In an AES environment: The flags or prot argument is invalid,
or the addr argument or pos argument is not a multiple of the
page size returned by sysconf(_SC_PAGE_SIZE).
[EACCESS] Attempt to map a file in a way precluded by file protection
(for example, trying to map for write a file for which the
caller has only read access rights).
[ENOMEM] addr conflicts with an existing mapping when attempting to
MAP_FIXED.
[ENOMEM] Out of virtual address space.
[EBADF] The supplied file descriptor was not open or was invalid.
[EIO] I/O error occurred while trying to map the object.
[ETXTBSY] Write access requested to a pure-procedure (shared text) file
that is being executed.
[EROFS] Write access requested to a file residing on a read-only file
system.
[ENODEV] The file descriptor fd refers to an object that cannot be
mapped, such as a terminal.
[ENXIO] The addresses specified by the range [pos, pos + len) are
invalid for fd.
msync will fail if either of the following is true:
[ENOENT] No region is mapped at the specified address.
[EIO] I/O error occurred during the force-write operation.
[ENOMEM] Out of virtual address space.
munmap will fail if either of the following is true:
[ENOENT] No region is mapped at the specified address.
[EINVAL] A bad length was specified.
mremap will fail if either of the following is true:
[ENOENT] No region is mapped at the specified address.
[ENOMEM] No virtual address space was available for the mapping.
[EIO] I/O error occurred while trying to set up the mapping.
SEE ALSO
madvise(2), mprotect(2), mset(2).