mio

An easy to use header-only cross-platform C++11 memory mapping library with an MIT license.

mio has been created with the goal to be easily includable (i.e. no dependencies) in any C++ project that needs memory mapped file IO without the need to pull in Boost.

Please feel free to open an issue, I'll try to address any concerns as best I can.

Why?

Because memory mapping is the best thing since sliced bread!

More seriously, the primary motivation for writing this library instead of using Boost.Iostreams, was the lack of support for establishing a memory mapping with an already open file handle/descriptor. This is possible with mio.

Furthermore, Boost.Iostreams' solution requires that the user pick offsets exactly at page boundaries, which is cumbersome and error prone. mio, on the other hand, manages this internally, accepting any offset and finding the nearest page boundary.

Albeit a minor nitpick, Boost.Iostreams implements memory mapped file IO with a std::shared_ptr to provide shared semantics, even if not needed, and the overhead of the heap allocation may be unnecessary and/or unwanted. In mio, there are two classes to cover the two use-cases: one that is move-only (basically a zero-cost abstraction over the system specific mmapping functions), and the other that acts just like its Boost.Iostreams counterpart, with shared semantics.

How to create a mapping

NOTE: the file must exist before creating a mapping.

There are three ways to map a file into memory:

• Using the constructor, which throws a std::system_error on failure:

mio::mmap_source mmap(path, offset, size_to_map);

or you can omit the offset and size_to_map arguments, in which case the entire file is mapped:

mio::mmap_source mmap(path);

• Using the factory function:

std::error_code error;
mio::mmap_source mmap = mio::make_mmap_source(path, offset, size_to_map, error);

or:

mio::mmap_source mmap = mio::make_mmap_source(path, error);

• Using the map member function:

std::error_code error;
mio::mmap_source mmap;
mmap.map(path, offset, size_to_map, error);

or:

mmap.map(path, error);

NOTE: The constructors require exceptions to be enabled. If you prefer to build your projects with -fno-exceptions, you can still use the other ways.

Moreover, in each case, you can provide either some string type for the file's path, or you can use an existing, valid file handle.

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <mio/mmap.hpp>
// #include <mio/mio.hpp> if using single header
#include <algorithm>

int main()
{
    // NOTE: error handling omitted for brevity.
    const int fd = open("file.txt", O_RDONLY);
    mio::mmap_source mmap(fd, 0, mio::map_entire_file);
    // ...
}

However, mio does not check whether the provided file descriptor has the same access permissions as the desired mapping, so the mapping may fail. Such errors are reported via the std::error_code out parameter that is passed to the mapping function.

WINDOWS USERS: This library does support the use of wide character types for functions where character strings are expected (e.g. path parameters).

Example

#include <mio/mmap.hpp>
// #include <mio/mio.hpp> if using single header
#include <system_error>