-type open_extra_info() :: #{exist => boolean(), size => non_neg_integer()}.

Extra information returned by the call to emmap:open/2,3. The value of exist true means that an existing memory map was open. The size represents the size of the memory map that was open.

-type open_option() ::
          anon | auto_unlink | create | debug | direct | fixed | hugetlb | huge_2mb | huge_1gb | lock |
          nocache | nolock | nonblock | noreserve | populate | private | read | shared |
          shared_validate | sync | truncate | uninitialized | write | fixed_size |
          {address, pos_integer()} |
          {chmod, pos_integer()} |
          {size, pos_integer()} |
          {max_inc_size, pos_integer()}.

Options for opening a memory mapped file:

anon

Anonymous mapping. The mapping is not backed by any file; its contents are initialized to zero. The offset argument should be zero.

auto_unlink

Automatically delete the mapped file after the mapped data was garbage collected. This can be used when the mapped file is a file-based shared-memory area (e.g. /dev/shm/...) and is mapped in direct mode to free the memory after the data was gc'd

create

Allow to create mmap file if it doesn't exist.

debug

Turn on debug printing in the NIF library.

fit

When fit is set, and opening a file with the current file size greater than requested, the memory map will be set to the requested length.

direct

Read/pread operations do not copy memory, but rather use "resource binaries" that can change content if the underlying data is changed. This is the most performant, but also has other thread-safety implications when not using atomic operations.

fixed

Don't interpret addr as a hint: place the mapping at exactly that address. The implementation aligns the given address to a multiple of the page size.

lock

Use a semaphore (read/write lock) to control state changes internally in the NIF library. This is the default option.

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. NOTE: this option is only valid for Mac OS.

nolock

Don't use a semaphore (read/write lock) to control state changes internally in the NIF library

nonblock

Don't perform read-ahead: create page tables entries only for pages that are already present in RAM. Since Linux 2.6.23, this flag causes populate to do nothing.

noreserve

Do not reserve swap space for this mapping. When swap space is reserved, one has the guarantee that it is possible to modify the mapping.

populate

Populate (prefault) page tables for a mapping. For a file mapping, this causes read-ahead on the file. This will help to reduce blocking on page faults later.

private

Create a private copy-on-write mapping. Updates to the mapping are not visible to other OS or Erlang processes mapping the same file, and are not carried through to the underlying file.

hugetlb

Allocate the mapping using "huge" pages.

huge_2mb

Used in conjunction with hugetlb to select alternative hugetlb page size of 2MB

huge_1gb

Used in conjunction with hugetlb to select alternative hugetlb page size of 1GB

read

Open for reading (this is default).

shared

Share this mapping. Updates to the mapping are visible to other OS or Erlang processes mapping the same region, and (in the case of file-backed mappings) are carried through to the underlying file. May be used in combination with sync to precisely control when updates are carried through to the underlying file.

shared_validate

This flag provides the same behavior as shared except that shared mappings ignore unknown flags in flags. By contrast, when creating a mapping using shared_validate, the kernel verifies all passed flags are known and fails the mapping with the error eopnotsupp for unknown flags. This mapping type is also required to be able to use some mapping flags (e.g., sync)

sync

This flag is available only with the shared_validate mapping type; mappings of type shared will silently ignore this flag. This flag is supported only for files supporting DAX (direct mapping of persistent memory). For other files, creating a mapping with this flag results in an eopnotsupp error. Shared file mappings with this flag provide the guarantee that while some memory is mapped writable in the address space of the OS process, it will be visible in the same file at the same offset even after the system crashes or is rebooted. In conjunction with the use of appropriate CPU instructions, this provides users of such mappings with a more efficient way of making data modifications persistent.

truncate

Truncate existing mmap file after it's open.

uninitialized

Don't clear anonymous pages. This flag is intended to improve performance on embedded devices. This flag is honored only if the kernel was configured with the CONFIG_MMAP_ALLOW_UNINITIALIZED option.

write

Open memory map for writing.

fixed_size

Don't allow the memory to be resized

{address, pos_integer()}

Open mapping at the given memory address (sets MAP_FIXED on the memory mapped file)

{chmod, pos_integer()}

Create mmap file with this mode (default: 0600)

{size, pos_integer()}

Create/access memory map on this size.

{max_inc_size, pos_integer()}

Size threshold used when automatically resizing shared memory with call to resize/1. Below this threshold the memory will double, and after this threshold, the resized memory will be increased by max_inc_size.