fmstream Class Reference

fmstream provides an interface to read/write data from/to memory-mapped files as input/output streams. More...

#include <fmstream.h>

Inheritance diagram for fmstream:

Public Member Functions
	fmstream ()
	Construct object.
	fmstream (const char *path_name, std::streamsize max_length=0, std::streamoff offset=0)
	Construct object and open or create a file.
virtual	~fmstream ()
	Destructs the fmstream object.
filemappingbuf *	rdbuf () const
	Get the associated filemappingbuf object.
bool	is_open () const
	Check if a file is open.
void	open (const char *path_name, std::streamsize max_length=0, std::streamoff offset=0)
	Open file.
void	close ()
	Close file.
const void *	ptellg ()
	Get position of the get pointer.
void *	ptellp ()
	Get position of the put pointer.
std::istream &	pseekg (const void *ptr)
	Sets the position of the get pointer.
std::ostream &	pseekp (void *ptr)
	Sets the position of the put pointer.
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.
	fmstream (fmstream &&rhs_stream)
	Move constructor (requires C++11).
fmstream &	operator= (fmstream &&rhs_stream)
	Move assignment (requires C++11).
void	swap (fmstream &stream)
	Swap internals (requires C++11).

Detailed Description

fmstream provides an interface to read/write data from/to memory-mapped files as input/output streams.

The objects of this class maintain internally a pointer to a filemappingbuf object that can be obtained by calling member rdbuf. The file to be associated with the stream can be specified either as a parameter in the constructor or by calling member open. After all necessary operations on a file have been performed, it can be closed (or disassociated) by calling member close. Once closed, the same file stream object may be used to open another file. The member function is_open can be used to determine whether the stream object is currently associated with a file. fmstream can be used in place of std::fstream.

Constructor & Destructor Documentation

fmstream::fmstream

(

)

Construct object.

Constructs an object of the fstream class. This implies the initialization of the associated filemappingbuf object and the call to the constructor of its base class with the filemappingbuf object as parameter.

fmstream::fmstream ( const char *  path_name, std::streamsize  max_length = 0, std::streamoff  offset = 0  )

explicit

Construct object and open or create a file.

Constructs an object of the fstream class. This implies the initialization of the associated filemappingbuf object and the call to the constructor of its base class with the filemappingbuf object as parameter. The stream is associated with a physical file as if a call to the member function open with the same parameters was made. If the constructor is not successful in opening the file, the object is still created although no file is associated to the stream buffer and the stream's failbit is set (which can be checked with inherited member fail).

Parameters

path_name	C-string contains the name of the file to be opened or created.
max_length	Maximum length of the file mapping. If this parameter are 0, the maximum length of the file mapping object is equal to the current size of the file.
offset	File 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().

See Also

open()

is_open()

close()

filemapping::offset_granularity()

fmstream::fmstream

(

fmstream &&

rhs_stream

)

Move constructor (requires C++11).

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

Parameters

rhs_stream

File stream to move. rhs_stream becomes of invalid state after the operation.

See Also

swap()

operator=()

Member Function Documentation

void fmstream::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. On failure, the failbit flag is set (which can be checked with member fail), and depending on the value set with exceptions an exception may be thrown.

See Also

open()

is_open()

const void * fmstream::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 * fmstream::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 fmstream::is_open

(

)

const

Check if a file is open.

Returns true if the stream is currently associated with a file, and false otherwise. The stream is associated with a file if either a previous call to member open succeeded or if the object was successfully constructed using the parameterized constructor, and close has not been called since.

Returns

true if a file is open, i.e. associated to this stream object. false otherwise.

See Also

open()

close()

void fmstream::open	(	const char *	path_name,
		std::streamsize	max_length = 0,
		std::streamoff	offset = 0
	)

Open file.

Opens a file whose name is path_name, associating its content with the stream 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 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 'offset + max_length', the file is not truncated. An attempt to map a file with a length of 0 fails. On failure, the failbit flag is set (which can be checked with member fail), and depending on the value set with exceptions an exception may be thrown.

Parameters

path_name	C-string contains the name of the file to be opened.
max_length	Maximum length of the file mapping. If this parameter are 0, the maximum length of the file mapping object is equal to the current size of the file.
offset	File 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().

See Also

is_open()

close()

filemapping::offset_granularity()

fmstream & fmstream::operator=

(

fmstream &&

rhs_stream

)

Move assignment (requires C++11).

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

Parameters

rhs_stream

File stream to move. rhs_stream becomes of invalid state after the operation.

Returns

*this.

See Also

swap()

std::istream & fmstream::pseekg

(

const void *

ptr

)

Sets the position of the get pointer.

The get pointer determines the next location to be read in the source associated to the stream. The function fails if no file is currently open (associated) with this object. On failure, the failbit flag is set (which can be checked with member fail), and depending on the value set with exceptions an exception may be thrown.

Parameters

ptr	New absolute position for the input pointer.

Returns

The function returns *this.

See Also

pseekp()

ptellg()

std::istream::seekg()

std::ostream & fmstream::pseekp

(

void *

ptr

)

Sets the position of the put pointer.

The put pointer determines the location in the output sequence where the next output operation is going to take place. The function fails if no file is currently open (associated) with this object. On failure, the failbit flag is set (which can be checked with member fail), and depending on the value set with exceptions an exception may be thrown.

Parameters

ptr	New absolute position for the output pointer.

Returns

The function returns *this.

See Also

pseekg()

ptellp()

std::istream::seekp()

const void * fmstream::ptellg

(

)

Get position of the get pointer.

The get pointer determines the next location in the input sequence to be read by the next input operation. The function fails if no file is currently open (associated) with this object.

Returns

Return the address of the get pointer. In case of failure, a null pointer is returned.

See Also

ptellp()

pseekg()

std::istream::tellg()

void * fmstream::ptellp

(

)

Get position of the put pointer.

The put pointer determines the location in the output sequence where the next output operation is going to take place. The function fails if no file is currently open (associated) with this object.

Returns

Return the address of the put pointer. In case of failure, a null pointer is returned.

See Also

ptellg()

pseekp()

std::istream::tellp()

filemappingbuf * fmstream::rdbuf

(

)

const

Get the associated filemappingbuf object.

Returns a pointer to the filemappingbuf object associated with the stream.

Returns

A pointer to the filemappingbuf object associated with the stream. Notice that for any successfully constructed fmstream object this pointer is never a null pointer, even if no files have been opened or if the stream is unbuffered.

std::streamsize fmstream::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 fmstream::swap

(

fmstream &

stream

)

Swap internals (requires C++11).

Exchanges the state of the stream with those of other.

Parameters

stream

fmstream to exchange the state with.

See Also

operator=()

---

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

• fmstream.h
• fmstream.cpp