The class hi(streambuf)tt(std::streambuf) receives the character sequences
processed by streams and defines the interface between stream objects and
devices (like a file on disk). A tt(streambuf) object is usually not directly
constructed, but usually it is used as base class of some derived class
implementing the communication with some concrete device.

    The primary reason for existence of the class tt(streambuf) is to decouple
the tt(stream) classes from the devices they operate upon. The rationale here
is to add an extra layer between the classes allowing us to communicate with
devices and the devices themselves. This implements a emi(chain of command)
which is seen regularly in software design.

    The em(chain of command) is considered a generic pattern when designing
 i(reusable software), encountered also in, e.g., the
 i(TCP/IP stack).

    A tt(streambuf) can be considered yet another example of the chain of
command pattern. Here the program talks to tt(stream) objects, which in turn
forward their requests to tt(streambuf) objects, which in turn communicate
with the devices. Thus, as we will see shortly, we are able to do in
user-software what had to be done via (expensive) system calls before.

    The class tt(streambuf) has no public constructor, but does make available
several public member functions. In addition to these public member functions,
several member functions are only available to classes derived from
tt(streambuf).  In section ref(FILEBUF) a predefined specialization of the
class tt(streambuf) is introduced. All public members of tt(streambuf)
discussed here are em(also) available in tt(filebuf).

    The next section shows the tt(streambuf) members that may be overridden
when deriving classes from tt(streambuf). Chapter ref(CONCRETE) offers
concrete examples of classes derived from tt(streambuf).

    The class tt(streambuf) is used by streams performing input operations and
by streams performing output operations and their member functions can be
ordered likewise. The type tt(std::streamsize)hi(streamsize) used below may,
for all practical purposes, be considered equal to the type tt(size_t).

label(STRBUFLABEL)
    hi(streambuf: and exceptions)hi(exception: and streambuf)
    When inserting information into tt(ostream) objects the information is
eventually passed on to the tt(ostream)'s tt(streambuf). The tt(streambuf) may
decide to throw an exception. However, this exception does not leave the
tt(ostream) using the tt(streambuf). Rather, the exception is caught by the
tt(ostream), which sets its tt(ios::bad_bit). Exceptions thrown by
manipulators which are inserted into tt(ostream) objects are em(not) caught by
the tt(ostream) objects.

bf(Public members for input operations)

    itemization(
    ithtq(in_avail)
        (std::streamsize in_avail())
       (Returns a lower bound on the number of characters that can be read
        immediately.)
    ithtq(sbumpc)
        (int sbumpc())
       (The next available character or endOfFile() is returned. The returned
        character is removed from the tt(streambuf) object. If no input is
        available, tt(sbumpc) calls the (protected) member ti(uflow) (see
        section ref(SBPROTECTED) below) to make new characters
        available. endOfFile() is returned if no more characters are
        available.)
    ithtq(sgetc)
        (int sgetc())
       (The next available character or endOfFile() is returned. The character
        is em(not) removed from the tt(streambuf) object. To remove a
        character from the tt(streambuf) object, tt(sbumpc) (or tt(sgetn)) can
        be used.)
    ithtq(sgetn)
        (int sgetn(char *buffer, std::streamsize n))
       (At most tt(n) characters are retrieved from the input buffer, and
        stored in tt(buffer). The actual number of characters read is
        returned. The (protected) member ti(xsgetn) (see section
        ref(SBPROTECTED) below) is called to obtain the requested number of
        characters.)
    ithtq(snextc)
        (int snextc())
       (The current character is obtained from the input buffer and returned as
        the next available character or endOfFile() is returned. The character
        is em(not) removed from the tt(streambuf) object.)
    ithtq(sputback)
        (int sputback(char c))
       (Inserts tt(c) into the tt(streambuf)'s buffer to be returned as the
        next character to read from the tt(streambuf) object. Caution should
        be exercised when using this function: often there is a maximum of
        just one character that can be put back.)
    ithtq(sungetc)
        (int sungetc())
        (Returns the last character read to the input buffer, to be read again
        at the next input operation.  Caution should be exercised when using
        this function: often there is a maximum of just one character that
        can be put back.)
    )

bf(Public members for output operations)

    itemization(
    ithtq(pubsync)
        (int pubsync())
       (Synchronizes (i.e., flushes) the buffer by writing any information
        currently available in the tt(streambuf)'s buffer to the
        device. Normally only used by classes derived from tt(streambuf).)
    ithtq(sputc)
        (int sputc(char c))
       (Character tt(c) is inserted into the tt(streambuf) object.  If, after
        writing the character, the buffer is full, the function calls the
        (protected) member function ti(overflow) to flush the buffer to the
        device (see section ref(SBPROTECTED) below).)
    ithtq(sputn)
        (int sputn(char const *buffer, std::streamsize n))
       (At most tt(n) characters from tt(buffer) are inserted into the
        tt(streambuf) object. The actual number of characters inserted is
        returned. This member function calls the (protected) member ti(xsputn)
        (see section ref(SBPROTECTED) below) to insert the requested number of
        characters.)
    )

bf(Public members for miscellaneous operations)

    The next three members are normally only used by classes derived from
tt(streambuf).
    itemization(
    ithtq(pubseekoff)
        (ios::pos_type pubseekoff(ios::off_type offset, ios::seekdir way,
            ios::openmode mode = ios::in | ios::out))
       (Sets the offset of the next character to be read or written to
        tt(offset), relative to the standard hi(seekdir) tt(ios::seekdir)
        values indicating the direction of the seeking operation.)
    ithtq(pubseekpos)
       (ios::pos_type pubseekpos(ios::pos_type offset,
            ios::openmode mode = ios::in | ios::out))
       (Sets the i(absolute position) of the next character to be read or
        written to tt(pos).)
    ithtq(pubsetbuf)
        (streambuf *pubsetbuf(char* buffer, std::streamsize n))
       (The tt(streambuf) object is going to use ti(buffer), which may contain
        at least tt(n) characters.)
    )
