includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::MemoryStream)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
                    (I/O on memory segments)

manpagename(FBB::MemoryStream)(I/O operations on memory segments)

manpagesynopsis()
    bf(#include <bobcat/memorystream>)nl()
    Linking option: tt(-lbobcat)

manpagedescription()

    This class combines the features of the bf(std::istream) and
bf(std::ostream) classes, operating on memory segments (cf. bf(shmget)(2)).

As with tt(std::fstream) objects, bf(FBB::MemoryStream) objects do not keep
separate offsets for reading and writing: the seek-members always refer to
the (single) offset maintained by the bf(FBB::MemoryBridge) object to which
the bf(MemoryStream) object (indirectly) interfaces.

includefile(include/namespace)

manpagesection(INHERITS FROM)
    bf(FBB::MemoryBuf) (private inheritance),nl()
    bf(std::iostream),nl()

manpagesection(CONSTRUCTORS)
    itemization(
    itb(MemoryStream())
       The default constructor defines a stub a bf(MemoryStream) object that
        cannot immediately be used to access memory segments. To use it, its
        member tt(open) must first be called.

    itb(MemoryStream(std::string const &bufSize, [bool erase = false,]
            std::ios::openmode openMode = std::ios::in | std::ios::out,
            size_t access = 0600))
       Constructs a bf(MemoryStream) object inheriting the facilities of the
        tt(std::iostream) class. Its default capacity is specified by
        tt(bufSize) (cf. section tt(BUFSIZE)), using memory segment(s)
        containing the stream's bytes.

        The access rights of the data stored in bf(MemoryStream) objects are
        defined by the tt(access) parameter, interpreted as an octal value,
        using the specifications used by (bf(chmod)(1)).

        The tt(erase) parameter is used to specify what happens to the memory
        segments once the bf(MemoryStream) object goes out of scope. When
        omitted or specified as tt(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
        tt(ID) (see the next constructor). When specified as tt(true) the
        memory segments are erased from memory when the object goes out of
        scope.

        If construction fails, an tt(FBB::Exception) is thrown.

    itb(MemoryStream(int id, [bool erase = false,]
        std::ios::openmode openMode = std::ios::in | std::ios::out))
       Constructs a bf(MemoryStream) connecting to the memory segments created
        by the previous constructor, using the memory segment's tt(ID) defined
        by that constructor.

        The tt(erase) parameter is used as it is used by the previous
        constructor. 

        Specifying the tt(ios::trunc) flag (or a comparable flag, like merely
        tt(ios::out)) immediately clears the current content of the memory
        segments.

        An tt(FBB::Exception) is thrown if construction fails (e.g., no memory
        segment having ID tt(id) exists),
    )

    The move/copy  constructors and assignment operators are not available.

manpagesection(BUFSIZE)

    includefile(bufsize.inc)

manpagesection(MEMBER FUNCTIONS)

     All members of tt(std::iostream) are available.

    itemization(
    itb(void exceptions(std::ios::iostate flag))
       After calling this member exceptions thrown while processing a
        bf(MemoryStream) leave the bf(MemoryStream) object, setting the
        stream's state to tt(flag). Such exceptions are caught as usual, while
        the object's tt(iostate) is set to tt(flag), allowing internally
        generated exceptions to be distinguished from other
        exceptions. Commonly the argument tt(std::ios::badbit) is used.

    itb(int id() const)
       The ID of the memory segments is returned.

    itb(void info(std::ostream &out))
       Information about the object's tt(MemoryBuf) is inserted into tt(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.

    itb(std::streamsize maxEnd() const)
       When using a bf(MemoryStream) object the offset just beyond thecurrent
        maximum offset is returned. E.g., if a bf(MemoryStream) object is
        configured with 5 data blocks of 1 MB each, then tt(maxEnd) returns 5
        * 1024 * 1024. When the object extends its number of data blocks
        tt(maxEnd) returns the corresponding new value.

    itb(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 bf(MemoryStream) object initially
        created by its default constructor. It expects the same argument as
        the second constructor. A matching tt(close) member does not exist and
        is not required.

        If opening fails, an tt(FBB::Exception) is thrown.

    itb(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 bf(MemoryStream) object initially
        created by its default constructor specifying the tt(ID) of a
        previously constructed bf(MemoryStream) object. It expects the same
        argument as the third constructor. A matching tt(close) member does
        not exist and is not required.

        If opening fails, an tt(FBB::Exception) is thrown.

    itb(void setErase(bool erase))
       This member is used to change the tt(erase) setting of a
        bf(MemoryStream) object. It can be used by, e.g., forking programs
        where the program constructs a bf(MemoryStream) object specifying
        tt(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 tt(setErase(true)) in the parent process.

    itb(void truncate(std::streamsize size))
       This member is used to reduce or enlarge the available memory size of a
        bf(MemoryStream) to tt(size). If it's reduced then the memory
        segments' data bytes from tt(size) to its original size are set to 0:
        newly allocated memory segments are always initialized to 0 byte
        values.
    )

manpagesection(EXAMPLE)
    verbinclude(../../memorystream/driver/driver.cc)

manpagefiles()
    em(bobcat/memorystream) - defines the class interface

manpageseealso()
    bf(bobcat)(7), bf(chmod)(1), bf(memorybuf)(3bobcat),
        bf(memoryreadme)(7bobcat), bf(shmget)(2)

manpagebugs()
    None reported

includefile(include/trailer)
