mmap —
map files
or devices into memory
#include
<sys/mman.h>
void *
mmap(
void
*addr,
size_t
len,
int
prot,
int
flags,
int
fd,
off_t
offset);
The
mmap() function causes the contents of
fd, starting at
offset, to be mapped in memory at the given
addr. The mapping will extend at least
len bytes, subject to page alignment
restrictions.
The
addr argument describes the address where
the system should place the mapping. If the
MAP_FIXED flag is specified, the allocation
will happen at the specified address, replacing any previously established
mappings in its range. Otherwise, the mapping will be placed at the available
spot at
addr; failing that it will be placed
"close by". If
addr is
NULL the system can pick any address.
Except for
MAP_FIXED mappings, the system
will never replace existing mappings.
The
len argument describes the minimum amount
of bytes the mapping will span. Since
mmap() maps
pages into memory,
len may be rounded up to
hit a page boundary. If
len is 0, the mapping
will fail with
EINVAL.
If an
fd and
offset are specified, the resulting address
may end up not on a page boundary, in order to align the page offset in the
addr to the page offset in
offset.
The protections (region accessibility) are specified in the
prot argument. It should either be
PROT_NONE (no permissions) or the bitwise
OR of one or more of the following values:
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. Exactly one of the first two values must be specified:
Any combination of the following flags may additionally be used:
-
-
MAP_ANON- Map anonymous memory not associated with any specific file.
The file descriptor used for creating
MAP_ANON must currently be -1
indicating no name is associated with the region.
-
-
MAP_ANONYMOUS- Synonym for
MAP_ANON.
-
-
MAP_FIXED- Demand that the mapping is placed at
addr, rather than having the system
select a location. addr,
len and
offset (in the case of
fd mappings) must be multiples of the
page size. Existing mappings in the address range will be replaced. Use of
this option is discouraged.
-
-
MAP_STACK- Indicate that the mapping is used as a stack. This flag
must be used in combination with
MAP_ANON and
MAP_PRIVATE.
Finally, the following flags are also provided for source compatibility with
code written for other operating systems, but are not recommended for use in
new
OpenBSD code:
-
-
MAP_COPY- Modifications are private and, unlike
MAP_PRIVATE, modifications made by
others are not visible. On OpenBSD this behaves
just like MAP_PRIVATE.
-
-
MAP_FILE- Mapped from a regular file, character special file, or
block special file specified by file descriptor
fd. On OpenBSD
and all systems conforming to IEEE Std
1003.1-2008 (“POSIX.1”) this is the default mapping
type and need not be specified.
-
-
MAP_HASSEMAPHORE- Notify the kernel that the region may contain semaphores
and that special handling may be necessary. On
OpenBSD this flag is ignored.
-
-
MAP_INHERIT- Permit regions to be inherited across
exec(3) system calls. On
OpenBSD this flag is ignored.
-
-
MAP_TRYFIXED- Attempt to use the hint provided by
addr. On OpenBSD
this is the default behavior.
The
close(2) function does not
unmap pages; see
munmap(2) for
further information.
The
mmap() function returns a pointer to the mapped
region if successful; otherwise the value
MAP_FAILED is returned and the global
variable
errno is set to indicate the error.
A successful return from
mmap() will never return
the value
MAP_FAILED.
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_PRIVATE
and MAP_SHARED were both
specified.-
-
- [
EINVAL]
MAP_FIXED
was specified and the addr parameter was
not page aligned.-
-
- [
EINVAL]
- addr and
len specified a region that would extend
beyond the end of the address space.
-
-
- [
EINVAL]
- fd did not specify a
regular, character special, or block special file.
-
-
- [
EINVAL]
- fd specified a character
special or block special file and the underlying device does not support
memory mapping.
-
-
- [
EINVAL]
- The allocation len was
0.
-
-
- [
ENOMEM]
MAP_FIXED
was specified and the addr parameter
wasn't available. MAP_ANON was
specified and insufficient memory was available.-
-
- [
ENOTSUP]
- The accesses requested in the
prot argument are not allowed. In
particular,
PROT_WRITE |
PROT_EXEC
mappings are not permitted in most binaries (see
kern.wxabort in
sysctl(2) for more
information).
madvise(2),
mincore(2),
mlock(2),
mprotect(2),
mquery(2),
msync(2),
munmap(2),
getpagesize(3)
The
mmap() function conforms to
IEEE Std 1003.1-2008
(“POSIX.1”).
The
mmap() system call first appeared in
4.1cBSD.
IEEE Std 1003.1-2008
(“POSIX.1”) specifies that references to pages beyond the
end of a mapped object shall generate a
SIGBUS signal; however, on some
architectures
OpenBSD generates a
SIGSEGV signal in this case instead.
Additionally,
IEEE Std 1003.1-2008
(“POSIX.1”) specifies that
mmap() shall fail with
EINVAL if neither
MAP_PRIVATE nor
MAP_SHARED is specified by
flags; however, for compatibility with old
programs,
OpenBSD instead defaults to
MAP_SHARED for mappings of character
special files, and to
MAP_PRIVATE for all
other mappings. New programs should not rely on this behavior.
Due to a limitation of the current vm system (see
uvm(9)), mapping descriptors
PROT_WRITE without also specifying
PROT_READ is useless (results in a
segmentation fault when first accessing the mapping). This means that such
descriptors must be opened with
O_RDWR,
which requires both read and write permissions on the underlying object.
![[OpenBSD]](/openbsd.gif){kind=small}