MMAP(2) — SYSTEM CALLS
NAME
mmap − map pages of memory
SYNOPSIS
#include <sys/types.h>
#include <sys/mman.h>
caddr_t mmap(addr, len, prot, flags, fd, off)
caddr_t addr;
int len, prot, flags, fd;
off_t off;
DESCRIPTION
mmap() establishes a mapping between the process’s address space at an address paddr for len bytes to the memory object represented by fd at off for len bytes. The value of paddr is an implementation-dependent function of the parameter addr and values of flags, further described below. A successful mmap() call returns paddr as its result. The address ranges covered by [paddr, paddr + len) and [off, off + len) must be legitimate for the address space of a process and the object in question, respectively.
The mapping established by mmap() replaces any previous mappings for the process’s pages in the range [paddr, paddr + len).
The parameter prot determines whether read, execute, write, or some combination of accesses are permitted to the pages being mapped. The protection options are defined in /usr/include/sys/mman.h as:
#define PROT_READ0x1/∗ page can be read ∗/
#define PROT_WRITE0x2/∗ page can be written ∗/
#define PROT_EXEC0x4/∗ page can be executed ∗/
#define PROT_NONE0x0/∗ page can not be accessed ∗/
Not all implementations literally provide all possible combinations. PROT_WRITE is often implemented as PROT_READ|PROT_WRITE and PROT_EXECUTE as PROT_READ|PROT_EXECUTE. 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 mman.h as:
#define MAP_SHARED1/∗ Share changes ∗/
#define MAP_PRIVATE2/∗ Changes are private ∗/
#define MAP_TYPE0xf/∗ Mask for type of mapping ∗/
#define MAP_FIXED0x10/∗ Interpret addr exactly ∗/
#define MAP_RENAME0x20/∗ Assign page to file ∗/
MAP_SHARED and MAP_PRIVATE describe the disposition of write references to the memory object. If MAP_SHARED is specified, 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. The mapping type is retained across a fork(2).
MAP_FIXED informs the system that the value of paddr 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 as a hint in an implementation-defined manner to arrive at paddr. The paddr 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 paddr, 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 paddr, 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”.
MAP_RENAME causes the pages currently mapped in the range [paddr, paddr + len) to be effectively renamed to be the file pages at [off, off + len). The currently mapped pages must be mapped as MAP_PRIVATE. MAP_RENAME implies a MAP_FIXED interpretation of addr. fd must be open for writing. MAP_RENAME affects the size of the memory object referenced by fd: the size is max(off + len - 1, flen) (where flen was the previous length of the object). After the pages are renamed, a mapping to them is reestablished with the parameters as specified in the renaming mmap.
The parameter off is constrained to be aligned and sized according to the value returned by getpagesize (2). When MAP_FIXED 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 [paddr, paddr + len).
It should be noted that the system will always zero-fill any partial pages 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 filesystem conditions, including quota exceeded errors.
RETURN VALUE
A successful mmap() returns the address at which the mapping was placed (paddr). A failing mmap() returns −1.
ERRORS
mmap() will fail if:
EBADF fd is not open.
EACCES fd is not open for read and PROT_READ or PROT_EXECUTE were 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) and off are not multiples of the page size as returned by getpagesize (2).
EINVAL The MAP_TYPE field in flags is invalid (neither MAP_PRIVATE or MAP_SHARED).
ENODEV fd refers to an object for which mmap() is meaningless, such as a terminal; or if the object does support mmap() and MAP_RENAME was specified then the object is unable to support MAP_RENAME (for instance, MAP_RENAME to a frame buffer or other device).
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.
ENOSPC MAP_RENAME was specified and there is no space left on the filesystem to hold the pages.
ETXTBSY One or more pages specified by an mmap() MAP_RENAME operation are not mapped MAP_PRIVATE.
SEE ALSO
fork(2), getpagesize(2), mprotect(2), munmap(2), mlockall(3)
BUGS
MAP_RENAME is not implemented.
Sun Release 4.0 — Last change: 25 March 1989