iommap

Memory-mapped file I/O NIF for Erlang.

Overview

iommap provides cross-platform memory-mapped file access for Erlang/OTP. 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.

Features:

• Cross-platform: Linux, macOS, FreeBSD, OpenBSD
• Thread-safe with pthread read-write locks
• SIGBUS protection for safe memory access
• Positional read/write operations
• Memory advice (madvise) hints
• File resize with automatic remapping

Installation

Using Hex

Add to your rebar.config:

{deps, [
    {iommap, "1.0.0"}
]}.

From GitHub

{deps, [
    {iommap, {git, "https://github.com/benoitc/erlang-iommap.git", {tag, "1.0.0"}}}
]}.

Quick Start

%% Create a new memory-mapped file
{ok, H} = iommap:open("/tmp/test.dat", read_write, [create, {size, 4096}]).

%% Write data at offset 0
ok = iommap:pwrite(H, 0, <<"Hello, iommap!">>).

%% Read data back
{ok, <<"Hello, iommap!">>} = iommap:pread(H, 0, 14).

%% Sync changes to disk
ok = iommap:sync(H).

%% Close the mapping
ok = iommap:close(H).

API Reference

Opening and Closing

%% Open with default read_write mode
{ok, Handle} = iommap:open(Path, Options).

%% Open with explicit mode
{ok, Handle} = iommap:open(Path, Mode, Options).

%% Close handle
ok = iommap:close(Handle).

Modes: read, write, read_write

Options:

Reading and Writing

%% Read Length bytes at Offset
{ok, Binary} = iommap:pread(Handle, Offset, Length).

%% Write Data at Offset
ok = iommap:pwrite(Handle, Offset, Data).

Synchronization

%% Sync to disk (blocking)
ok = iommap:sync(Handle).

%% Sync with mode: sync (blocking) or async (non-blocking)
ok = iommap:sync(Handle, async).

File Operations

%% Resize file and remap
ok = iommap:truncate(Handle, NewSize).

%% Get current mapped size
{ok, Size} = iommap:position(Handle).

%% Provide access pattern hints
ok = iommap:advise(Handle, Offset, Length, Hint).

Hints: normal, random, sequential, willneed, dontneed

Documentation

• Features & API Reference
• Changelog
• HexDocs

Generate docs locally:

rebar3 ex_doc

Building

# Compile
rebar3 compile

# Run tests
rebar3 eunit

# Type checking
rebar3 dialyzer

# Generate documentation
rebar3 ex_doc

Platform Support

Support

Support, design and discussions are done via the GitHub Tracker.

Professional support is available via Enki Multimedia. Contact sales@enki-multimedia.eu.

License

MIT - See LICENSE for details.

Copyright (c) 2026 Benoit Chesneau