NAME
mmap —
map files or devices into
memory
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#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_EXEC
- Pages may be executed.
-
-
PROT_READ
- Pages may be read.
-
-
PROT_WRITE
- Pages may be written.
-
-
PROT_NONE
- Placeholder when requesting no access permission.
As a
NetBSD extension,
PROT_MPROTECT
can be used to request additional
permissions for later use with
mprotect(
2). This is necessary for
switching pages between writeable and executable when PAX mprotect
restrictions are in place.
Note that, due to
hardware limitations, on some platforms PROT_WRITE
may
imply PROT_READ
, and PROT_READ
may imply PROT_EXEC
. Portable programs should not rely
on these flags being separately enforceable.
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.
Note that either
MAP_SHARED
or
MAP_PRIVATE
must be specified. Sharing, mapping type
and options are specified in the
flags argument by
OR'ing the following values:
-
-
MAP_ALIGNED(n)
- Request that the allocation be aligned to the given
boundary. The parameter n should be the base 2
logarithm of the desired alignment (e.g., to request alignment to 16K, use
14 as the value for n). The alignment must be equal to or greater than the
platform's page size as returned by
sysconf(3) with the
_SC_PAGESIZE
request.
-
-
MAP_ANON
- Map anonymous memory not associated with any specific file.
The file descriptor is not used for creating
MAP_ANON
regions, and must be specified as -1. The
mapped memory will be zero filled.
-
-
MAP_FILE
- Mapped from a regular file or character-special device
memory. Read accesses beyond the end of of the file or device but less
than the current page size will be zero-filled. Write accesses beyond the
end of the file or device but less than the current page size will not
affect the file or device. References beyond the end of file that are
beyond the current page size will result in the delivery of
SIGBUS
signal.
-
-
MAP_FIXED
- Do not permit the system to select a different address than
the one specified. If the specified address cannot be used,
mmap will fail. If MAP_FIXED is specified,
addr must be a multiple of the pagesize. Use of this
option is discouraged.
-
-
MAP_HASSEMAPHORE
- Notify the kernel that the region may contain semaphores
and that special handling may be necessary.
-
-
MAP_INHERIT
- Permit regions to be inherited across
execve(2) system calls.
-
-
MAP_TRYFIXED
- Attempt to use the address addr even
if it falls within the normally protected process data or text segment
memory regions. If the requested region of memory is actually present in
the memory map, a different address will be selected as if
MAP_TRYFIXED
had not been specified. If
addr is NULL, this flag is
ignored and the system will select a mapping address.
-
-
MAP_WIRED
- Lock the mapped region into memory as with
mlock(2).
-
-
MAP_PRIVATE
- Modifications made by this process are private, however
modifications made by other processes using
MAP_SHARED
will be seen.
-
-
MAP_SHARED
- Modifications are shared.
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.
If
MAP_FIXED
is not specified, the system will attempt
to place the mapping in an unused portion of the address space chosen to
minimize possible collision between mapped regions and the heap.
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. The
symbol
MAP_FAILED
is defined in the header
⟨
sys/mman.h⟩. No successful return from
mmap() will return the value
MAP_FAILED
.
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.
PAX mprotect restrictions prohibit the requested protection.
-
-
- [
EBADF
]
- fd is not a valid open file
descriptor.
-
-
- [
EINVAL
]
MAP_FIXED
was specified and the
addr parameter was not page aligned or was outside
of the valid address range for a process.
MAP_ANON was specified and
fd
was not -1.
-
-
- [
ENODEV
]
- fd did not reference a regular or
character special file.
-
-
- [
ENOMEM
]
MAP_FIXED
was specified and the
addr parameter wasn't available.
MAP_ANON
was specified and insufficient memory was
available.
-
-
- [
EOVERFLOW
]
- fd references a regular file and the
value of offset plus len would
exceed the offset maximum established in its open file description.
SEE ALSO
madvise(2),
mincore(2),
mlock(2),
mprotect(2),
msync(2),
munmap(2),
getpagesize(3),
sysconf(3)
STANDARDS
The
mmap() function conforms to
IEEE Std
1003.1b-1993 (“POSIX.1b”).
HISTORY
The
mmap() interface was first designed in
4.2BSD.