# <streambuf>

<head><title>&lt;streambuf&gt;</title></head>

# `<streambuf>`

* * *

Include the [iostreams](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cpp.html#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;
    }  // namespace stdCopy to clipboard

## `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;
    
        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());
        };Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits)
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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_locale2.html#locale%20object)**
in an object of type
`locale`
for potential use by a derived stream buffer.

### `basic_streambuf::basic_streambuf`

    basic_streambuf();Copy to clipboard

The protected constructor stores a null pointer in all the pointers
controlling the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer) and the
[output buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer).
It also stores
`locale::classic()`
in the [locale object](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_locale2.html#locale%20object).

### `basic_streambuf::char_type`

    typedef Elem char_type;Copy to clipboard

The type is a synonym for the template parameter `Elem`.

### `basic_streambuf::eback`

    char_type *eback() const;Copy to clipboard

The member function returns a pointer to the beginning of the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer).

### `basic_streambuf::egptr`

    char_type *egptr() const;Copy to clipboard

The member function returns a pointer just past the end of the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer).

### `basic_streambuf::epptr`

    char_type *epptr() const;Copy to clipboard

The member function returns a pointer just past the end of the
[output buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer).

### `basic_streambuf::gbump`

    void gbump(int count);Copy to clipboard

The member function adds `count` to the next pointer for the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer).

### `basic_streambuf::getloc`

    locale getloc() const;Copy to clipboard

The member function returns the stored locale object.

### `basic_streambuf::gptr`

    char_type *gptr() const;Copy to clipboard

The member function returns a pointer to the next element of the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer).

### `basic_streambuf::imbue`

    virtual void imbue(const locale &loc);Copy to clipboard

The default behavior is to do nothing.

### `basic_streambuf::in_avail`

    streamsize in_avail();Copy to clipboard

If a [read position](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#read%20position) is available,
the member function returns
`egptr() -
gptr()`.
Otherwise, it returns
`showmanyc()`.

### `basic_streambuf::int_type`

    typedef typename traits_type::int_type int_type;Copy to clipboard

The type is a synonym for
`traits_type::int_type`.

### `basic_streambuf::off_type`

    typedef typename traits_type::off_type off_type;Copy to clipboard

The type is a synonym for
`traits_type::off_type`.

### `basic_streambuf::overflow`

    virtual int_type overflow(int_type meta =
        traits_type::eof());Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#write%20position) is available,
it can store the element into the write position and increment the
next pointer for the
[output buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer).
- 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());Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#putback%20position) is available,
it can store the element into the putback position and decrement the
next pointer for the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer).
- 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;Copy to clipboard

The member function returns a pointer to the beginning of the
[output buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer).

### `basic_streambuf::pbump`

    void pbump(int count);Copy to clipboard

The member function adds `count` to the next pointer for the
[output buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer).

### `basic_streambuf::pos_type`

    typedef typename traits_type::pos_type pos_type;Copy to clipboard

The type is a synonym for
`traits_type::pos_type`.

### `basic_streambuf::pptr`

    char_type *pptr() const;Copy to clipboard

The member function returns a pointer to the next element of the
[output buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer).

### `basic_streambuf::pubimbue`

    locale pubimbue(const locale& loc);Copy to clipboard

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);Copy to clipboard

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);Copy to clipboard

The member function returns
`seekpos(sp, which)`.

### `basic_streambuf::pubsetbuf`

    basic_streambuf *pubsetbuf(char_type *buffer, streamsize count);Copy to clipboard

The member function returns
`setbuf(buffer, count)`.

### `basic_streambuf::pubsync`

    int pubsync();Copy to clipboard

The member function returns
`sync()`.

### `basic_streambuf::sbumpc`

    int_type sbumpc();Copy to clipboard

If a [read position](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#read%20position) is available,
the member function returns
`traits_type::to_int_type(
*gptr())`
and increments the next pointer for the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer).
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);Copy to clipboard

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);Copy to clipboard

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);Copy to clipboard

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);Copy to clipboard

The member function stores `gbeg` in the beginning pointer,
`gnext` in the next pointer,
and `gend` in the end pointer for the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer).

### `basic_streambuf::setp`

    void setp(char_type *pbeg, char_type *pend);Copy to clipboard

The member function stores `pbeg` in the beginning pointer,
`pbeg` in the next pointer,
and `pend` in the end pointer for the
[output buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer).

### `basic_streambuf::sgetc`

    int_type sgetc();Copy to clipboard

If a [read position](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#read%20position) 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);Copy to clipboard

The member function returns
`xsgetn(ptr, count)`.

### `basic_streambuf::showmanyc`

    virtual streamsize showmanyc();Copy to clipboard

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();Copy to clipboard

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);Copy to clipboard

If a [putback position](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#putback%20position) is available
and `ch` compares equal to the character stored in that position,
the member function decrements the next pointer for the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer) and returns
`traits_type::to_int_type(ch)`.
Otherwise, it returns
`pbackfail(ch)`.

### `basic_streambuf::sputc`

    int_type sputc(char_type ch);Copy to clipboard

If a [write position](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#write%20position) is available,
the member function stores `ch` in the write position,
increments the next pointer for the
[output buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer), and returns
`traits_type::to_int_type(ch)`.
Otherwise, it returns
`overflow(ch)`.

### `basic_streambuf::sputn`

    streamsize sputn(const char_type *ptr, streamsize count);Copy to clipboard

The member function returns
`xsputn(ptr, count)`.

### `basic_streambuf::stossc`

    void stossc(); [optional]Copy to clipboard

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

### `basic_streambuf::sungetc`

    int_type sungetc();Copy to clipboard

If a [putback position](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#putback%20position) is available,
the member function decrements the next pointer for the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer) and returns
`traits_type::to_int_type(
*gptr())`.
Otherwise it returns
`pbackfail()`.

### `basic_streambuf::sync`

    virtual int sync();Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer).
It does *not* involve putting back any elements between the next
and end pointers for the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer).
If the function cannot succeed, it returns -1.
The default behavior is to return zero.

### `basic_streambuf::traits_type`

    typedef Tr traits_type;Copy to clipboard

The type is a synonym for the template parameter `Tr`.

### `basic_streambuf::uflow`

    virtual int_type uflow();Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#read%20position) is available,
it takes `ch` as the element stored in the read position
and advances the next pointer for the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer).
- 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();Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#read%20position) 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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer), 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);Copy to clipboard

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);Copy to clipboard

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;Copy to clipboard

The type is a synonym for template class
[`basic_streambuf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#basic_streambuf), specialized
for elements of type *char* with default
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits).

## `wstreambuf`

    typedef basic_streambuf<wchar_t, char_traits<wchar_t> >
        wstreambuf;Copy to clipboard

The type is a synonym for template class
[`basic_streambuf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#basic_streambuf), specialized
for elements of type `wchar_t` with default
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits).

* * *

See also the
**[Table of Contents](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#Table%20of%20Contents)** and the
**[Index](https://docs.qualcomm.com/doc/80-N3040-23/topic/_cpp_index.html)**.

*[Copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_pjp.html) © 1992-2006by P.J. Plauger. All rights reserved.*

<!--V5.01:1566-->

Last Published: Oct 06, 2026

Previous Topic
 
<stdlib.h></stdlib.h> Next Topic

<string.h></string.h>