includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::MemoryBuf)(3bobcat)(_CurYrs_)
        (libbobcat-dev__CurVers_)
        (Memory memory streambuf)

manpagename(FBB::MemoryBuf)(streambuf interfacing to memory segments)

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

manpagedescription()
    bf(MemoryBuf) implements a specialization of the bf(std::streambuf) class,
allowing stream classes (tt(std::iostream, FBB::MemoryStream)) to perform I/O
operations on memory segmnts (cf. bf(shmget)(2)). 

bf(FBB::MemoryBuf) povides the tt(streambufs) of tt(FBB::MemoryStream)
objects using a bf(FBB::MemoryBridge) object interfacing to the shared memory
blocks read/written by a bf(FBB::MemoryBuf) object.

includefile(include/namespace)

manpagesection(INHERITS FROM)
    bf(std::streambuf).

manpagesection(CONSTRUCTORS)
    itemization(
    itb(MemoryBuf())
       The default constructor defines a stub bf(MemoryBuf) object that cannot
        immediately be used to access memory segments. In practice usable
        tt(FBB::MemoryBuf) objects are constructed by one of the following
        constructors.

    itb(MemoryBuf(std::string const &bufSize, [bool erase = false,]
            std::ios::openmode openMode = std::ios::in | std::ios::out,
            size_t access = 0600))
       Constructs a bf(MemoryBuf) object. 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(MemoryBuf) 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(MemoryBuf(int id, [bool erase,]
        std::ios::openmode openMode = std::ios::in | std::ios::out))
       This constructor connects to a memory segment having ID tt(id).

       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 constructor and the move assignment operator are available, the
    copy constructor and copy assignment operator are not available.

manpagesection(BUFSIZE)

    includefile(bufsize.inc)

manpagesection(MEMBER FUNCTIONS)

     All members of bf(std::streambuf) are available.

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

    itb(void info(std::ostream &out))
       Information about the tt(MemoryBridge) 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(MemoryBuf) object the offset just beyond thecurrent
        maximum offset is returned. E.g., if a bf(MemoryBuf) 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 setErase(bool erase))
       This member is used to change the tt(erase) setting of a bf(MemoryBuf)
        object. It can be used by, e.g., forking programs where the program
        constructs a bf(MemoryBuf) 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 can be used to reduce or enlarge the available memory size
        of a bf(MemoryBuf) object to tt(size). If it's reduced then the
        memory segements' data bytes from tt(size) to its original size are
        set to 0: newly allocated memory segments are always initialized
        to 0 byte values.

    itb(std::streamsize writtenUntil() const)
       Returns the highest ever byte-offset where a value was written.
    )

manpagesection(EXAMPLE)
    See the bf(memorystream)(3bobcat) man page.

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

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

manpagebugs()
    Note that by default exceptions thrown from within a bf(std::stream)
object are caught by the stream object, setting its tt(ios::failbit) flag. To
allow exceptions to leave a stream object, its tt(exceptions) member can be
called, e.g., using:
        verb(
    myStream.exceptions(ios::failbit | ios::badbit | ios::eofbit);
        )

includefile(include/trailer)
