This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

<streambuf>

Include the iostreams standard header <streambuf> to define template class basic_streambuf, which is basic to the operation of the iostreams classes. (This header is typically included for you by another of the iostreams headers. You seldom have occasion to include it directly.)

namespace std {
template<class Elem, class Tr = char_traits<Elem> >
    class basic_streambuf;
typedef basic_streambuf<char, char_traits<char> >
    streambuf;
typedef basic_streambuf<wchar_t,
    char_traits<wchar_t> > wstreambuf;
    };

basic_streambuf

basic_streambuf · char_type · eback · egptr · epptr · gbump · getloc · gptr · imbue · in_avail · int_type · off_type · overflow · pbackfail · pbase · pbump · pos_type · pptr · pubimbue · pubseekoff · pubseekpos · pubsetbuf · pubsync · sbumpc · seekoff · seekpos · setbuf · setg · setp · sgetc · sgetn · showmanyc · snextc · sputbackc · sputc · sputn · stossc · sungetc · sync · traits_type · uflow · underflow · xsgetn · xsputn

template <class Elem, class Tr = char_traits<Elem> >
    class basic_streambuf {
public:
    typedef Elem char_type;
    typedef Tr traits_type;
    typedef typename traits_type::int_type int_type;
    typedef typename traits_type::pos_type pos_type;
    typedef typename traits_type::off_type off_type;
    virtual ~streambuf();
    locale pubimbue(const locale& loc);
    locale getloc() const;
    basic_streambuf *pubsetbuf(char_type *buffer,
        streamsize count);
    pos_type pubseekoff(off_type off,
        ios_base::seekdir way,
        ios_base::openmode which =
            ios_base::in | ios_base::out);
    pos_type pubseekpos(pos_type sp,
        ios_base::openmode which =
            ios_base::in | ios_base::out);
    int pubsync();
    streamsize in_avail();
    int_type snextc();
    int_type sbumpc();
    int_type sgetc();
    void stossc(); [optional]
    streamsize sgetn(char_type *ptr, streamsize count);
    int_type sputbackc(char_type ch);
    int_type sungetc();
    int_type sputc(char_type ch);
    streamsize sputn(const char_type *ptr, streamsize count);
protected:
    basic_streambuf();
    char_type *eback() const;
    char_type *gptr() const;
    char_type *egptr() const;
    void gbump(int count);
    void setg(char_type *gbeg,
        char_type *gnext, char_type *gend);
    char_type *pbase() const;
    char_type *pptr() const;
    char_type *epptr() const;
    void pbump(int count);
    void setp(char_type *pbeg, char_type *pend);
    virtual void imbue(const locale &loc);
    virtual basic_streambuf *setbuf(char_type *buffer,
        streamsize count);
    virtual pos_type seekoff(off_type off,
        ios_base::seekdir way,
        ios_base::openmode which =
            ios_base::in | ios_base::out);
    virtual pos_type seekpos(pos_type sp,
        ios_base::openmode which =
            ios_base::in | ios_base::out);
    virtual int sync();
    virtual streamsize showmanyc();
    virtual streamsize xsgetn(char_type *ptr,
        streamsize count);
    virtual int_type underflow();
    virtual int_type uflow();
    virtual int_type pbackfail(int_type meta =
        traits_type::eof());
    virtual streamsize xsputn(const char_type *ptr,
        streamsize count);
    virtual int_type overflow(int_type meta =
        traits_type::eof());
    };

The template class describes an abstract base class for deriving a stream buffer, which controls the transmission of elements to and from a specific representation of a stream. An object of class basic_streambuf helps control a stream with elements of type Tr, also known as char_type, whose character traits are determined by the class char_traits, also known as traits_type.

Every stream buffer conceptually controls two independent streams, in fact, one for extractions (input) and one for insertions (output). A specific representation may, however, make either or both of these streams inaccessible. It typically maintains some relationship between the two streams. What you insert into the output stream of a basic_stringbuf<Elem, Tr> object, for example, is what you later extract from its input stream. And when you position one stream of a basic_filebuf<Elem, Tr> object, you position the other stream in tandem.

The public interface to template class basic_streambuf supplies the operations common to all stream buffers, however specialized. The protected interface supplies the operations needed for a specific representation of a stream to do its work. The protected virtual member functions let you tailor the behavior of a derived stream buffer for a specific representation of a stream. Each of the derived stream buffers in this library describes how it specializes the behavior of its protected virtual member functions. Documented here is the default behavior for the base class, which is often to do nothing.

The remaining protected member functions control copying to and from any storage supplied to buffer transmissions to and from streams. An input buffer, for example, is characterized by:

• eback(), a pointer to the beginning of the buffer
• gptr(), a pointer to the next element to read
• egptr(), a pointer just past the end of the buffer

Similarly, an output buffer is characterized by:

• pbase(), a pointer to the beginning of the buffer
• pptr(), a pointer to the next element to write
• epptr(), a pointer just past the end of the buffer

For any buffer, the protocol is:

• If the next pointer is null, no buffer exists. Otherwise, all three pointers point into the same sequence. (They can be safely compared for order.)
• For an output buffer, if the next pointer compares less than the end pointer, you can store an element at the write position designated by the next pointer.
• For an input buffer, if the next pointer compares less than the end pointer, you can read an element at the read position designated by the next pointer.
• For an input buffer, if the beginning pointer compares less than the next pointer, you can put back an element at the putback position designated by the decremented next pointer.

Any protected virtual member functions you write for a class derived from basic_streambuf<Elem, Tr> must cooperate in maintaining this protocol.

An object of class basic_streambuf<Elem, Tr> stores the six pointers described above. It also stores a locale object in an object of type locale for potential use by a derived stream buffer.

basic_streambuf::basic_streambuf

basic_streambuf();

The protected constructor stores a null pointer in all the pointers controlling the input buffer and the output buffer. It also stores locale::classic() in the locale object.

basic_streambuf::char_type

typedef Elem char_type;

The type is a synonym for the template parameter Elem.

basic_streambuf::eback

char_type *eback() const;

The member function returns a pointer to the beginning of the input buffer.

basic_streambuf::egptr

char_type *egptr() const;

The member function returns a pointer just past the end of the input buffer.

basic_streambuf::epptr

char_type *epptr() const;

The member function returns a pointer just past the end of the output buffer.

basic_streambuf::gbump

void gbump(int count);

The member function adds count to the next pointer for the input buffer.

basic_streambuf::getloc

locale getloc() const;

The member function returns the stored locale object.

basic_streambuf::gptr

char_type *gptr() const;

The member function returns a pointer to the next element of the input buffer.

basic_streambuf::imbue

virtual void imbue(const locale &loc);

The default behavior is to do nothing.

basic_streambuf::in_avail

streamsize in_avail();

If a read position is available, the member function returns egptr() - gptr(). Otherwise, it returns showmanyc().

basic_streambuf::int_type

typedef typename traits_type::int_type int_type;

The type is a synonym for traits_type::int_type.

basic_streambuf::off_type

typedef typename traits_type::off_type off_type;

The type is a synonym for traits_type::off_type.

basic_streambuf::overflow

virtual int_type overflow(int_type meta =
    traits_type::eof());

If meta does not compare equal to traits_type::eof(), the protected virtual member function endeavors to insert the element traits_type:: to_char_type(meta) into the output stream. It can do so in various ways:

• If a write position is available, it can store the element into the write position and increment the next pointer for the output buffer.
• It can make a write position available by allocating new or additional storage for the output buffer.
• It can make a write position available by writing out, to some external destination, some or all of the elements between the beginning and next pointers for the output buffer.

If the function cannot succeed, it returns traits_type::eof() or throws an exception. Otherwise, it returns traits_type::not_eof(meta). The default behavior is to return traits_type::eof().

basic_streambuf::pbackfail

virtual int_type pbackfail(int_type meta =
    traits_type::eof());

The protected virtual member function endeavors to put back an element into the input stream, then make it the current element (pointed to by the next pointer). If meta compares equal to traits_type::eof(), the element to push back is effectively the one already in the stream before the current element. Otherwise, that element is replaced by traits_type:: to_char_type(meta). The function can put back an element in various ways:

• If a putback position is available, it can store the element into the putback position and decrement the next pointer for the input buffer.
• It can make a putback position available by allocating new or additional storage for the input buffer.
• For a stream buffer with common input and output streams, it can make a putback position available by writing out, to some external destination, some or all of the elements between the beginning and next pointers for the output buffer.

If the function cannot succeed, it returns traits_type::eof() or throws an exception. Otherwise, it returns some other value. The default behavior is to return traits_type::eof().

basic_streambuf::pbase

char_type *pbase() const;

The member function returns a pointer to the beginning of the output buffer.

basic_streambuf::pbump

void pbump(int count);

The member function adds count to the next pointer for the output buffer.

basic_streambuf::pos_type

typedef typename traits_type::pos_type pos_type;

The type is a synonym for traits_type::pos_type.

basic_streambuf::pptr

char_type *pptr() const;

The member function returns a pointer to the next element of the output buffer.

basic_streambuf::pubimbue

locale pubimbue(const locale& loc);

The member function stores loc in the locale object, calls imbue(), then returns the previous value stored in the locale object.

basic_streambuf::pubseekoff

pos_type pubseekoff(off_type off,
    ios_base::seekdir way,
    ios_base::openmode which =
        ios_base::in | ios_base::out);

The member function returns seekoff(off, way, which).

basic_streambuf::pubseekpos

pos_type pubseekpos(pos_type sp,
    ios_base::openmode which =
        ios_base::in | ios_base::out);

The member function returns seekpos(sp, which).

basic_streambuf::pubsetbuf

basic_streambuf *pubsetbuf(char_type *buffer, streamsize count);

The member function returns setbuf(buffer, count).

basic_streambuf::pubsync

int pubsync();

The member function returns sync().

basic_streambuf::sbumpc

int_type sbumpc();

If a read position is available, the member function returns traits_type::to_int_type( *gptr()) and increments the next pointer for the input buffer. Otherwise, it returns uflow().

basic_streambuf::seekoff

virtual pos_type seekoff(off_type off,
    ios_base::seekdir way,
    ios_base::openmode which =
        ios_base::in | ios_base::out);

The protected virtual member function endeavors to alter the current positions for the controlled streams. The new position is determined as follows:

• If way == ios_base::beg, the new position is the beginning of the stream plus off.
• If way == ios_base::cur, the new position is the current stream position plus off.
• If way == ios_base::end, the new position is the end of the stream plus off.

Typically, if which & ios_base::in is nonzero, the input stream is affected, and if which & ios_base::out is nonzero, the output stream is affected. Actual use of this parameter varies among derived stream buffers, however.

If the function succeeds in altering the stream position(s), it returns the resultant stream position (or one of them). Otherwise, it returns an invalid stream position. The default behavior is to return an invalid stream position.

basic_streambuf::seekpos

virtual pos_type seekpos(pos_type sp,
    ios_base::openmode which =
        ios_base::in | ios_base::out);

The protected virtual member function endeavors to alter the current positions for the controlled streams. The new position is sp.

Typically, if which & ios_base::in is nonzero, the input stream is affected, and if which & ios_base::out is nonzero, the output stream is affected. Actual use of this parameter varies among derived stream buffers, however.

If the function succeeds in altering the stream position(s), it returns the resultant stream position (or one of them). Otherwise, it returns an invalid stream position. The default behavior is to return an invalid stream position.

basic_streambuf::setbuf

virtual basic_streambuf *setbuf(char_type *buffer,
    streamsize count);

The protected virtual member function performs an operation particular to each derived stream buffer. (See, for example, basic_filebuf.) The default behavior is to return this.

basic_streambuf::setg

void setg(char_type *gbeg, char_type *gnext,
    char_type *gend);

The member function stores gbeg in the beginning pointer, gnext in the next pointer, and gend in the end pointer for the input buffer.

basic_streambuf::setp

void setp(char_type *pbeg, char_type *pend);

The member function stores pbeg in the beginning pointer, pbeg in the next pointer, and pend in the end pointer for the output buffer.

basic_streambuf::sgetc

int_type sgetc();

If a read position is available, the member function returns traits_type::to_int_type( *gptr()) Otherwise, it returns underflow().

basic_streambuf::sgetn

streamsize sgetn(char_type *ptr, streamsize count);

The member function returns xsgetn(ptr, count).

basic_streambuf::showmanyc

virtual streamsize showmanyc();

The protected virtual member function returns a count of the number of characters that can be extracted from the input stream with no fear that the program will suffer an indefinite wait. The default behavior is to return zero.

basic_streambuf::snextc

int_type snextc();

The member function calls sbumpc() and, if that function returns traits_type::eof(), returns traits_type::eof(). Otherwise, it returns sgetc().

basic_streambuf::sputbackc

int_type sputbackc(char_type ch);

If a putback position is available and ch compares equal to the character stored in that position, the member function decrements the next pointer for the input buffer and returns traits_type::to_int_type(ch). Otherwise, it returns pbackfail(ch).

basic_streambuf::sputc

int_type sputc(char_type ch);

If a write position is available, the member function stores ch in the write position, increments the next pointer for the output buffer, and returns traits_type::to_int_type(ch). Otherwise, it returns overflow(ch).

basic_streambuf::sputn

streamsize sputn(const char_type *ptr, streamsize count);

The member function returns xsputn(ptr, count).

basic_streambuf::stossc

void stossc(); [optional]

The member function calls sbumpc(). Note that an implementation is not required to supply this member function.

basic_streambuf::sungetc

int_type sungetc();

If a putback position is available, the member function decrements the next pointer for the input buffer and returns traits_type::to_int_type( *gptr()). Otherwise it returns pbackfail().

basic_streambuf::sync

virtual int sync();

The protected virtual member function endeavors to synchronize the controlled streams with any associated external streams. Typically, this involves writing out any elements between the beginning and next pointers for the output buffer. It does not involve putting back any elements between the next and end pointers for the input buffer. If the function cannot succeed, it returns -1. The default behavior is to return zero.

basic_streambuf::traits_type

typedef Tr traits_type;

The type is a synonym for the template parameter Tr.

basic_streambuf::uflow

virtual int_type uflow();

The protected virtual member function endeavors to extract the current element ch from the input stream, then advance the current stream position, and return the element as traits_type::to_int_type(ch). It can do so in various ways:

• If a read position is available, it takes ch as the element stored in the read position and advances the next pointer for the input buffer.
• It can read an element directly, from some external source, and deliver it as the value ch.
• For a stream buffer with common input and output streams, it can make a read position available by writing out, to some external destination, some or all of the elements between the beginning and next pointers for the output buffer. Or it can allocate new or additional storage for the input buffer. The function then reads in, from some external source, one or more elements.

If the function cannot succeed, it returns traits_type::eof(), or throws an exception. Otherwise, it returns the current element ch in the input stream, converted as described above, and advances the next pointer for the input buffer. The default behavior is to call underflow() and, if that function returns traits_type::eof(), to return traits_type::eof(). Otherwise, the function returns the current element ch in the input stream, converted as described above, and advances the next pointer for the input buffer.

basic_streambuf::underflow

virtual int_type underflow();

The protected virtual member function endeavors to extract the current element ch from the input stream, without advancing the current stream position, and return it as traits_type::to_int_type(ch). It can do so in various ways:

• If a read position is available, ch is the element stored in the read position.
• It can make a read position available by allocating new or additional storage for the input buffer, then reading in, from some external source, one or more elements.

If the function cannot succeed, it returns traits_type::eof(), or throws an exception. Otherwise, it returns the current element in the input stream, converted as described above. The default behavior is to return traits_type::eof().

basic_streambuf::xsgetn

virtual streamsize xsgetn(char_type *ptr, streamsize count);

The protected virtual member function extracts up to count elements from the input stream, as if by repeated calls to sbumpc, and stores them in the array beginning at ptr. It returns the number of elements actually extracted.

basic_streambuf::xsputn

virtual streamsize xsputn(const char_type *ptr,
    streamsize count);

The protected virtual member function inserts up to count elements into the output stream, as if by repeated calls to sputc, from the array beginning at ptr. It returns the number of elements actually inserted.

streambuf

typedef basic_streambuf<char, char_traits<char> >
    streambuf;

The type is a synonym for template class basic_streambuf, specialized for elements of type char with default character traits.

wstreambuf

typedef basic_streambuf<wchar_t, char_traits<wchar_t> >
    wstreambuf;

The type is a synonym for template class basic_streambuf, specialized for elements of type wchar_t with default character traits.

See also the Table of Contents and the Index.

Copyright © 1992-2002 by P.J. Plauger. All rights reserved.