Skip to content

Instantly share code, notes, and snippets.

@johnjcamilleri
Last active October 18, 2021 11:40
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save johnjcamilleri/1cdc73d25420302035fb40df1aac2d75 to your computer and use it in GitHub Desktop.
Save johnjcamilleri/1cdc73d25420302035fb40df1aac2d75 to your computer and use it in GitHub Desktop.
macOS man pages
MMAP(2) BSD 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/mman.h>
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 allo-
cated 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 map-
pings 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 anonymous memory not associated with any specific file. The offset argument is ignored. Mac OS X specific: the file descriptor 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 is runtime 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) 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.
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).
[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 <sys/types.h>
#include <sys/mman.h>
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:
o The flags parameter must specify either MAP_PRIVATE or MAP_SHARED.
o The len parameter must not be 0.
o 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 pos-
sessing the com.apple.security.cs.allow-jit entitlement.
SEE ALSO
madvise(2), mincore(2), minherit(2), mlock(2), mprotect(2), msync(2), munlock(2), munmap(2), shmat(2), getpagesize(3)
Apple Developer Documentation
https://developer.apple.com/documentation/security/hardened_runtime_entitlements
BSD February 14, 2020 BSD
MSYNC(2) BSD System Calls Manual MSYNC(2)
NAME
msync -- synchronize a mapped region
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/mman.h>
int
msync(void *addr, size_t len, int flags);
DESCRIPTION
The msync() system call writes modified whole pages back to the filesystem and updates the file modification time. Only those pages containing addr and len-1 succeeding locations will be exam-
ined.
The flags argument may be specified as follows:
MS_ASYNC Return immediately
MS_SYNC Perform synchronous writes
MS_INVALIDATE Invalidate all cached data
The MS_ASYNC flag is not permitted to be combined with other flags.
RETURN VALUES
If any errors occur, -1 is returned and errno is set to indicate the error. Otherwise, a 0 value is returned.
ERRORS
msync() will fail if:
[EBUSY] Some of the specified addresses are locked and MS_INVALIDATE is specified.
[EINVAL] addr is not a multiple of the hardware page size.
[EINVAL] len is too large, or less than 1.
[EINVAL] flags is invalid (e.g., it combines MS_ASYNC with another flag, which is not permitted).
[EIO] An I/O error occurs while writing to the file system.
[ENOMEM] The specified address range is outside of the address range of the process or includes an unmapped page.
LEGACY SYNOPSIS
#include <sys/types.h>
#include <sys/mman.h>
The include file <sys/types.h> is necessary.
SEE ALSO
madvise(2), mincore(2), mprotect(2), munmap(2), compat(5)
HISTORY
The msync() function first appeared in 4.4BSD.
BSD June 21, 1994 BSD
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment