Memory-mapped file I/O for Erlang.

This module provides cross-platform memory-mapped file access compatible with Linux, macOS, FreeBSD, and OpenBSD.

Memory-mapped files allow applications to access file data as if it were in memory, enabling efficient random access patterns and shared memory between processes.

Quick Start

   %% Create and write to a memory-mapped file
   {ok, H} = iommap:open("/tmp/test.dat", read_write, [create, {size, 4096}]),
   ok = iommap:pwrite(H, 0, <<"Hello, iommap!">>),
   {ok, <<"Hello, iommap!">>} = iommap:pread(H, 0, 14),
   ok = iommap:sync(H),
   ok = iommap:close(H).

Access Modes

• read - Read-only access to the file
• write - Write-only access to the file
• read_write - Full read and write access (default)

Mapping Options

• shared - Changes are visible to other processes (default)
• private - Copy-on-write; changes are private
• lock - Lock pages in memory (mlock)
• populate - Prefault pages on mapping (Linux only)
• nocache - Disable page caching (macOS only)
• create - Create file if it doesn't exist
• truncate - Truncate existing file
• {size, N} - Initial size for new files

Thread Safety

All operations are thread-safe. The NIF uses pthread read-write locks to allow multiple concurrent reads while writes are exclusive.

Error Handling

Operations return {error, Reason} on failure. Common reasons:

• badarg - Invalid arguments
• enomem - Out of memory
• enoent - File not found
• eacces - Permission denied
• closed - Handle already closed
• out_of_bounds - Offset/length exceeds file size
• sigbus - Memory access fault (file truncated externally)

Zero-Copy Region Binaries

region_binary/3 returns a refcounted binary that points directly into the mapped region with no data copy. The underlying mapping is kept alive (its munmap is deferred) for as long as any such binary, or any sub-binary derived from it, is reachable.

Lifetime model: the NIF uses two resources internally. The handle holds one reference to the mapping; close/1 releases that reference but does not call munmap if region binaries are still outstanding. The mapping is unmapped only when the last reference (handle ref + outstanding region binaries) is dropped.

Truncation hazard: region_binary/3 is unsafe to use against files that may be truncated by external processes (or by iommap:truncate/2 shrinking past the binary's range) while a returned binary is reachable. Reads of unmapped pages happen outside any NIF call and can crash the BEAM with SIGBUS. Callers needing safety against external mutation must use pread/3 (which copies and is unaffected).