includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::OFdBuf)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
                    (File Descriptor Output Stream Buffer)

manpagename(FBB::OFdBuf)
            (Output stream buffer initialized by a file descriptor)

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

manpagedescription()
    bf(FBB::OFdBuf) objects may be used as a tt(std::streambuf) of
tt(std::ostream) objects to allow insertions into a file descriptor.

File descriptors are not defined within the context of bf(C++),
but they can be used on operating systems that support the concept. Realize
that using file descriptors introduces operating system dependencies.

includefile(include/namespace)

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

manpagesection(ENUMERATION)
    The public enumeration tt(Mode) defined in the class tt(FBB::OFdStreamBuf)
has the following values:
    itemization(
    it() bf(CLOSE_FD), indicating that the file descriptor used by the object
must be closed;
    it() bf(KEEP_FD) (the default) indicating that the file descriptor used by
the object must not be closed.
    )

manpagesection(CONSTRUCTORS)
    itemization(
    itb(OFdBuf())
       This constructor initializes the streambuf, without associating it to a
        file descriptor, and without using buffering. The member tt(reset) can
        be used to associate the object later on with a file descriptor and
        optionally a buffer size.  When the object is destroyed or if the
        mode-less overloaded version of the tt(reset) member is called, the
        file descriptor is closed.

    itb(OFdBuf(Mode mode))
       This constructor initializes the streambuf, without associating it to a
        file descriptor, and without using buffering. The member tt(reset) can
        be used to associate the object later on with a file descriptor and
        optionally a buffer size.  When the object is destroyed or if the
        mode-less overloaded version of the member tt(reset) is called, the
        tt(Mode) argument determines whether the file descriptor will be
        closed or will remain open.

    itb(OFdBuf(int fd, size_t n = 1))
       This constructor initializes the streambuf, associating it to file
        descriptor tt(fd), and an optional unget buffer size (by default
        having size 1).  When tt(reset) is called subsequently, or if the
        object is destroyed the provided file descriptor will be closed.

    itb(OFdBuf(int fd, size_t n = 1))
       This constructor initializes the streambuf, associating it to file
        descriptor tt(fd), and an optional unget buffer size (by default
        having size 1).  When the object is destroyed or if the mode-less
        overloaded version of the member tt(reset) is called, the file
        descriptor will be closed.

    itb(OFdBuf(int fd, Mode mode, size_t n = 1))
       This constructor initializes the streambuf, associating it to file
        descriptor tt(fd), and an optional unget buffer size (by default
        having size 1).  When the object is destroyed or if the mode-less
        overloaded version of the member tt(reset) is called, the tt(Mode)
        argument determines whether the file descriptor will be closed or will
        remain open.
    )

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

manpagesection(MEMBER FUNCTIONS)
     All members of tt(std::streambuf) are available, as tt(FBB::OFdBuf)
inherits from this class.
    itemization(
    itb(void eoi())
       The file descriptor used by the tt(OFdBuf) is closed, irrespective of
        the tt(Mode) that was specified when the tt(OFdBuf) object was
        constructed. Following tt(eoi) the tt(OFdBuf) object can no longer be
        used until one of its tt(reset) members has been called. Instead of
        using this member the tt(eoi) manipulator can also be used.

    itb(int fd() const)
        The file descriptor used by the tt(OFdBuf) object is returned.
        If the tt(OFdBuf) is not associated with a file descriptor -1 is
        returned.

    itb(void reset(int xfd, size_t n = 1))
       The streambuf is (re)initialized, using file descriptor tt(fd), and an
        optional unget buffer size (by default having size 1). When called
        repeatedly, the tt(Mode) specification used whem the object was
        constructed determines whether the file descriptor will be closed or
        will remain open.

    itb(void reset(int xfd, Mode mode, size_t n = 1))
       The streambuf is (re)initialized, using file descriptor tt(fd), a file
        descriptor closing parameter and an optional unget buffer size (by
        default having size 1). Depending on the tt(Mode) argument the
        object's currently used file descriptor will be closed or will remain
        open when the tt(IFdBuf) object is destroyed.

    itb(void warn(bool on))
       When tt(on == true) a warning is written to the standard error stream
        when its tt(sync) member returns -1. If tt(warn) is not explicitly
        called tt(on == true) is used.

    )

manpagesection(MANIPULATOR)
    itemization(
    itb(FBB::eoi)
       The tt(eoi) manipulator can be inserted into the tt(ostream) instead of
        calling the tt(OFdBuf::end) member. It performs the same actions as
        the tt(eoi) member.  If inserted into a plain tt(std::ostream) nothing
        happens.
    )

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

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

manpageseealso()
    bf(bobcat)(7), bf(ifdbuf)(3bobcat), bf(ofdstream)(3bobcat),
    bf(std::streambuf)

manpagebugs()
    None reported

includefile(include/trailer)
