includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::IOBuf)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
                    (Streambuf doing I/O)

manpagename(FBB::IOBuf)(streambuf allowing input and output operations)

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

manpagedescription()
    This class implements a specialization of the bf(std::streambuf) class,
allowing input operations from and output operations to different files. It is
intended to be used in combination with bf(FBB::IOStream), thus allowing all
stream-based input and output operations using the same object without the
need to use em(seek)-operations. Using an bf(FBB::IOStream) object it is,
e.g., possible to construct two-way communications using pipes, much like the
facilities offered by sockets.

    If the streams that will be associated with the bf(IOBuf) object
support seeking, then the bf(IOBuf) will do so to. Seeking might also be
available for a single stream (either the bf(std::istream) or the
bf(std::ostream)). 

When the bf(IOBuf) object goes out of scope, its associated
bf(std::ostream) object is flushed.

includefile(include/namespace)

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

manpagesection(CONSTRUCTORS)
    itemization(
    itb(IOBuf())
        The default constructor results in a bf(IOBuf) object that
cannot be immediately used. Its member bf(open()) must be called first.
    itb(IOBuf(std::istream &in, std::ostream &out)) 
        This constructor associates the bf(IOBuf) object with a
bf(std::istream) and a bf(std::ostream). All output operations will be passed
on to the bf(std::ostream), all input operations to the bf(std::istream). The
streams passed to bf(IOBuf()) should outlive the bf(IOBuf)
object. 
    )

    Copy and move constructors (and assignment operators) are not available.

manpagesection(MEMBER FUNCTIONS)
     All members of bf(std::streambuf) are
available, as bf(FBB::IOBuf) inherits from these classes.
    itemization(
    itb(void open(std::istream &in, std::ostream &out))
        This member (re)associates the bf(IOBuf) object with a
bf(std::istream) and a bf(std::ostream). All output operations will be passed
on to the bf(std::ostream), all input operations to the bf(std::istream). The
streams passed to bf(IOBuf()) should outlive the bf(IOBuf)
object. If this member is called for an bf(IOBuf) object already
associated with an bf(std::ostream) object, the already associated 
bf(std::ostream) object is flushed before setting up the new association.
    )

manpagesection(VIRTUAL PROTECTED MEMBER FUNCTIONS)

    The following bf(std::streambuf) member functions should only be called
when the bf(FBB::Streambuf) object is associated with bf(std::istream) and
bf(std::ostream) objects (i.e., they should not be called between the
construction of a default bf(FBB:IOBuf) object and a subsequent call of
bf(IOBuf::open())):

    The members listed in this section implement the tasks of 
comparably named virtual function in the class's private interface. This
separates the redefinable interface from the user-interface. The class
bf(IOStreamBuf) can, in accordance with Liskov's Substitution Principle, be
used as a tt(std:streambuf); but it also offers facilities for classes
deriving from bf(IOStreamBuf). These facilities are listed here.

    itemization(
    itb(pos_type pSeekoff(off_type offset, std::ios::seekdir way,
                                 std::ios::openmode mode = 
                                                std::ios::in | std::ios::out))
        With seekable streams, repositions the associated bf(std::istream)
        or bf(std::ostream) is repositioned to offset tt(offset), relative to
        tt(way).

    itb(pos_type pSeekpos(off_type offset, std::ios::openmode mode = 
                                                std::ios::in | std::ios::out))
        With seekable streams, repositions the associated bf(std::istream)
        or bf(std::ostream) is repositioned to offset tt(offset), relative to

    itb(std::streamsize pXsputn(char const *buffer, std::streamsize n))
        This member inserts tt(n) characters from tt(buffer) into the
        associated bf(std::ostream) stream.
    )

manpagesection(EXAMPLE)
    See the example provided with bf(process)(3bobcat).

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

manpageseealso()
    bf(bobcat)(7), bf(iostream)(3bobcat), bf(process)(3bobcat)

manpagebugs()
    None reported.

includefile(include/trailer)
