If you spot a problem with this page, click here to create a Bugzilla issue.

Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

std.mmfile

Read and write memory mapped files.

Memory mapped files are a mechanism in operating systems that allows file access through virtual memory. After opening a file with MmFile, the contents can be read from or written to with standard slice / pointer operations. Changes to the memory are automatically reflected in the underlying file.

Memory mapping can increase I/O performance of large files, compared to buffered read / write operations from std.file and std.stdio. However, I/O errors are not handled as safely: when for example the disk that the file is on gets removed, reading from it may result in a segfault.

License:

Boost License 1.0.

Authors:

Walter Bright, Matthew Wilson

References https://en.wikipedia.org/wiki/Memory-mapped_file

Source std/mmfile.d

class MmFile;

MmFile objects control the memory mapped file resource.

Examples:

Read an existing file

import std.file;
std.file.write(deleteme, "hello"); // deleteme is a temporary filename
scope(exit) remove(deleteme);

// Use a scope class so the file will be closed at the end of this function
scope mmfile = new MmFile(deleteme);

writeln(mmfile.length); // "hello".length

// Access file contents with the slice operator
// This is typed as `void[]`, so cast to `char[]` or `ubyte[]` to use it
const data = cast(const(char)[]) mmfile[];

// At this point, the file content may not have been read yet.
// In that case, the following memory access will intentionally
// trigger a page fault, causing the kernel to load the file contents
writeln(data[0 .. 5]); // "hello"

Examples:

Write a new file

import std.file;
scope(exit) remove(deleteme);

scope mmfile = new MmFile(deleteme, MmFile.Mode.readWriteNew, 5, null);
writeln(mmfile.length); // 5

auto data = cast(ubyte[]) mmfile[];

// This write to memory will be reflected in the file contents
data[] = '\n';

mmfile.flush();

writeln(std.file.read(deleteme)); // "\n\n\n\n\n"

enum Mode: int;

The mode the memory mapped file is opened with.

read: Read existing file
readWriteNew: Delete existing file, write new file
readWrite: Read/Write existing file, create if not existing
readCopyOnWrite: Read/Write existing file, copy on write

scope this(string filename);

Open memory mapped file filename for reading. File is closed when the object instance is deleted.

Throws:

On POSIX, std.exception.ErrnoException.
On Windows, std.windows.syserror.WindowsException.

scope this(string filename, Mode mode, ulong size, void* address, size_t window = 0);

Open memory mapped file filename in mode. File is closed when the object instance is deleted.

Parameters:

string `filename`	name of the file. If null, an anonymous file mapping is created.
Mode `mode`	access mode defined above.
ulong `size`	the size of the file. If 0, it is taken to be the size of the existing file.
void* `address`	the preferred address to map the file to, although the system is not required to honor it. If null, the system selects the most convenient address.
size_t `window`	preferred block size of the amount of data to map at one time with 0 meaning map the entire file. The window size must be a multiple of the memory allocation page size.

Throws:

On POSIX, std.exception.ErrnoException.
On Windows, std.windows.syserror.WindowsException.

const @property ulong length();

Gives size in bytes of the memory mapped file.

alias opDollar = length;

Forwards length.

Mode mode();

Read-only property returning the file mode.

void[] opSlice();

Returns entire file contents as an array.

void[] opSlice(ulong i1, ulong i2);

Returns slice of file contents as an array.

ubyte opIndex(ulong i);

Returns byte at index i in file.

ubyte opIndexAssign(ubyte value, ulong i);

Sets and returns byte at index i in file to value.

Library Reference

std.mmfile