mmap preferred-address length protection flags file-descriptor offset => address, error
preferred-address -- A non-negative integer, or nil.
length -- A non-negative integer.
protection -- A non-negative fixnum.
flags -- A non-negative fixnum.
file-descriptor -- A non-negative fixnum.
offset -- A non-negative integer.
address -- A non-negative integer.
error -- A fixnum.
mmap creates a new mapping in the virtual address space of the calling process. The starting address for the new mapping is specified in preferred-address. The length argument specifies the length of the mapping.
If preferred-address is nil, then the kernel chooses the address at which to create the mapping; this is the most portable method of creating a new mapping. If preferred-address is not nil, then the kernel takes it as a hint about where to place the mapping; on Linux, the mapping will be created at a nearby page boundary. The address of the new mapping is returned as the result of the call.
The contents of a file mapping (as opposed to an anonymous mapping; see +map-anonymous+), are initialized using length bytes starting at offset offset in the file (or other object) referred to by the file descriptor file-descriptor. The argument offset must be a multiple of the page size.
The protection argument describes the desired memory protection of the mapping (and must not conflict with the open mode of the file). It is either +prot-none+ or the bitwise or of one or more of the following flags:
| +prot-exec+ |
Pages may be executed. |
| +prot-read+ |
Pages may be read. |
| +prot-write+ |
Pages may be written. |
| +prot-none+ |
Pages may not be accessed. |
The flags argument determines whether updates to the mapping are visible to other processes mapping the same region, and whether updates are carried through to the underlying file. This behavior is determined by including exactly one of the following values in flags:
| +map-shared+ |
Share this mapping. Updates to the mapping are visible to other processes that map this file, and are carried through to the underlying file. The file may not actually be updated until msync or munmap is called. |
| +map-private+ |
Create a private copy-on-write mapping. Updates to the mapping are not visible to other processes mapping the same file, and are not carried through to the underlying file. It is unspecified whether changes made to the file after the mmap call are visible in the mapped region. |
Both of these flags are described in POSIX.1-2001.
In addition, zero or more of the following values can be ORed in flags:
Of the above flags, only +map-fixed+ is specified in POSIX.1-2001. However, most systems also support +map-anonymous+ (or its synonym +map-anon+).
Some systems document the additional flags +map-autogrow+, +map-autoresrv+, +map-copy+, and +map-local+.
Memory mapped by mmap is preserved across fork with the same attributes.
A file is mapped in multiples of the page size. For a file that is not a multiple of the page size, the remaining memory is zeroed when mapped, and writes to that region are not written out to the file. The effect of changing the size of the underlying file of a mapping on the pages that correspond to added or removed regions of the file is unspecified.
| +eacces+ |
A file descriptor refers to a non-regular file. Or +map-private+ was requested, but file-descriptor is not open for reading. Or +map-shared+ +map-shared+ was requested and +prot-write+ is set, but file-descriptor is not open in read/write (+o-rdwr+) mode. Or +prot-write+ is set, but the file is append-only. |
| +eagain+ |
The file has been locked, or too much memory has been locked (see setrlimit). |
| +ebadf+ |
file-descriptor is not a valid file descriptor (and +map-anonymous+ was not set). |
| +einval+ |
The argument address or the argument length or the argument offset is too large or not aligned on a page boundary. |
| +einval+ |
(since Linux 2.6.12) length was 0. |
| +einval+ |
flags contained neither MAP_PRIVATE or MAP_SHARED, or contained both of these values. |
| +enfile+ |
The system limit on the total number of open files has been reached. |
| +enodev+ |
The underlying filesystem of the specified file does not support memory mapping. |
| +enomem+ |
No memory is available, or the process's maximum number of mappings would have been exceeded. |
| +eperm+ |
The protection argument asks for +prot-exec+ but the mapped area belongs to a file on a filesystem that was mounted no-exec. |
| +etxtbsy+ |
+map-denywrite+ was set but the object specified by file-descriptor is open for writing. |
| +eoverflow+ |
On 32-bit architecture together with the large file extension (i.e., using 64-bit off_t): the number of pages used for length plus number of pages used for offset would overflow unsigned long (32 bits). |
More to be filled in later...