The mmap(2) function maps a file on disk into a
buffer in memory so that when bytes are retrieved from the buffer,
they're read from the file. The file has the open file descriptor
fd and the function maps len bytes of the file. The
portion of the file to be mapped to the buffer is off bytes
from the beginning of the file. The function returns a pointer
(pa such that the range [pa pa+ len) is
the same as the range [fd fd+ len).
addr
The point in the address space where the mapping should be
placed. Normally this is set to zero, which indicates that the
system may place the mapping anywhere. If it's a positive non-zero
value, then it is considered a hint to the system for placing the
buffer. This can be changed by setting MAP_FIXED in the
flags argument; if set, the function must return the value
of addr as the address of the buffer. If it cannot, the
function fails. The value of addr should be a multiple of
the system's virtual memory page size, returned by sysconf(2) with
the argument _SC_PAGESIZE (or _SC_PAGE_SIZE).
len
The length of the mapped space, in bytes. It's rounded up to
the nearest multiple of sysconf(_SC_PAGE_SIZE).
prot
The set of accesses permitted to the pages being mapped.
Traditionally these should be the same as the open mode of the file
(that is, you can't write to the memory if the file was opened
read-only). These access values are defined in
<sys/mman.h>:
PROT_READ
Read permission.
PROT_WRITE
Write permission.
PROT_EXEC
Execute permission.
PROT_NONE
No access allowed.
flags
Other information about how the mapped file is to be handled.
Possible values are:
MAP_SHARED
Changes can be shared; cannot be specified with MAP_PRIVATE.
When the calling process writes to the memory region, the file may
be changed. These changes are visible in all MAP_SHARED mappings of
the same portion of the file, by any process.
MAP_PRIVATE
Changes are private; cannot be specified with MAP_SHARED. When
the calling process writes to the memory region, the file isn't
changed, they affect a copy of the file. No other process mapping
the same portion of the file can see these changes.
MAP_FIXED
The pointer returned by the function must be equal to
addr. Normally, the returned pointer is derived from the
addr but doesn't have to be identical. This is the least
portable way of coding with the function.
This information is retained across a fork(2), but not across an
exec(2).
fd
The file descriptor of the file to be mapped. The file should
have already been opened.
off
The offset to the part of the file where mapping should start.
The value of off should be a multiple of the system's
virtual memory page size, returned by
sysconf(_SC_PAGESIZE).
When the process terminates, the mapped region is unmapped. It
does not unmap when fd is closed.
You can also explicitly unmap the region by calling the
munmap(2) function.
The file indicated by fd wasn't open to be read; or
fd wasn't open for writing and PROT_WRITE was specified for
a MAP_SHARED mapping.
[ENXIO]
The addresses [off, off+len) were invalid
for fd.
[EINVAL]
The off (or the addr argument, if MAP_FIXED was
specified), was not a multiple of the page size (as returned by
sysconf(2)) or was otherwise invalid; or
flags was invalid (neither MAP_PRIVATE nor MAP_SHARED was
set).
[EINVAL]
MAP_ANON was specified and the off address was non-zero;
the size of the anonymous memory section created is len
bytes long.
[EMFILE]
Fulfilling the request would exceed the system limit on the
number of mapped regions.
[ENODEV]
The fd refers to a file of an unsupported type.
[ENOMEM]
If MAP_FIXED was specified, then the range [addr,
addr+len) is greater than allowed for a process'
address space; if MAP_FIXED was not specified, there is
insufficient room in the address space to perform the mapping.