# std::basic_stringbuf<CharT,Traits,Allocator>::overflow

> C++ Atlas: `cppatlas.com/w/cpp/io/basic_stringbuf/overflow` | Source: https://en.cppreference.com/w/cpp/io/basic_stringbuf/overflow | Domain: Input/output

Appends the character c to the output character sequence.

## Official Specification Summary (cppreference)

```cpp
protected:
virtual int_type overflow( int_type c = Traits::eof() );
```

Appends the character `c` to the output character sequence.

If `c` is the end-of-file indicator (`traits::eq_int_type(c, traits::eof()) == true`), then there is no character to append. The function does nothing and returns an unspecified value other than `traits::eof()`.

Otherwise, if the output sequence has a write position available or this function can successfully make a write position available, then calls `sputc(c)` and returns `c`.

This function can make a write position available if the `std::stringbuf` is open for output (`(mode & ios_base::out) != 0`): in this case, it reallocates (or initially allocates) the buffer big enough to hold the entire current buffer plus at least one more character. If the `std::stringbuf` is also open for input (`(mode & ios_base::in) != 0`), then `overflow` also increases the size of the get area by moving `egptr()` to point just past the new write position.

### Parameters

- `c` - the character to store in the put area

### Return value

`Traits::eof()` to indicate failure, `c` if the character `c` was successfully appended, or some value other than `Traits::eof()` if called with `Traits::eof()` as the argument.

### Notes

This function is different from a typical `overflow()` which moves the contents of the buffer to the associated character sequence because for a `std::basic_stringbuf`, the buffer and the associated sequence are one and the same.

### Example

In the implementation used to execute this example (e.g. GCC-4.9), `overflow()` over-allocates the put area to 512 bytes: a call to `str()` would only return the four initialized bytes, but the next 508 calls to `sputc()` would not require new calls to `overflow()`.

```cpp
#include <sstream>
#include <iostream>

struct mybuf : std::stringbuf
{
    mybuf(const std::string& new_str,
          std::ios_base::openmode which = std::ios_base::in | std::ios_base::out)
        : std::stringbuf(new_str, which) {}

    int_type overflow(int_type c = EOF) override
    {
        std::cout << "stringbuf::overflow('" << char(c) << "') called\n"
                  << "Before: size of get area: " << egptr() - eback() << '\n'
                  << "        size of put area: " << epptr() - pbase() << '\n';

        int_type ret = std::stringbuf::overflow(c);

        std::cout << "After : size of get area: " << egptr() - eback() << '\n'
                  << "        size of put area: " << epptr() - pbase() << '\n';

        return ret;
    }
};

int main()
{
    std::cout << "read-write stream:\n";
    mybuf sbuf("   "); // read-write stream
    std::iostream stream(&sbuf);
    stream << 1234;
    std::cout << sbuf.str() << '\n';

    std::cout << "\nread-only stream:\n";
    mybuf ro_buf("   ", std::ios_base::in); // read-only stream
    std::iostream ro_stream(&ro_buf);
    ro_stream << 1234;

    std::cout << "\nwrite-only stream:\n";
    mybuf wr_buf("   ", std::ios_base::out); // write-only stream
    std::iostream wr_stream(&wr_buf);
    wr_stream << 1234;
}
```

Possible output:

```text
read-write stream:
stringbuf::overflow('4') called
Before: size of get area: 3
        size of put area: 3
After : size of get area: 4
        size of put area: 512
1234

read-only stream:
stringbuf::overflow('1') called
Before: size of get area: 3
        size of put area: 0
After : size of get area: 3
        size of put area: 0

write-only stream:
stringbuf::overflow('4') called
Before: size of get area: 0
        size of put area: 3
After : size of get area: 0
        size of put area: 512
```

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

| DR | Applied to | Behavior as published | Correct behavior |
| --- | --- | --- | --- |
| LWG 169 | C++98 | the buffer (re)allocated could only hold one extra character | allows more extra characters |
| LWG 432 | C++98 | `overflow` moved `epptr()` to point just past the new write position if the `std::stringbuf` is open for input | it is not moved |

### See also

- [`overflow`](https://en.cppreference.com/w/cpp/io/basic_streambuf/overflow) [virtual]: writes characters to the associated output sequence from the put area (virtual protected member function of `std::basic_streambuf<CharT,Traits>`)
- [`underflow`](https://en.cppreference.com/w/cpp/io/basic_stringbuf/underflow) [virtual]: returns the next character available in the input sequence (virtual protected member function)

---
Attribution: content from https://en.cppreference.com/w/cpp/io/basic_stringbuf/overflow (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.