30 Input/output library [input.output]

30.6 Stream buffers [stream.buffers]

30.6.1 Header <streambuf> synopsis [streambuf.syn]

namespace std {
  template <class charT, class traits = char_traits<charT>>
    class basic_streambuf;
  using streambuf  = basic_streambuf<char>;
  using wstreambuf = basic_streambuf<wchar_t>;
}
1
#
The header <streambuf> defines types that control input from and output to character sequences.

30.6.2 Stream buffer requirements [streambuf.reqts]

1
#
Stream buffers can impose various constraints on the sequences they control.
Some constraints are:
  • (1.1)
    The controlled input sequence can be not readable.
  • (1.2)
    The controlled output sequence can be not writable.
  • (1.3)
    The controlled sequences can be associated with the contents of other representations for character sequences, such as external files.
  • (1.4)
    The controlled sequences can support operations directly to or from associated sequences.
  • (1.5)
    The controlled sequences can impose limitations on how the program can read characters from a sequence, write characters to a sequence, put characters back into an input sequence, or alter the stream position.
2
#
Each sequence is characterized by three pointers which, if non-null, all point into the same charT array object.
The array object represents, at any moment, a (sub)sequence of characters from the sequence.
Operations performed on a sequence alter the values stored in these pointers, perform reads and writes directly to or from associated sequences, and alter “the stream position” and conversion state as needed to maintain this subsequence relationship.
The three pointers are:
  • (2.1)
    the beginning pointer, or lowest element address in the array (called xbeg here);
  • (2.2)
    the next pointer, or next element address that is a current candidate for reading or writing (called xnext here);
  • (2.3)
    the end pointer, or first element address beyond the end of the array (called xend here).
3
#
The following semantic constraints shall always apply for any set of three pointers for a sequence, using the pointer names given immediately above:
  • (3.1)
    If xnext is not a null pointer, then xbeg and xend shall also be non-null pointers into the same charT array, as described above; otherwise, xbeg and xend shall also be null.
  • (3.2)
    If xnext is not a null pointer and xnext < xend for an output sequence, then a write position is available.
    In this case, *xnext shall be assignable as the next element to write (to put, or to store a character value, into the sequence).
  • (3.3)
    If xnext is not a null pointer and xbeg < xnext for an input sequence, then a putback position is available.
    In this case, xnext[-1] shall have a defined value and is the next (preceding) element to store a character that is put back into the input sequence.
  • (3.4)
    If xnext is not a null pointer and xnext < xend for an input sequence, then a read position is available.
    In this case, *xnext shall have a defined value and is the next element to read (to get, or to obtain a character value, from the sequence).

30.6.3 Class template basic_­streambuf [streambuf]

namespace std {
  template <class charT, class traits = char_traits<charT>>
  class basic_streambuf {
  public:
    using char_type   = charT;
    using int_type    = typename traits::int_type;
    using pos_type    = typename traits::pos_type;
    using off_type    = typename traits::off_type;
    using traits_type = traits;

    virtual ~basic_streambuf();

    // [streambuf.locales], locales
    locale   pubimbue(const locale& loc);
    locale   getloc() const;

    // [streambuf.buffer], buffer and positioning
    basic_streambuf* pubsetbuf(char_type* s, streamsize n);
    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();

    // Get and put areas
    // [streambuf.pub.get], get area
    streamsize in_avail();
    int_type snextc();
    int_type sbumpc();
    int_type sgetc();
    streamsize sgetn(char_type* s, streamsize n);

    // [streambuf.pub.pback], putback
    int_type sputbackc(char_type c);
    int_type sungetc();

    // [streambuf.pub.put], put area
    int_type   sputc(char_type c);
    streamsize sputn(const char_type* s, streamsize n);

  protected:
    basic_streambuf();
    basic_streambuf(const basic_streambuf& rhs);
    basic_streambuf& operator=(const basic_streambuf& rhs);

    void swap(basic_streambuf& rhs);

    // [streambuf.get.area], get area access
    char_type* eback() const;
    char_type* gptr()  const;
    char_type* egptr() const;
    void       gbump(int n);
    void       setg(char_type* gbeg, char_type* gnext, char_type* gend);

    // [streambuf.put.area], put area access
    char_type* pbase() const;
    char_type* pptr() const;
    char_type* epptr() const;
    void       pbump(int n);
    void       setp(char_type* pbeg, char_type* pend);

    // [streambuf.virtuals], virtual functions
    // [streambuf.virt.locales], locales
    virtual void imbue(const locale& loc);

    // [streambuf.virt.buffer], buffer management and positioning
    virtual basic_streambuf* setbuf(char_type* s, streamsize n);
    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();

    // [streambuf.virt.get], get area
    virtual streamsize showmanyc();
    virtual streamsize xsgetn(char_type* s, streamsize n);
    virtual int_type   underflow();
    virtual int_type   uflow();

    // [streambuf.virt.pback], putback
    virtual int_type   pbackfail(int_type c = traits::eof());

    // [streambuf.virt.put], put area
    virtual streamsize xsputn(const char_type* s, streamsize n);
    virtual int_type   overflow(int_type c = traits::eof());
  };
}
1
#
The class template basic_­streambuf serves as an abstract base class for deriving various stream buffers whose objects each control two character sequences:

30.6.3.1 basic_­streambuf constructors [streambuf.cons]

basic_streambuf();
1
#
Effects: Constructs an object of class basic_­streambuf<charT, traits> and initializes:299
  • (1.1)
    all its pointer member objects to null pointers,
  • (1.2)
    the getloc() member to a copy the global locale, locale(), at the time of construction.
2
#
Remarks: Once the getloc() member is initialized, results of calling locale member functions, and of members of facets so obtained, can safely be cached until the next time the member imbue is called.
basic_streambuf(const basic_streambuf& rhs);
3
#
Effects: Constructs a copy of rhs.
4
#
Postconditions:
  • (4.1)
    eback() == rhs.eback()
  • (4.2)
    gptr() == rhs.gptr()
  • (4.3)
    egptr() == rhs.egptr()
  • (4.4)
    pbase() == rhs.pbase()
  • (4.5)
    pptr() == rhs.pptr()
  • (4.6)
    epptr() == rhs.epptr()
  • (4.7)
    getloc() == rhs.getloc()
~basic_streambuf();
5
#
Effects: None.
299)
The default constructor is protected for class basic_­streambuf to assure that only objects for classes derived from this class may be constructed.

30.6.3.2 basic_­streambuf public member functions [streambuf.members]

30.6.3.2.1 Locales [streambuf.locales]

locale pubimbue(const locale& loc);
1
#
Postconditions: loc == getloc().
2
#
Effects: Calls imbue(loc).
3
#
Returns: Previous value of getloc().
locale getloc() const;
4
#
Returns: If pubimbue() has ever been called, then the last value of loc supplied, otherwise the current global locale, locale(), in effect at the time of construction.
If called after pubimbue() has been called but before pubimbue has returned (i.e., from within the call of imbue()) then it returns the previous value.

30.6.3.2.2 Buffer management and positioning [streambuf.buffer]

basic_streambuf* pubsetbuf(char_type* s, streamsize n);
1
#
Returns: setbuf(s, n).
pos_type pubseekoff(off_type off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out);
2
#
Returns: seekoff(off, way, which).
pos_type pubseekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out);
3
#
Returns: seekpos(sp, which).
int pubsync();
4
#
Returns: sync().

30.6.3.2.3 Get area [streambuf.pub.get]

streamsize in_avail();
1
#
Returns: If a read position is available, returns egptr() - gptr().
Otherwise returns showmanyc() ([streambuf.virt.get]).
int_type snextc();
2
#
Effects: Calls sbumpc().
3
#
Returns: If that function returns traits​::​eof(), returns traits​::​eof().
Otherwise, returns sgetc().
int_type sbumpc();
4
#
Returns: If the input sequence read position is not available, returns uflow().
Otherwise, returns traits​::​to_­int_­type(*gptr()) and increments the next pointer for the input sequence.
int_type sgetc();
5
#
Returns: If the input sequence read position is not available, returns underflow().
Otherwise, returns traits​::​to_­int_­type(*gptr()).
streamsize sgetn(char_type* s, streamsize n);
6
#
Returns: xsgetn(s, n).

30.6.3.2.4 Putback [streambuf.pub.pback]

int_type sputbackc(char_type c);
1
#
Returns: If the input sequence putback position is not available, or if traits​::​eq(c, gptr()[-1]) is false, returns pbackfail(traits​::​to_­int_­type(c)).
Otherwise, decrements the next pointer for the input sequence and returns traits​::​to_­int_­type(*gptr()).
int_type sungetc();
2
#
Returns: If the input sequence putback position is not available, returns pbackfail().
Otherwise, decrements the next pointer for the input sequence and returns traits​::​to_­int_­type(*gptr()).

30.6.3.2.5 Put area [streambuf.pub.put]

int_type sputc(char_type c);
1
#
Returns: If the output sequence write position is not available, returns overflow(traits​::​to_­int_­type(c)).
Otherwise, stores c at the next pointer for the output sequence, increments the pointer, and returns traits​::​to_­int_­type(c).
streamsize sputn(const char_type* s, streamsize n);
2
#
Returns: xsputn(s, n).

30.6.3.3 basic_­streambuf protected member functions [streambuf.protected]

30.6.3.3.1 Assignment [streambuf.assign]

basic_streambuf& operator=(const basic_streambuf& rhs);
1
#
Effects: Assigns the data members of rhs to *this.
2
#
Postconditions:
  • (2.1)
    eback() == rhs.eback()
  • (2.2)
    gptr() == rhs.gptr()
  • (2.3)
    egptr() == rhs.egptr()
  • (2.4)
    pbase() == rhs.pbase()
  • (2.5)
    pptr() == rhs.pptr()
  • (2.6)
    epptr() == rhs.epptr()
  • (2.7)
    getloc() == rhs.getloc()
3
#
Returns: *this.
void swap(basic_streambuf& rhs);
4
#
Effects: Swaps the data members of rhs and *this.

30.6.3.3.2 Get area access [streambuf.get.area]

char_type* eback() const;
1
#
Returns: The beginning pointer for the input sequence.
char_type* gptr() const;
2
#
Returns: The next pointer for the input sequence.
char_type* egptr() const;
3
#
Returns: The end pointer for the input sequence.
void gbump(int n);
4
#
Effects: Adds n to the next pointer for the input sequence.
void setg(char_type* gbeg, char_type* gnext, char_type* gend);
5
#
Postconditions: gbeg == eback(), gnext == gptr(), and gend == egptr().

30.6.3.3.3 Put area access [streambuf.put.area]

char_type* pbase() const;
1
#
Returns: The beginning pointer for the output sequence.
char_type* pptr() const;
2
#
Returns: The next pointer for the output sequence.
char_type* epptr() const;
3
#
Returns: The end pointer for the output sequence.
void pbump(int n);
4
#
Effects: Adds n to the next pointer for the output sequence.
void setp(char_type* pbeg, char_type* pend);
5
#
Postconditions: pbeg == pbase(), pbeg == pptr(), and pend == epptr().

30.6.3.4 basic_­streambuf virtual functions [streambuf.virtuals]

30.6.3.4.1 Locales [streambuf.virt.locales]

void imbue(const locale&);
1
#
Effects: Change any translations based on locale.
2
#
Remarks: Allows the derived class to be informed of changes in locale at the time they occur.
Between invocations of this function a class derived from streambuf can safely cache results of calls to locale functions and to members of facets so obtained.
3
#
Default behavior: Does nothing.

30.6.3.4.2 Buffer management and positioning [streambuf.virt.buffer]

basic_streambuf* setbuf(char_type* s, streamsize n);
1
#
Effects: Influences stream buffering in a way that is defined separately for each class derived from basic_­streambuf in this Clause ([stringbuf.virtuals], [filebuf.virtuals]).
2
#
Default behavior: Does nothing.
Returns this.
pos_type seekoff(off_type off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out);
3
#
Effects: Alters the stream positions within one or more of the controlled sequences in a way that is defined separately for each class derived from basic_­streambuf in this Clause ([stringbuf.virtuals], [filebuf.virtuals]).
4
#
Default behavior: Returns pos_­type(off_­type(-1)).
pos_type seekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out);
5
#
Effects: Alters the stream positions within one or more of the controlled sequences in a way that is defined separately for each class derived from basic_­streambuf in this Clause ([stringbuf], [filebuf]).
6
#
Default behavior: Returns pos_­type(off_­type(-1)).
int sync();
7
#
Effects: Synchronizes the controlled sequences with the arrays.
That is, if pbase() is non-null the characters between pbase() and pptr() are written to the controlled sequence.
The pointers may then be reset as appropriate.
8
#
Returns: -1 on failure.
What constitutes failure is determined by each derived class ([filebuf.virtuals]).
9
#
Default behavior: Returns zero.

30.6.3.4.3 Get area [streambuf.virt.get]

streamsize showmanyc();300
1
#
Returns: An estimate of the number of characters available in the sequence, or -1.
If it returns a positive value, then successive calls to underflow() will not return traits​::​eof() until at least that number of characters have been extracted from the stream.
If showmanyc() returns -1, then calls to underflow() or uflow() will fail.301
2
#
Default behavior: Returns zero.
3
#
Remarks: Uses traits​::​eof().
streamsize xsgetn(char_type* s, streamsize n);
4
#
Effects: Assigns up to n characters to successive elements of the array whose first element is designated by s.
The characters assigned are read from the input sequence as if by repeated calls to sbumpc().
Assigning stops when either n characters have been assigned or a call to sbumpc() would return traits​::​eof().
5
#
Returns: The number of characters assigned.302
6
#
Remarks: Uses traits​::​eof().
int_type underflow();
7
#
Remarks: The public members of basic_­streambuf call this virtual function only if gptr() is null or gptr() >= egptr()
8
#
Returns: traits​::​to_­int_­type(c), where c is the first character of the pending sequence, without moving the input sequence position past it.
If the pending sequence is null then the function returns traits​::​eof() to indicate failure.
9
#
The pending sequence of characters is defined as the concatenation of
  • (9.1)
    the empty sequence if gptr() is null, otherwise the characters in [gptr(), egptr()), followed by
  • (9.2)
    some (possibly empty) sequence of characters read from the input sequence.
10
#
The result character is the first character of the pending sequence if it is non-empty, otherwise the next character that would be read from the input sequence.
11
#
The backup sequence is the empty sequence if eback() is null, otherwise the characters in [eback(), gptr()).
12
#
Effects: The function sets up the gptr() and egptr() such that if the pending sequence is non-empty, then egptr() is non-null and the characters in [gptr(), egptr()) are the characters in the pending sequence, otherwise either gptr() is null or gptr() == egptr().
13
#
If eback() and gptr() are non-null then the function is not constrained as to their contents, but the “usual backup condition” is that either
  • (13.1)
    the backup sequence contains at least gptr() - eback() characters, in which case the characters in [eback(), gptr()) agree with the last gptr() - eback() characters of the backup sequence, or
  • (13.2)
    the characters in [gptr() - n, gptr()) agree with the backup sequence (where n is the length of the backup sequence).
14
#
Default behavior: Returns traits​::​eof().
int_type uflow();
15
#
Requires: The constraints are the same as for underflow(), except that the result character shall be transferred from the pending sequence to the backup sequence, and the pending sequence shall not be empty before the transfer.
16
#
Default behavior: Calls underflow().
If underflow() returns traits​::​eof(), returns traits​::​eof().
Otherwise, returns the value of traits​::​to_­int_­type(*gptr()) and increment the value of the next pointer for the input sequence.
17
#
Returns: traits​::​eof() to indicate failure.
300)
The morphemes of showmanyc are “es-how-many-see”, not “show-manic”.
301)
underflow or uflow might fail by throwing an exception prematurely.
The intention is not only that the calls will not return eof() but that they will return “immediately”.
302)
Classes derived from basic_­streambuf can provide more efficient ways to implement xsgetn() and xsputn() by overriding these definitions from the base class.

30.6.3.4.4 Putback [streambuf.virt.pback]

int_type pbackfail(int_type c = traits::eof());
1
#
Remarks: The public functions of basic_­streambuf call this virtual function only when gptr() is null, gptr() == eback(), or traits​::​eq(traits​::​to_­char_­type(c), gptr()[-1]) returns false.
Other calls shall also satisfy that constraint.
The pending sequence is defined as for underflow(), with the modifications that
  • (1.1)
    If traits​::​eq_­int_­type(c, traits​::​eof()) returns true, then the input sequence is backed up one character before the pending sequence is determined.
  • (1.2)
    If traits​::​eq_­int_­type(c, traits​::​eof()) returns false, then c is prepended.
    Whether the input sequence is backed up or modified in any other way is unspecified.
2
#
Postconditions: On return, the constraints of gptr(), eback(), and pptr() are the same as for underflow().
3
#
Returns: traits​::​eof() to indicate failure.
Failure may occur because the input sequence could not be backed up, or if for some other reason the pointers could not be set consistent with the constraints.
pbackfail() is called only when put back has really failed.
4
#
Returns some value other than traits​::​eof() to indicate success.
5
#
Default behavior: Returns traits​::​eof().

30.6.3.4.5 Put area [streambuf.virt.put]

streamsize xsputn(const char_type* s, streamsize n);
1
#
Effects: Writes up to n characters to the output sequence as if by repeated calls to sputc(c).
The characters written are obtained from successive elements of the array whose first element is designated by s.
Writing stops when either n characters have been written or a call to sputc(c) would return traits​::​eof().
It is unspecified whether the function calls overflow() when pptr() == epptr() becomes true or whether it achieves the same effects by other means.
2
#
Returns: The number of characters written.
int_type overflow(int_type c = traits::eof());
3
#
Effects: Consumes some initial subsequence of the characters of the pending sequence.
The pending sequence is defined as the concatenation of
  • (3.1)
    the empty sequence if pbase() is not null, otherwise the pptr() - pbase() characters beginning at pbase(), followed by
  • (3.2)
    the empty sequence if traits​::​eq_­int_­type(c, traits​::​eof()) returns true, otherwise the sequence consisting of c.
4
#
Remarks: The member functions sputc() and sputn() call this function in case that no room can be found in the put buffer enough to accommodate the argument character sequence.
5
#
Requires: Every overriding definition of this virtual function shall obey the following constraints:
  1. 1.
    The effect of consuming a character on the associated output sequence is specified303
  2. 2.
    Let r be the number of characters in the pending sequence not consumed.
    If r is nonzero then pbase() and pptr() shall be set so that: pptr() - pbase() == r and the r characters starting at pbase() are the associated output stream.
    In case r is zero (all characters of the pending sequence have been consumed) then either pbase() is set to nullptr, or pbase() and pptr() are both set to the same non-null value.
  3. 3.
    The function may fail if either appending some character to the associated output stream fails or if it is unable to establish pbase() and pptr() according to the above rules.
6
#
Returns: traits​::​eof() or throws an exception if the function fails.
Otherwise, returns some value other than traits​::​eof() to indicate success.304
7
#
Default behavior: Returns traits​::​eof().
303)
That is, for each class derived from an instance of basic_­streambuf in this Clause ([stringbuf], [filebuf]), a specification of how consuming a character effects the associated output sequence is given.
There is no requirement on a program-defined class.
304)
Typically, overflow returns c to indicate success, except when traits​::​eq_­int_­type(c, traits​::​eof()) returns true, in which case it returns traits​::​not_­eof(c).