DragonFly On-Line Manual Pages
MMAP(2) DragonFly System Calls Manual MMAP(2)
NAME
mmap - allocate memory, or map files or devices into memory
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/types.h>
#include <sys/mman.h>
void *
mmap(void *addr, size_t len, int prot, int flags, int fd, off_t offset);
DESCRIPTION
The mmap() function causes the pages starting at addr and continuing for
at most len bytes to be mapped from the object described by fd, starting
at byte offset offset. If len is not a multiple of the pagesize, the
mapped region may extend past the specified range. Any such extension
beyond the end of the mapped object will be zero-filled.
If addr is non-zero, it is used as a hint to the system. (As a
convenience to the system, the actual address of the region may differ
from the address supplied.) If addr is zero, an address will be selected
by the system. The actual starting address of the region is returned. A
successful mmap deletes any previous mapping in the allocated address
range.
The protections (region accessibility) are specified in the prot argument
by or'ing the following values:
PROT_NONE Pages may not be accessed.
PROT_READ Pages may be read.
PROT_WRITE Pages may be written.
PROT_EXEC Pages may be executed.
The flags parameter specifies the type of the mapped object, mapping
options and whether modifications made to the mapped copy of the page are
private to the process or are to be shared with other references.
Sharing, mapping type and options are specified in the flags argument by
or'ing the following values:
MAP_ANON Map anonymous memory not associated with any
specific file. The file descriptor used for
creating MAP_ANON must be -1. The offset parameter
is ignored.
MAP_ANONYMOUS This flag is an alias for MAP_ANON and is provided
for compatibility.
MAP_FIXED Do not permit the system to select a different
address than the one specified. If the specified
address contains other mappings those mappings will
be replaced. If the specified address cannot
otherwise be used, mmap() will fail. If MAP_FIXED
is specified, addr must be a multiple of the
pagesize.
MAP_TRYFIXED Try to do a fixed mapping but fail if another
mapping already exists in the space instead of
overwriting the mapping.
When used with MAP_STACK This flag creates a grow-
down stack area with the specified maximum stack
size. It is no longer special-cased and will be
converted to a normal anonymous mmap(), meaning
that other mmap() calls cannot sub-map ungrown
areas returned by prior MAP_STACK maps using
MAP_TRYFIXED. The entire area is now applicable to
the mapping.
Note that the kernel itself can still create auto-
grow areas but will do so for the user stack in
order to maintain backwards compatibility with
older code that might otherwise assume it can map
below the user stack (in particular, older pthread
libraries). This compatibility is deprecated and
will be removed in a future release.
MAP_HASSEMAPHORE Notify the kernel that the region may contain
semaphores and that special handling may be
necessary.
MAP_NOCORE Region is not included in a core file.
MAP_NOSYNC Causes data dirtied via this VM map to be flushed
to physical media only when necessary (usually by
the pager) rather than gratuitously. Typically
this prevents the update daemons from flushing
pages dirtied through such maps and thus allows
efficient sharing of memory across unassociated
processes using a file-backed shared memory map.
Without this option any VM pages you dirty may be
flushed to disk every so often (every 30-60 seconds
usually) which can create performance problems if
you do not need that to occur (such as when you are
using shared file-backed mmap regions for IPC
purposes). Note that VM/filesystem coherency is
maintained whether you use MAP_NOSYNC or not. This
option is not portable across UNIX platforms (yet),
though some may implement the same behavior by
default.
WARNING! Extending a file with ftruncate(2), thus
creating a big hole, and then filling the hole by
modifying a shared mmap() can lead to severe file
fragmentation. In order to avoid such
fragmentation you should always pre-allocate the
file's backing store by write()ing zero's into the
newly extended area prior to modifying the area via
your mmap(). The fragmentation problem is
especially sensitive to MAP_NOSYNC pages, because
pages may be flushed to disk in a totally random
order.
The same applies when using MAP_NOSYNC to implement
a file-based shared memory store. It is
recommended that you create the backing store by
write()ing zero's to the backing file rather than
ftruncate()ing it. You can test file fragmentation
by observing the KB/t (kilobytes per transfer)
results from an "iostat 1" while reading a large
file sequentially, e.g., using "dd if=filename
of=/dev/null bs=32k".
The fsync(2) function will flush all dirty data and
metadata associated with a file, including dirty
NOSYNC VM data, to physical media. The sync(8)
command and sync(2) system call generally do not
flush dirty NOSYNC VM data. The msync(2) system
call is obsolete since BSD implements a coherent
filesystem buffer cache. However, it may be used
to associate dirty VM pages with filesystem buffers
and thus cause them to be flushed to physical media
sooner rather than later.
MAP_PRIVATE Modifications are private.
MAP_SHARED Modifications are shared.
MAP_STACK Map the area as a stack. MAP_ANON is implied.
Offset should be 0, fd must be -1, and prot should
include at least PROT_READ and PROT_WRITE. This
option creates a memory region that grows to at
most len bytes in size, starting from the stack top
and growing down. The stack top is the starting
address returned by the call, plus len bytes. The
bottom of the stack at maximum growth is the
starting address returned by the call.
The entire area is reserved from the point of view
of other mmap() calls, even if not faulted in yet.
Note that unless MAP_FIXED or MAP_TRYFIXED is used,
you cannot count on the returned address matching
the hint you have provided.
MAP_VPAGETABLE Memory accessed via this map is not linearly mapped
and will be governed by a virtual page table. The
base address of the virtual page table may be set
using mcontrol(2) with MADV_SETMAP. Virtual page
tables work with anonymous memory but there is no
way to populate the page table so for all intents
and purposes MAP_VPAGETABLE can only be used when
mapping file descriptors. Since the kernel will
update the VPTE_M bit in the virtual page table,
the mapping must R+W even though actual access to
the memory will be properly governed by the virtual
page table.
Addressable backing store is limited by the range
supported in the virtual page table entries. The
kernel may implement a page table abstraction
capable of addressing a larger range within the
backing store then could otherwise be mapped into
memory.
The close(2) function does not unmap pages, see munmap(2) for further
information.
The current design does not allow a process to specify the location of
swap space. In the future we may define an additional mapping type,
MAP_SWAP, in which the file descriptor argument specifies a file or
device to which swapping should be done.
RETURN VALUES
Upon successful completion, mmap() returns a pointer to the mapped
region. Otherwise, a value of MAP_FAILED is returned and errno is set to
indicate the error.
ERRORS
Mmap() will fail if:
[EACCES] The flag PROT_READ was specified as part of the prot
parameter and fd was not open for reading. The flags
MAP_SHARED and PROT_WRITE were specified as part of
the flags and prot parameters and fd was not open for
writing.
[EBADF] fd is not a valid open file descriptor.
[EINVAL] MAP_FIXED was specified and the addr parameter was not
page aligned, or part of the desired address space
resides out of the valid address space for a user
process.
[EINVAL] Len was negative.
[EINVAL] MAP_ANON was specified and the fd parameter was not
-1.
[EINVAL] MAP_ANON has not been specified and fd did not
reference a regular or character special file.
[EINVAL] Offset was not page-aligned.
[ENOMEM] MAP_FIXED was specified and the addr parameter wasn't
available. MAP_ANON was specified and insufficient
memory was available. The system has reached the per-
process mmap limit specified in the vm.max_proc_mmap
sysctl.
SEE ALSO
madvise(2), mincore(2), mlock(2), mprotect(2), msync(2), munlock(2),
munmap(2), getpagesize(3)
DragonFly 5.5-DEVELOPMENT January 18, 2015 DragonFly 5.5-DEVELOPMENT