Memory-mapped files stream
Provide read-write access to memory-mapped files on Windows and POSIX systems.
 All Classes Functions
filemappingbuf Class Reference

File mapping stream buffer. More...

#include <fmstream.h>

Inheritance diagram for filemappingbuf:

Public Member Functions

 filemappingbuf ()
 Construct object.
 
virtual ~filemappingbuf ()
 Destructs the filemappingbuf object.
 
bool is_open () const
 Check if a file is open.
 
filemappingbufopen (const char *path_name, std::ios_base::openmode mode, std::streamsize max_length=0, std::streamoff offset=0)
 Open file.
 
filemappingbufclose ()
 Close file.
 
void * pubseekptr (void *ptr, std::ios_base::openmode which=std::ios_base::in|std::ios_base::out)
 Set internal position pointer to absolute position.
 
const void * data () const
 Get the read-only base address of the mapping.
 
void * data ()
 Get the base address of the mapping.
 
std::streamsize size () const
 Get the maximum byte length of the mapping.
 
C++11

The following methods requires some features introduced by the latest revision of the C++ standard (2011).

Older compilers may not support it.

 filemappingbuf (filemappingbuf &&rhs_buf)
 Move constructor (requires C++11).
 
filemappingbufoperator= (filemappingbuf &&rhs_buf)
 Move assignment (requires C++11).
 
void swap (filemappingbuf &buf)
 Swap internals (requires C++11).
 

Detailed Description

File mapping stream buffer.

This class applies the functionality of the std::streambuf class to read and write from/to memory-mapped files. By calling member open, a physical file is associated to the file buffer as its associated character sequence. Depending on the mode used in this operation, the access to the controlled input sequence or the controlled output sequence may be restricted. The state of the filemappingbuf object -i.e. whether a file is open or not- may be tested by calling member function is_open. Internally, filemappingbuf objects operate as defined in the std::streambuf class. The class overrides some virtual members inherited from streambuf to provide a specific functionality for memory-mapped files.

Constructor & Destructor Documentation

filemappingbuf::filemappingbuf ( )

Construct object.

A filemappingbuf object is constructed, initializing all its pointers to null pointers and initializing the object's locale.

filemappingbuf::filemappingbuf ( filemappingbuf &&  rhs_buf)

Move constructor (requires C++11).

Acquires the contents of rhs_buf, by move-assigning its members and base classes.

Parameters
rhs_buffilemappingbuf to move. rhs_buf becomes of invalid state after the operation.
See Also
swap()
operator=()

Member Function Documentation

filemappingbuf * filemappingbuf::close ( )

Close file.

Closes the file currently associated with the object and disassociates it. The function fails if no file is currently open (associated) with this object.

Returns
In case of success, the function returns this. In case of failure, a null pointer is returned.
See Also
open()
is_open()
const void * filemappingbuf::data ( ) const

Get the read-only base address of the mapping.

The function fails if no file is currently open (associated) with this object.

Returns
In case of success, returns the constant base address of the mapping. In case of failure, a null pointer is returned.
See Also
size()
void * filemappingbuf::data ( )

Get the base address of the mapping.

The function fails if no file is currently open (associated) with this object.

Returns
In case of success, returns the base address of the mapping. In case of failure, a null pointer is returned.
See Also
size()
bool filemappingbuf::is_open ( ) const

Check if a file is open.

The function returns true if a previous call to open succeeded and there have been no calls to the member close since, meaning that the filemappingbuf object is currently associated with a file.

Returns
true if a file is open, i.e. associated to this stream buffer object. false otherwise.
See Also
open()
close()
filemappingbuf * filemappingbuf::open ( const char *  path_name,
std::ios_base::openmode  mode,
std::streamsize  max_length = 0,
std::streamoff  offset = 0 
)

Open file.

Opens a file, associating its content with the stream buffer object to perform input/output operations on it. The operations allowed and some operating details depend on parameter mode. If the object already has a file associated (open), this function fails. If the i/o mode is input only and the file do not exist, this function fails. If the i/o mode is output and the file do not exist, the file is created with the 'offset + max_length' size. If the size of the opened file is less than 'offset + max_length', the file growing. If the size of the opened file is greater than max_length, the file is not truncated. An attempt to map a file with a length of 0 fails.

Parameters
path_nameC-string contains the name of the file to be opened.
modeFlags describing the requested i/o mode for the file. This is an object of type std::ios_base::openmode. It consists of a combination of the following member constants:
  • std::ios_base::ate (at end) Set the stream's position indicator to the end of the file on opening.
  • std::ios_base::in (input) Allow input operations on the stream.
  • std::ios_base::out (output) Allow output operations on the stream.
max_lengthMaximum length of the file mapping. If this parameter is 0, the mapping extends from the specified offset to the end of the file.
offsetFile offset where the mapping begins. They must also match the memory allocation granularity of the system. That is, the offset must be a multiple of the allocation granularity. To obtain the offset granularity of the system, use filemapping::offset_granularity().
Returns
The function returns this if successful. In case of failure, close is called and a null pointer is returned.
See Also
is_open()
close()
filemapping::offset_granularity()
filemappingbuf & filemappingbuf::operator= ( filemappingbuf &&  rhs_buf)

Move assignment (requires C++11).

Closes the source filemappingbuf (as if member close was called), and then acquires the contents of rhs_buf.

Parameters
rhs_buffilemappingbuf to move. rhs_buf becomes of invalid state after the operation.
Returns
*this.
See Also
swap()
void * filemappingbuf::pubseekptr ( void *  ptr,
std::ios_base::openmode  which = std::ios_base::in | std::ios_base::out 
)

Set internal position pointer to absolute position.

Calls protected virtual member seekptr, which sets a new position value for one or both of the internal position pointers. The parameter which determines which of the position pointers is affected: either the get pointer or the put pointer, or both. The function fails if no file is currently open (associated) with this object.

Parameters
ptrNew absolute position for the position pointer.
whichDetermines which of the internal position pointers shall be modified: the input pointer, the output pointer, or both. This is an object of type std::ios_base::openmode.
Returns
In case of success, return the new position value of the modified position pointer. In case of failure, a null pointer is returned.
See Also
std::streambuf::pubseekpos()
std::streambuf::pubseekoff()
std::streamsize filemappingbuf::size ( ) const

Get the maximum byte length of the mapping.

The function fails if no file is currently open (associated) with this object.

Returns
In case of success, returns the length of the mapping. In case of failure, 0 is returned.
See Also
data()
void filemappingbuf::swap ( filemappingbuf buf)

Swap internals (requires C++11).

Exchanges the state of the filemappingbuf with those of other.

Parameters
buffilemappingbuf to exchange the state with.
See Also
operator=()

The documentation for this class was generated from the following files: