MMAP(2) Domain/OS BSD 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;
msync(addr, len)
caddr_t addr;
int len;
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 causes the pages starting at addr and continuing for at most len
bytes to be mapped from the object represented by descriptor fd, starting
at an offset of pos bytes from the beginning of the object. flags
specifies the type of object to be mapped, mapping options, and whether
modifications made to this mapped copy of the page 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_ANON 0x0002 /* allocated from memory, swap space */
#define MAP_TYPE 0x000f /* mask for type field */
/* sharing types; choose one */
#define MAP_SHARED 0x0010 /* share changes */
#define MAP_PRIVATE 0x0000 /* changes are private */
/* other flags */
#define MAP_FIXED 0x0020 /* map addr must be exactly as requested */
#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 */
MAP_ANON maps memory not associated with any specific file. The file
descriptor used for creating MAP_ANON regions is used only for naming and
must be given as -1.
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. The MAP_HASSEMAPHORE flag allows special
handling for regions that may contain semaphores. The MAP_INHERIT flag
allows a region to be inherited after an exec.
mmap returns a convenient starting address for the region. This address
may not be the same as addr, unless the MAP_FIXED flag is given. In this
case, the exact address will be used or the call will fail.
When used with MAP_FIXED, the offset of pos from a hardware boundary
equal to the segment size must be the same as the offset of addr from the
same boundary. Therefore, the following must be true:
(pos mod seg_size) == (addr mod seg_size)
where seg_size=32768 for Apollo M68K (M680X0) workstations, and
seg_size=524288 for Apollo M88K (AT) workstations. The only time mmap
will remove an existing mapping is when flags == MAP_FIXED, the existing
mapping begins at addr, and the call to mmap succeeds. mmap will not
remove existing mappings that merely overlap the specified range. In
this case, mmap returns an error. If MAP_FIXED is not specified, existing
mappings not removed: mmap ignores addr and the system chooses an
address for the region.
The actual amount of virtual memory mapped is returned in len. addr,
len, and pos must all be multiples of the page size. Use getpagesize(2)
to determine the size of a page.
prot specifies the accessibility of the mapped pages, as defined in
<sys/mman.h>:
/* protections are chosen from these bits, ORed together */
#define PROT_READ 0x04 /* pages can be read */
#define PROT_WRITE 0x02 /* pages can be written */
#define PROT_EXEC 0x01 /* pages can be executed */
Currently, Domain/OS BSD does not support copy-on-write mapping (flags ==
MAP_PRIVATE and prot == PROT_WRITE). Under these conditions, mmap
returns an error.
Use msync to synchronize a mapped region with the file it maps. It
writes any modified pages back to the file system and updates the file
modification time. If len is 0, all modified pages within the region
containing addr will be flushed; if len is nonzero, only the pages
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.
A mapping can be removed by a call to munmap. munmap deletes the region
containing the address given, and causes further references to addresses
within the region to generate invalid memory references.
mremap maps different pages of the object currently mapped at addr into
the process' address space, thereby replacing the old mapping. The new
mapping will have the same protections, map type, and flags as the old
mapping, but starts at pos bytes from the beginning of the object being
mapped. The starting address of the newly mapped region is returned, and
the actual amount mapped is returned in len.
NOTES
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).
We recommend that you not map a region in a vfork'ed child process
(between the vfork and the exec). Such a region will NOT remain mapped
in the parent process' address space when the child exec's or exit's.
This implementation is based upon a proposal by McKusick and Karels, and
upon other sources. Its details may change in a future release.
*NFS is a registered trademark of Sun Microsystems Inc.
SEE ALSO
McKusick, M.K. and Karels, M.J. A New Virtual Memory Implementation for
Berkeley UNIX. Berkeley, California: Department of Electrical
Engineering and Computer Science, University of California, 1986.
madvise(2), mprotect(2), mset(2).
DIAGNOSTICS
If successful, mmap returns the starting address of the mapping.
Otherwise, it returns NULL 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_ANON, map a file with an extended name.
[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.
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.
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.