MMAP(2) | System Calls Manual | MMAP(2) |
mmap
— allocate
memory, or map files or devices into memory
Standard C Library (libc, -lc)
#include
<sys/mman.h>
void *
mmap
(void
*addr, size_t len,
int prot,
int flags,
int fd,
off_t offset);
The
mmap
()
system call 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 offset or
len is not a multiple of the pagesize, the mapped
region may extend past the specified range. Any extension beyond the end of
the mapped object will be zero-filled.
The addr argument is used by the system to
determine the starting address of the mapping, and its interpretation is
dependent on the setting of the MAP_FIXED flag. If MAP_FIXED is specified in
flags, the system will try to place the mapping at the
specified address, possibly removing a mapping that already exists at that
location. If MAP_FIXED is not specified, then the system will attempt to use
the range of addresses starting at addr if they do not
overlap any existing mappings, including memory allocated by
malloc(3) and other such allocators.
Otherwise, the system will choose an alternate address for the mapping
(using an implementation dependent algorithm) that does not overlap any
existing mappings. In other words, without MAP_FIXED
the system will attempt to find an empty location in the address space if
the specified address range has already been mapped by something else. If
addr is zero and MAP_FIXED is not specified, then an
address will be selected by the system so as not to overlap any existing
mappings in the address space. In all cases, the actual starting address of
the region is returned. If MAP_FIXED is specified, a successful
mmap deletes any previous mapping in the allocated
address range. Previous mappings are never deleted if MAP_FIXED is not
specified.
The protections (region accessibility) are specified in the prot argument by or'ing the following values:
PROT_NONE
PROT_READ
PROT_WRITE
PROT_EXEC
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.
When the hardened runtime is enabled (See the links in the
SEE ALSO section), the protections cannot
be both PROT_WRITE
and
PROT_EXEC
without also having the flag
MAP_JIT
and the process possessing the
com.apple.security.cs.allow-jit
entitlement
The flags argument 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 (copy-on-write) 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_ANONYMOUS
MAP_ANON.
MAP_ANON
MAP_ANON
regions
can be used to pass some Mach VM flags, and can be specified as -1 if no
such flags are associated with the region. Mach VM flags are defined in
<mach/vm_statistics.h>
and
the ones that currently apply to mmap
are:
VM_FLAGS_PURGABLE to create Mach purgable (i.e. volatile) memory.
VM_MAKE_TAG(tag) to associate an 8-bit tag with the region.
<mach/vm_statistics.h>
defines some preset tags (with a VM_MEMORY_ prefix). Users are
encouraged to use tags between 240 and 255. Tags are used by tools such
as vmmap(1) to help identify
specific memory regions.
MAP_FILE
MAP_FIXED
mmap
()
will fail. If MAP_FIXED
is specified,
addr must be a multiple of the pagesize. If a
MAP_FIXED
request is successful, the mapping
established by mmap
() replaces any previous
mappings for the process' pages in the range from
addr to addr +
len. Use of this option is discouraged.MAP_HASSEMAPHORE
MAP_PRIVATE
MAP_SHARED
MAP_NOCACHE
MAP_JIT
PROT_WRITE
and
PROT_EXEC
when the hardened runtime is enabled.
Without this flag an attempt to create a mapping with both
PROT_WRITE
and PROT_EXEC
set will fail with MAP_FAILED
on macOS. A
writable, but not executable mapping is returned on iOS, watchOS and tvOS.
Usage of this flag requires the caller to have the
com.apple.security.cs.allow-jit
entitlement on
macOS.
MAP_32BIT
mmap
()
to place the mapping into the first 4 Gigabytes of the process's address
space. If there is no free virtual address space in this range,
mmap
() will return
MAP_FAILED.
Note that in order for this flag to yield addresses below 4GiB, the program's PAGEZERO must be reduced in size, since the default PAGEZERO size for 64-bit programs is at least 4GiB.
Conforming applications must specify either MAP_PRIVATE or MAP_SHARED.
The close(2) system call 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.
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 mmap
() system call will fail if:
EACCES
]PROT_READ
was specified as part of the
prot argument and fd was not
open for reading. The flags MAP_SHARED
and
PROT_WRITE
were specified as part of the
flags and prot argument and
fd was not open for writing.EBADF
]EINVAL
]MAP_FIXED
was specified and the addr argument was not page
aligned, or part of the desired address space resides out of the valid
address space for a user process.EINVAL
]EINVAL
]EINVAL
]EINVAL
]ENODEV
]MAP_ANON
has not been specified and the file fd refers to
does not support mapping.ENOMEM
]MAP_FIXED
was specified and the addr argument was not
available. MAP_FIXED
was specified and the address
range specified exceeds the address space limit for the process.
MAP_ANON
was specified and insufficient memory was
available.ENXIO
]EOVERFLOW
]The following entitlements only have an effect when the hardened runtime is enabled.
com.apple.security.cs.allow-jit
MAP_JIT
flag.com.apple.security.cs.allow-unsigned-executable-memory
MAP_JIT
flag.com.apple.security.cs.disable-executable-page-protection
#include
<sys/types.h>
#include
<sys/mman.h>
The include file
<sys/types.h>
is
necessary.
mmap
() now returns with
errno set to EINVAL in places that historically
succeeded. The rules have changed as follows:
sysconf
().On macOS 10.14 Mojave the hardened runtime restricts pages from
having both the PROT_WRITE
and
PROT_EXEC
protections without the caller also
setting the MAP_JIT
flag and
possessing the com.apple.security.cs.allow-jit
entitlement.
madvise(2), mincore(2), minherit(2), mlock(2), mprotect(2), msync(2), munlock(2), munmap(2), shmat(2), getpagesize(3)
https://developer.apple.com/documentation/security/hardened_runtime_entitlements
February 14, 2020 | macOS 14.6 |