Provided by: libbobcat-dev_6.11.00-1_amd64 
NAME
FBB::MemoryStream - I/O operations on memory segments
SYNOPSIS
#include <bobcat/memorystream>
Linking option: -lbobcat
DESCRIPTION
This class combines the features of the std::istream and std::ostream classes, operating on memory
segments (cf. shmget(2)).
As with std::fstream objects, FBB::MemoryStream objects do not keep separate offsets for reading and
writing: the seek-members always refer to the (single) offset maintained by the FBB::MemoryBridge object
to which the MemoryStream object (indirectly) interfaces.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the
namespace FBB.
INHERITS FROM
FBB::MemoryBuf (private inheritance),
std::iostream,
CONSTRUCTORS
o MemoryStream():
The default constructor defines a stub a MemoryStream object that cannot immediately be used to
access memory segments. To use it, its member open must first be called.
o MemoryStream(std::string const &bufSize, [bool erase = false,] std::ios::openmode openMode =
std::ios::in | std::ios::out, size_t access = 0600):
Constructs a MemoryStream object inheriting the facilities of the std::iostream class. Its default
capacity is specified by bufSize (cf. section BUFSIZE), using memory segment(s) containing the
stream’s bytes.
The access rights of the data stored in MemoryStream objects are defined by the access parameter,
interpreted as an octal value, using the specifications used by (chmod(1)).
The erase parameter is used to specify what happens to the memory segments once the MemoryStream
object goes out of scope. When omitted or specified as false the allocated memory segments are not
erased from memory when the object goes out of scope (and can be reaccessed until the computer is
rebooted) using the memory object’s ID (see the next constructor). When specified as true the
memory segments are erased from memory when the object goes out of scope.
If construction fails, an FBB::Exception is thrown.
o MemoryStream(int id, [bool erase = false,] std::ios::openmode openMode = std::ios::in |
std::ios::out):
Constructs a MemoryStream connecting to the memory segments created by the previous constructor,
using the memory segment’s ID defined by that constructor.
The erase parameter is used as it is used by the previous constructor.
Specifying the ios::trunc flag (or a comparable flag, like merely ios::out) immediately clears the
current content of the memory segments.
An FBB::Exception is thrown if construction fails (e.g., no memory segment having ID id exists),
The move/copy constructors and assignment operators are not available.
BUFSIZE
The bufSize parameter required by the second MemoryStream constructor and the open member (see below)
specifies the default number nummber of shared memory memory blocks and their sizes. The size of the
memory blocks is specified as k, M or G, indicating block sizes in kilo-, Mega- and GigaBytes. Before
those letters the default number of blocks is specified. E.g., "100M". Internally the number of kiloBytes
is converted to `pages’, using the system’s page size, which is commonly equal to 4 kB (so when
specifying "5k" then the stream prepares for two shared data segments, each having a capacity of 4 kB.
The number of MegaBytes is used as specified, and when specifying GB the data segments are .5 GB.
The number of shared data segments is aotomatically enlarged when the current capacity is exceeded, and
the potentially available data segments are initially not allocated: they’re allocated once information
is written into their areas.
MEMBER FUNCTIONS
All members of std::iostream are available.
o void exceptions(std::ios::iostate flag):
After calling this member exceptions thrown while processing a MemoryStream leave the MemoryStream
object, setting the stream’s state to flag. Such exceptions are caught as usual, while the
object’s iostate is set to flag, allowing internally generated exceptions to be distinguished from
other exceptions. Commonly the argument std::ios::badbit is used.
o int id() const:
The ID of the memory segments is returned.
o void info(std::ostream &out):
Information about the object’s MemoryBuf is inserted into out: the IDs of the memory data blocks,
their sizes, the current maximum number of memory data blocks, the number of bytes that can be
read from the memory segments, and its actual storage capacity.
o std::streamsize maxEnd() const:
When using a MemoryStream object the offset just beyond thecurrent maximum offset is returned.
E.g., if a MemoryStream object is configured with 5 data blocks of 1 MB each, then maxEnd returns
5 * 1024 * 1024. When the object extends its number of data blocks maxEnd returns the
corresponding new value.
o void open(char const *bufSize, [bool erase = false,] std::ios::openmode openMode = std::ios::in |
std::ios::out, size_t access = 0600):
This member can be used to activate a MemoryStream object initially created by its default
constructor. It expects the same argument as the second constructor. A matching close member does
not exist and is not required.
If opening fails, an FBB::Exception is thrown.
o void open(int id, [bool erase = false,] std::ios::openmode openMode = std::ios::in |
std::ios::out, size_t access = 0600):
This member can be used to activate a MemoryStream object initially created by its default
constructor specifying the ID of a previously constructed MemoryStream object. It expects the same
argument as the third constructor. A matching close member does not exist and is not required.
If opening fails, an FBB::Exception is thrown.
o void setErase(bool erase):
This member is used to change the erase setting of a MemoryStream object. It can be used by, e.g.,
forking programs where the program constructs a MemoryStream object specifying erase == false, but
whose memory segments should be erased when the parent process ends but not also when the child
process ends. This is accomplished by calling setErase(true) in the parent process.
o void truncate(std::streamsize size):
This member is used to reduce or enlarge the available memory size of a MemoryStream to size. If
it’s reduced then the memory segments’ data bytes from size to its original size are set to 0:
newly allocated memory segments are always initialized to 0 byte values.
EXAMPLE
#include <iostream>
#include <string>
#include <ostream>
#include <istream>
#include <bobcat/exception>
#include <bobcat/memorystream>
using namespace std;
using namespace FBB;
int main(int argc, char **argv)
{
MemoryStream ms;
char ch = ’h’;
string cmd;
while (true)
{
ios::off_type offset;
switch (ch)
{
case ’h’:
cout <<
"\n"
" b open a MemoryStream for 10k\n"
" h this info\n"
" i show info about the memory stream\n"
" o show the current absolute offset\n"
" q quit\n"
" s <x> seek (abs) offset x\n"
" x extract the next line from the current offset\n"
" < insert lines (until empty) at the current "
"offset\n"
" > extract lines (until EOF) from the current "
"offset\n";
break;
case ’b’:
ms.open("10k", true);
[[fallthrough]];
case ’i’:
ms.info(cout);
break;
case ’o’:
cout << ms.seekg(0, ios::cur).tellg() << ’\n’;
break;
case ’q’:
return 0;
case ’s’:
{
size_t offset;
cin >> offset;
cout << "tellg: " << ms.seekg(offset).tellg() << ’\n’;
}
break;
case ’x’:
{
string line;
if (getline(ms, line))
cout << line << ’\n’;
else
{
cout << "No lines available\n";
ms.clear();
}
}
break;
case ’<’:
{
cin.ignore(100, ’\n’);
while (true)
{
string line;
getline(cin, line);
if (line.empty())
break;
ms << line << endl;
}
}
break;
case ’>’:
{
string line;
while (getline(ms, line))
cout << line << ’\n’;
ms.clear();
ms.seekg(0, ios::end);
}
break;
default:
cout << "request `" << ch << "’ not implemented\n";
break;
}
cout << "? ";
cin >> ch;
}
}
FILES
bobcat/memorystream - defines the class interface
SEE ALSO
bobcat(7), chmod(1), memorybuf(3bobcat), memoryreadme(7bobcat), shmget(2)
BUGS
None reported
BOBCAT PROJECT FILES
o https://fbb-git.gitlab.io/bobcat/: gitlab project page;
Debian Bobcat project files:
o libbobcat6: debian package containing the shared library, changelog and copyright note;
o libbobcat-dev: debian package containing the static library, headers, manual pages, and developer
info;
BOBCAT
Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.
COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License (GPL).
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).
libbobcat-dev_6.11.00 2005-2025 FBB::MemoryStream(3bobcat)