File::Map#

📦 std

Memory-mapped scalars: make a file look like an ordinary string.

File::Map attaches a file — or a fresh anonymous region of memory — to a Perl scalar. Reads and writes to the scalar go straight to the kernel’s mapping: the file appears in your variable as a string, and changes propagate back without you ever calling read or write. A multi-gigabyte file costs almost nothing to open this way, because pages are faulted in lazily as you touch them.

Once a scalar is mapped it behaves like a regular string for the operations that matter: substr, regex match and substitution, index, length, and slicing. Direct assignment ($map = "...") is caught and fixed up so you never corrupt the mapping, though substr is the recommended way to write. The mapping is released automatically when the scalar goes out of scope; unmap is available for explicit control.

Synopsis#

use File::Map qw(map_file map_anonymous unmap);

map_file my $map, 'data.bin', '+<';   # read/write
$map =~ s/foo/bar/g;                  # edits go to disk
substr $map, 0, 4, "HEAD";            # in-place write

map_anonymous my $buf, 4096, 'shared'; # scratch region
unmap $map;                            # optional

Choosing a mapping function#

  • map_file — give a filename and a mode, get a mapped scalar. The common case.

  • map_handle — same idea, but you already have an open filehandle.

  • map_anonymous — no file; a scratch region shared with forked children or private to the process.

  • sys_map — low-level wrapper around raw mmap(2) flags for when the convenience functions don’t fit.

Managing a live mapping#

  • sync — flush pending writes back to disk.

  • advise — hint the kernel about access patterns ("sequential", "random", "willneed", …).

  • protect — change read/write protection at runtime.

  • remap — resize an existing mapping (Linux only).

  • unmap — drop the mapping explicitly.

Functions#

Mapping#

map_file#

Open a file by name and attach it to a scalar as a memory map.

map_handle#

Attach an already-open filehandle to a scalar as a memory map.

map_anonymous#

Allocate a fresh memory region backed by no file and attach it to a scalar.

sys_map#

Low-level mapping with raw mmap(2) protection and flag constants.

remap#

Resize an existing mapping in place.

Unmapping#

unmap#

Release a mapping explicitly before the scalar goes out of scope.

Synchronisation#

sync#

Flush pending writes from a mapped scalar back to disk.

Advice#

advise#

Tell the kernel how the mapped region will be accessed.

protect#

Change the read/write/execute protection of a mapped region.