# Memory-Mapped Files

Overview
Acknowledgments
Installation
Headers
Reference

1. Class `mapped_file_params`
2. Class `mapped_file_source`
3. Class `mapped_file_sink`
4. Class `mapped_file`

## Overview

The classes `mapped_file_source`, `mapped_file_sink` and `mapped_file` provide access to memory-mapped files on Windows and POSIX systems. These Devices behave much like the File Wrappers `basic_file_source`, `basic_file_sink` and `basic_file`, with the following important differences:

- By default, files must exist before being opened, and are not truncated; attempting to write past the end of a file results in an error. To map a file which does not yet exist, use `mapped_file_params::new_file_size`.
- Files are always opened in binary mode.
- Wide-character streams are not supported.

Wide-character versions of the memory-mapped file Devices may be defined as follows, using the template `code_converter`:

        #include <boost/iostreams/code_converter.hpp>
        #include <boost/iostreams/device/mapped_file.hpp>

        typedef code_converter<mapped_file_source>  wmapped_file_source;
        typedef code_converter<mapped_file_sink>    wmapped_file_sink;

## Acknowledgments

The memory-mapped file Devices are based on the work of Craig Henderson ([Henderson]). Additionals features were implemented by Jonathan Graehl.

## Installation

The memory-mapped file Devices depend on the source file `<libs/iostreams/src/mapped_file.cpp>`. This source file makes use of Windows or POSIX headers depending on the user's operating system. For installation instructions see Installation.

## Headers

`<boost/iostreams/device/mapped_file.hpp>`

## Reference

### 1. Class `mapped_file_params`

#### Description

Class encapsulating the parameters used to open a memory-mapped file.

#### Synopsis

    namespace boost { namespace iostreams {

    struct mapped_file_params {
        explicit mapped_file_params();
        explicit mapped_file_params(const std::string& path);
        std::string              path;
        mapped_file::mapmode     flags;
        std::ios_base::openmode  mode;  // Deprecated
        stream_offset            offset;
        std::size_t              length;
        stream_offset            new_file_size;
        const char*              hint;
    };

    } } // End namespace boost::io

#### `mapped_file_params::path`

        std::string              path;

The pathname of the file to map.

#### `mapped_file_params::mode`

        std::ios_base::openmode  mode;

Indicates whether the file should be opened with read-access, write-access or both. Ignored by `mapped_file_source` and `mapped_file_sink`. This member is deprecated. Please use flags in new code instead.

#### `mapped_file_params::flags`

        mapped_file::mapmode  flags;

Indicates whether the file should be opened with read-access, read-write-access, or private access. A file opened with private access can be written to, but the changes will not affect the underlying file.

#### `mapped_file_params::offset`

        stream_offset            offset;

The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be abotained via the static member function `alignment` of `mapped_file_source`, `mapped_file_sink` or `mapped_file`. Defaults to `0`.

#### `mapped_file_params::length`

        std::size_t              length;

The number of bytes to map. If this parameter is not specified, the entire file is mapped.

#### `mapped_file_params::new_file_size`

        stream_offset            new_file_size;

If this value is non-zero it specifies the size of a file to be created. If a file with pathname path already exists, it will be overwritten.

#### `mapped_file_params::hint`

        const char*              hint;

Suggests a location in the process's address space for the mapping to begin.

### 2. Class `mapped_file_source`

#### Description

Model of Source providing read-only access to memory-mapped files on Windows and POSIX systems.

#### Synopsis

    namespace boost { namespace iostreams {

    class mapped_file_source {
    public:
        typedef char                      char_type;
        typedef [implementation-defined]  category;
        mapped_file_source();
        explicit mapped_file_source(mapped_file_params params);
        explicit mapped_file_source( const std::string& path,
                                     size_type length = max_length,
                                     boost::intmax_t offset = 0 );
        void open(mapped_file_params params);
        void open( const std::string& path,
                   size_type length = max_length,
                   boost::intmax_t offset = 0 );
        bool is_open() const;
        void close();
        size_type size() const;
        const char* data() const;
        static int alignment();
    };

    } } // End namespace boost::io

#### `mapped_file_source::mapped_file_source`

        mapped_file_source();

Constructs a `mapped_file_source` which must be opened before it can be used to perform i/o.

        explicit mapped_file_source(mapped_file_params params);

Constructs a `mapped_file_source` from the given parameters.

        explicit mapped_file_source( const std::string& path,
                                     size_type length = max_length,
                                     boost::intmax_t offset = 0 );

Constructs a `mapped_file_source` to access a specified file. The parameters have the following interpretation:

path | - | The pathname of the file to map.
length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped.
offset | - | The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function `alignment`.

#### `mapped_file_source::open`

        void open(mapped_file_params params);

Connects this `mapped_file_source` to a memory-mapped file obtained as described by the given parameters.

            void open( const std::string& path,
                       size_type length = max_length,
                       boost::intmax_t offset = 0 );

Connects this `mapped_file_source` to a memory-mapped file obtained as described by the given parameters, which have the following interpretation:

path | - | The pathname of the file to map.
length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped.
offset | - | The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function `alignment`.

#### `mapped_file_source::is_open`

        bool is_open() const;

Returns `true` if this `mapped_file_source` has been successfully opened without subsequently having been closed.

#### `mapped_file_source::close`

        void close();

Frees the mapping associated with this `mapped_file_source`.

#### `mapped_file_source::size`

        size_type size() const;

Returns the size in bytes of the mapping associated with this `mapped_file_source`.

#### `mapped_file_source::data`

        const char* data() const;

Returns a pointer to the first byte of data in the mapping associated with this `mapped_file_source`.

#### `mapped_file_source::alignment`

        static int alignment();

Returns the operating system's virtual memory allocation granularity.

### 3. Class `mapped_file_sink`

#### Description

Model of Sink providing write-only access to memory-mapped files on Windows and POSIX systems.

#### Synopsis

    namespace boost { namespace iostreams {

    class mapped_file_sink {
    public:
        typedef char                      char_type;
        typedef [implementation-defined]  category;
        enum mapmode { readwrite, priv };
        mapped_file_sink();
        explicit mapped_file_sink(mapped_file_params params);
        explicit mapped_file_sink( const std::string& path,
                                   size_type length = max_length,
                                   boost::intmax_t offset = 0,
                                   mapmode flags = readwrite );
        void open(mapped_file_params params);
        void open( const std::string& path,
                   size_type length = max_length,
                   boost::intmax_t offset = 0,
                   mapmode flags = readwrite );
        bool is_open() const;
        mapmode flags() const;
        void close();
        size_type size() const;
        char* data() const;
        static int alignment();
    };

    } } // End namespace boost::io

#### `mapped_file_sink::mapped_file_sink`

        mapped_file_sink();

Constructs a `mapped_file_sink` which must be opened before it can be used to perform i/o.

        explicit mapped_file_sink(mapped_file_params params);

Constructs a `mapped_file_sink` from the given parameters.

        explicit mapped_file_sink( const std::string& path,
                                   size_type length = max_length,
                                   boost::intmax_t offset = 0,
                                   mapmode flags );

Constructs a `mapped_file_sink` to access a specified file. The parameters have the following interpretation:

path | - | The pathname of the file to map.
length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped.
offset | - | The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function `alignment`.
flags | - | Indicates whether the `mapped_file_sink` should be opened for read-write access or private access.

#### `mapped_file_sink::open`

        void open(mapped_file_params params);

Connects this `mapped_file_sink` to a memory-mapped file obtained as described by the given parameters.

            void open( const std::string& path,
                       size_type length = max_length,
                       boost::intmax_t offset = 0
                       mapmode flags );

Connects this `mapped_file_sink` to a memory-mapped file obtained as described by the given parameters, which have the following interpretation:

path | - | The pathname of the file to map.
length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped.
offset | - | The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function `alignment`.
flags | - | Indicates whether the `mapped_file_sink` should be opened for read-write access or private access.

#### `mapped_file_sink::is_open`

        bool is_open() const;

Returns `true` if this `mapped_file_sink` has been successfully opened without subsequently having been closed.

#### `mapped_file_sink::flags`

        mapmode flags() const;

Indicates whether the `mapped_file_sink` was opened for read/write-access or private-access.

#### `mapped_file_sink::close`

        void close();

Frees the mapping associated with this `mapped_file_sink`.

#### `mapped_file_sink::size`

        size_type size() const;

Returns the size in bytes of the mapping associated with this `mapped_file_sink`.

#### `mapped_file_sink::data`

        char* data() const;

Returns a pointer to the first byte of data in the mapping associated with this `mapped_file_sink`.

#### `mapped_file_sink::alignment`

        static int alignment();

Returns the operating system's virtual memory allocation granularity.

### 4. Class `mapped_file`

#### Description

Model of SeekableDevice providing read-write access to memory-mapped files on Windows and POSIX systems.

#### Synopsis

    namespace boost { namespace iostreams {

    class mapped_file {
    public:
        typedef char                      char_type;
        typedef [implementation-defined]  category;
        enum mapmode { readonly, readwrite, priv };
        mapped_file();
        explicit mapped_file(mapped_file_params params);
        explicit mapped_file( const std::string& path,
                              std::ios_base::openmode mode =
                                  std::ios_base::in | std::ios_base::out,
                              size_type length = max_length,
                              boost::intmax_t offset = 0 );
        explicit mapped_file( const std::string& path,
                              mapmode mode,
                              size_type length = max_length,
                              boost::intmax_t offset = 0 );
        void open(mapped_file_params params);
        void open( const std::string& path,
                   std::ios_base::openmode mode =
                       std::ios_base | std::ios_base,
                   size_type length = max_length,
                   boost::intmax_t offset = 0 );
        void open( const std::string& path,
                   mapmode mode,
                   size_type length = max_length,
                   boost::intmax_t offset = 0 );
        bool is_open() const;
        mapmode flags() const;
        void close();
        size_type size() const;
        char* data() const;
        const char* const_data() const;
        static int alignment();
    };

    } } // End namespace boost::iostreams

#### `mapped_file::mapped_file`

        mapped_file();

Constructs a `mapped_file` which must be opened before it can be used to perform i/o.

        explicit mapped_file(mapped_file_params params);

Constructs a `mapped_file` from the given parameters.

        explicit mapped_file( const std::string& path,
                              std::ios_base::openmode mode =
                                  std::ios_base | std::ios_base,
                              size_type length = max_length,
                              boost::intmax_t offset = 0 );

Constructs a `mapped_file` to access a specified file. The parameters have the following interpretation:

path | - | The pathname of the file to map.
mode | - | Indicates whether the file should be opened with read-access, write-access or both. Use of `std::ios_base::openmode` with `mapped_file` is deprecated. Please use `mapmode` instead in new code.
length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped.
offset | - | The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function `alignment`.

        explicit mapped_file( const std::string& path,
                              mapmode mode,
                              size_type length = max_length,
                              boost::intmax_t offset = 0 );

Constructs a `mapped_file` to access a specified file. The parameters have the following interpretation:

path | - | The pathname of the file to map.
mode | - | Indicates whether the file should be opened with read-access, read/write-access or private-access.
length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped.
offset | - | The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function `alignment`.

#### `mapped_file::open`

        void open(mapped_file_params params);

Connects this `mapped_file` to a memory-mapped file obtained as described by the given parameters.

            void open( const std::string& path,
                       std::ios_base::openmode mode =
                           std::ios_base | std::ios_base,
                       size_type length = max_length,
                       boost::intmax_t offset = 0 );

Connects this `mapped_file` to a memory-mapped file obtained as described by the given parameters, which have the following interpretation:

path | - | The pathname of the file to map.
mode | - | Indicates whether the file should be opened with read-access, write-access or both. Use of `std::ios_base::openmode` with `mapped_file` is deprecated. Please use `mapmode` in new code.
length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped.
offset | - | The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function `alignment`.

            void open( const std::string& path,
                       mapmode mode,
                       size_type length = max_length,
                       boost::intmax_t offset = 0 );

Connects this `mapped_file` to a memory-mapped file obtained as described by the given parameters, which have the following interpretation:

path | - | The pathname of the file to map.
mode | - | Indicates whether the file should be opened with read-access, read/write-access or private access.
length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped.
offset | - | The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function `alignment`.

#### `mapped_file::is_open`

        bool is_open() const;

Returns `true` if this `mapped_file` has been successfully opened without subsequently having been closed.

#### `mapped_file::flags`

        mapmode flags() const;

Indicates whether the `mapped_file` was opened for read-access, read/write-access or private-access.

#### `mapped_file::close`

        void close();

Frees the mapping associated with this `mapped_file`.

#### `mapped_file::size`

        size_type size() const;

Returns the size in bytes of the mapping associated with this `mapped_file`.

#### `mapped_file::data`

        char* data() const;

Returns a pointer to the first byte of data in the mapping associated with this `mapped_file`, if it was opened with write-access, and a null pointer otherwise.

#### `mapped_file::const_data`

        const char* const_data() const;

Returns a pointer to the first byte of data in the mapping associated with this `mapped_file`.

#### `mapped_file::alignment`

        static int alignment();

Returns the operating system's virtual memory allocation granularity.

Revised 02 Feb 2008

© Copyright 2008 CodeRage, LLC
© Copyright 2004-2007 Jonathan Turkanis

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)