--- name: "mmap" section: "2" platform: "macos" package: "xnu" version: "12377.121.6" release: "macOS 26.5" platforms: ["linux", "freebsd", "macos"] url: "https://new.carta.tech/mmap" --- # mmap(2) allocate memory, or map files or devices into memory ## NAME **mmap** – allocate memory, or map files or devices into memory ## LIBRARY Standard C Library (libc, -lc) ## SYNOPSIS **#include \** *void* *\**\ **mmap**(*void \*addr*, *size\_t len*, *int prot*, *int flags*, *int fd*, *off\_t offset*); ## DESCRIPTION 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)](/malloc/3.md) 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 Pages may not be accessed. - PROT\_READ Pages may be read. - PROT\_WRITE Pages may be written. - PROT\_EXEC Pages may be executed. 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 Synonym for MAP\_ANON. - MAP\_ANON Map zero-filled anonymous memory not associated with any specific file. The *offset* argument is ignored. Mac OS X specific: the *fd* used for creating 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 Mapped from a regular file. (This is the default mapping type, and need not be specified.) - 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. 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 Notify the kernel that the region may contain semaphores and that special handling may be necessary. - MAP\_PRIVATE Modifications are private (copy-on-write). - MAP\_SHARED Modifications are shared. - MAP\_NOCACHE Pages in this mapping are not retained in the kernel's memory cache. If the system runs low on memory, pages in MAP\_NOCACHE mappings will be among the first to be reclaimed. This flag is intended for mappings that have little locality and provides a hint to the kernel that pages in this mapping are unlikely to be needed again in the near future. - MAP\_JIT Allow mapping pages both 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 Directs **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)](/close/2.md) system call does not unmap pages, see [munmap(2)](/munmap/2.md) 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 The **mmap**() system call will fail if: - \[EACCES\] The flag 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\] The *fd* argument is not a valid open file descriptor. - \[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\] *flags* does not include either MAP\_PRIVATE or MAP\_SHARED. - \[EINVAL\] *flags* includes bits that are not part of any valid flags value. - \[EINVAL\] The *len* argument was negative or zero. Historically, the system call would not return an error if the argument was zero. See other potential additional restrictions in the COMPATIBILITY section below. - \[EINVAL\] The *offset* argument was not page-aligned based on the page size as returned by [getpagesize(3)](/getpagesize/3.md). - \[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\] Addresses in the specified range are invalid for *fd*. - \[EOVERFLOW\] Addresses in the specified range exceed the maximum offset set for *fd*. ## ENTITLEMENTS The following entitlements only have an effect when the hardened runtime is enabled. - com.apple.security.cs.allow-jit A Boolean value that indicates whether the app may create writable and executable memory using the MAP\_JIT *flag*. - com.apple.security.cs.allow-unsigned-executable-memory A Boolean value that indicates whether the app may create writable and executable memory without the restrictions imposed by using the MAP\_JIT *flag*. - com.apple.security.cs.disable-executable-page-protection A Boolean value that indicates whether to disable all code signing protections while launching an application, and during its execution. ## LEGACY SYNOPSIS **#include \** **#include \** The include file ⟨sys/types.h⟩ is necessary. ## COMPATIBILITY **mmap**() now returns with *errno* set to EINVAL in places that historically succeeded. The rules have changed as follows: - The *flags* parameter must specify either MAP\_PRIVATE or MAP\_SHARED. - The *len* parameter must not be 0. - The *off* parameter must be a multiple of pagesize, as returned by **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. ## SEE ALSO [madvise(2)](/madvise/2.md), [mincore(2)](/mincore/2.md), [minherit(2)](/minherit/2.md), [mlock(2)](/mlock/2.md), [mprotect(2)](/mprotect/2.md), [msync(2)](/msync/2.md), [munlock(2)](/munlock/2.md), [munmap(2)](/munmap/2.md), [shmat(2)](/shmat/2.md), [getpagesize(3)](/getpagesize/3.md) ### Apple Developer Documentation https://developer.apple.com/documentation/security/hardened\_runtime\_entitlements