# Iostreams

> An iostream is a formatting layer on top of a buffer layer, with a state word that records what went wrong. Most iostream bugs come from reading the state bits wrong, from sticky formatting, or from mixing the formatted and unformatted halves of the interface.

- **Source:** C++ Atlas (https://cppatlas.com/topics/iostreams)
- **Track:** Library utilities
- **Estimated reading time:** 13 minutes
- **ISO C++ clauses:** [iostate.flags] (https://eel.is/c++draft/iostate.flags), [istream.formatted] (https://eel.is/c++draft/istream.formatted), [istream.unformatted] (https://eel.is/c++draft/istream.unformatted), [ostream.formatted] (https://eel.is/c++draft/ostream.formatted), [facet.num.get.virtuals] (https://eel.is/c++draft/facet.num.get.virtuals), [iostream.objects.overview] (https://eel.is/c++draft/iostream.objects.overview), [syncstream] (https://eel.is/c++draft/syncstream), [spanstream] (https://eel.is/c++draft/spanstream)
- **cppreference links:** [std::basic_ios](https://en.cppreference.com/w/cpp/io/basic_ios), [std::basic_istream](https://en.cppreference.com/w/cpp/io/basic_istream), [std::basic_streambuf](https://en.cppreference.com/w/cpp/io/basic_streambuf), [std::ios_base::sync_with_stdio](https://en.cppreference.com/w/cpp/io/ios_base/sync_with_stdio), [std::basic_osyncstream](https://en.cppreference.com/w/cpp/io/basic_osyncstream), [std::basic_spanstream](https://en.cppreference.com/w/cpp/io/basic_spanstream), [std::setw](https://en.cppreference.com/w/cpp/io/manip/setw), [std::basic_ifstream](https://en.cppreference.com/w/cpp/io/basic_ifstream)
- **Prerequisites:** strings-and-string-view, exceptions-and-stack-unwinding

## The one idea

An iostream has two halves. The **stream** (`istream`, `ostream`) converts between values and characters and remembers the outcome. The **stream buffer** (`streambuf`) moves characters to and from a source: a file, a string, a memory span, or the C `stdout`. The stream owns a formatting state (base, width, fill, locale) and a state word with the bits `eofbit`, `failbit`, and `badbit`. Everything surprising about iostreams is a consequence of one of those three things: formatting state that persists, state bits with narrow meanings, and the buffer layer underneath.

```text
 ostream / istream / iostream      formatting, state bits, locale
          |
       basic_ios                   holds the pointer to a streambuf
          |
     streambuf                     buffering and transport
   /     |      \      \
filebuf stringbuf spanbuf syncbuf
```

> **Mental model.** The bits are not an error code. `failbit` means the last operation did not do its job, `eofbit` means the stream ran into the end while trying, and `badbit` means the buffer layer itself broke. A stream in the failed state ignores every later operation until you call `clear()`.

## The state bits and the loop idiom

`good()` is true only when no bit is set. `fail()` is true when `failbit` or `badbit` is set. `eof()` reports `eofbit` alone, and `bad()` reports `badbit` alone. A stream converts to `bool` as `!fail()`, so `if (in)` and `while (in >> x)` test whether the last extraction worked.

The common bug is testing `eof()` before reading, because `eofbit` is set only after an attempt to read past the end, and an attempt can also succeed. Reading `42` from a stream that holds exactly `"42"` sets `eofbit` because the number parser needed one more character to know it was done, yet the read succeeded.

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

int main() {
  std::istringstream in("1 2 3\n");
  int x;
  while (!in.eof()) {            // bug: eof() is still false after reading 3
    in >> x;                     // fails on the trailing newline, x is untouched
    std::cout << x << ' ';       // prints 1 2 3 3
  }
}
```

The correct form puts the extraction itself in the condition.

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

int main() {
  std::istringstream in("1 2 3\n");
  int x;
  while (in >> x) std::cout << x << ' ';   // 1 2 3

  std::istringstream lines("a\nb\n");
  std::string line;
  while (std::getline(lines, line)) std::cout << line << ';';  // a;b;
}
```

When an extraction fails because the text is not a number, `failbit` is set and, since C++11, the target gets the value 0. If the sentry fails instead, because the stream is already in a failed state or because only whitespace remained, the target is left alone, which is why the buggy loop above repeats its last value. An out-of-range value stores the largest or smallest representable value and sets `failbit`. Extracting `"-1"` into an unsigned type is accepted and wraps, as `strtoull` would do, without setting any bit.

After a failure, call `in.clear()` to reset the state and then deal with the offending characters, usually with `in.ignore(...)`. Note also that `str("...")` on a string stream replaces the contents but does not clear the state bits, so a stream that reached the end must be cleared as well as refilled.

> **Pitfall.** `while (!in.eof())` processes the last item twice on input that ends in a newline, and loops forever on malformed input because `failbit` is set while `eofbit` never is. Test the read, not the bit.

## Formatted versus unformatted input, and mixing the two

Formatted input (`operator>>`) first skips leading whitespace, then parses a value. Unformatted input (`get`, `getline`, `read`, `ignore`, `peek`) takes characters as they come, including whitespace, and `gcount()` reports how many characters the last unformatted call extracted. Both families construct a sentry object first, which checks the stream state and, for formatted input, skips whitespace.

The classic consequence is the leftover newline.

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

int main() {
  std::istringstream in("5\nhello\n");
  int n;
  std::string line;
  in >> n;                  // reads 5, leaves "\nhello\n"
  std::getline(in, line);   // reads up to the newline: line is empty
  std::getline(in, line);   // line is now "hello"
}
```

Either call `in.ignore(std::numeric_limits<std::streamsize>::max(), '\n')` after the numeric read, or read whole lines first and parse them with a string stream. The latter also gives you a per-line failure state.

Since C++20, extracting into a character array uses the array's size as the limit. Before that the unbounded `operator>>(char*)` was a buffer overflow waiting for a long word, and `std::setw` was the mitigation.

## Sticky and one-shot formatting

Most manipulators change the stream's formatting state permanently: `std::hex`, `std::fixed`, `std::setprecision`, `std::setfill`, `std::left`, `std::boolalpha`. One does not: **`std::setw` applies to the next formatted output and then resets to zero.** Width also never truncates; a string longer than the width prints in full.

```cpp
#include <iomanip>
#include <iostream>

int main() {
  std::cout << std::hex << std::setw(4) << std::setfill('0') << 255 << ' ' << 255 << '\n';
  // 00ff ff   hex and fill stay, width was used up by the first 255
  std::cout << 255 << '\n';  // ff: still hex, which is why code saves and restores flags
}
```

Because the state sticks to the stream object, a function that sets `std::hex` on a stream it was given changes later output of unrelated code. Save `std::ios_base::flags()` and restore them, or format into a temporary `std::ostringstream`. This stickiness is one of the reasons the newer `std::format` is easier to reason about.

## Speed and synchronization

`std::endl` writes a newline and flushes; `'\n'` only writes a newline. Flushing on every line costs a system call for each one when the output is a file or pipe. Use `'\n'`, and flush deliberately when you need output to appear before a crash or before a prompt.

Two settings commonly slow down `cin` and `cout`. By default the standard streams are **synchronized** with C stdio, so a program may mix `printf` and `cout` and get a sensible order, at the price of typically slower, less buffered access. Calling `std::ios::sync_with_stdio(false)` before any input or output removes that, and the streams use their own buffers. After that, mixing the two APIs on the same stream is no longer safe, and the standard's guarantee that concurrent use of the standard streams from several threads is not a data race applies only while synchronized. The second setting is that `cin` is tied to `cout`, meaning `cout` is flushed before every `cin` read. `std::cin.tie(nullptr)` removes that, which is fine unless you rely on a prompt appearing first.

```cpp
#include <iostream>

int main() {
  std::ios::sync_with_stdio(false);  // before the first I/O operation
  std::cin.tie(nullptr);             // do not flush cout before each read
  int x;
  while (std::cin >> x) std::cout << x * 2 << '\n';
}
```

Even in the synchronized case, the standard only says concurrent access is free of data races; characters from different threads can still interleave. C++20's `std::osyncstream` solves that: it wraps another stream, collects output in its own buffer, and transfers it to the target as one unit when `emit()` is called or the object is destroyed. Writes from different `osyncstream` objects to the same target do not interleave.

```cpp
#include <iostream>
#include <syncstream>

void log(int id) {
  std::osyncstream out(std::cout);   // buffered privately
  out << "worker " << id << " done\n";
}                                    // destroyed here: emitted as one block
```

## String streams, span streams, files, and locale

`std::istringstream`, `std::ostringstream`, and `std::stringstream` wrap a `std::string`. `str()` returns a copy of the content, which costs an allocation. C++23's `std::ispanstream`, `std::ospanstream`, and `std::spanstream` instead use a character buffer you own, with no allocation and no copy. You read the written part back with `span()`. An `ospanstream` does not add a null terminator, and writing past the end of the buffer sets `badbit`, so size the buffer for the worst case.

File streams take an open mode, and the combination decides whether the file is created, truncated, or must already exist.

| Mode | Meaning | C equivalent |
| --- | --- | --- |
| `in` | read, must exist | `"r"` |
| `out` or `out\|trunc` | write, create or truncate | `"w"` |
| `out\|app` | append writes at the end | `"a"` |
| `in\|out` | read and write, must exist, no truncation | `"r+"` |
| `in\|out\|trunc` | read and write, create or truncate | `"w+"` |

Add `binary` to avoid newline translation on platforms that have it. An `ofstream` always adds `out` to the mode you pass, and an `ifstream` always adds `in`. A failed open does not throw by default; it sets `failbit`, so test the stream after constructing it.

Each stream holds a `std::locale` that is copied from the global locale when the stream is constructed and decides how numbers are printed and parsed: decimal point, digit grouping, `boolalpha` names. This is why changing the global locale after a stream was built does not affect that stream, and why `imbue` exists.

Finally, a stream can be told to report failures by throwing. `in.exceptions(std::ios::failbit)` makes every transition to the failed state throw `std::ios_base::failure`, which turns the end of the `while (in >> x)` loop into an exception. That is rarely what you want for input, so the usual mask is `badbit` only, or nothing. An exception thrown from inside a library formatted operation, for example by the stream buffer, is caught by the stream, recorded as `badbit`, and rethrown only if `badbit` is in the mask. A user-written `operator<<` is an ordinary function and is not wrapped this way.

## What to remember

- Streams are a formatting layer over a `streambuf`; the formatting state and the state bits live on the stream.
- `failbit` means the operation failed, `eofbit` means it hit the end, `badbit` means the buffer broke. A stream converts to `bool` as `!fail()`.
- Put the read in the loop condition: `while (in >> x)` and `while (std::getline(in, s))`. Never loop on `eof()`.
- A successful read can set `eofbit`, and a sentry failure leaves the target unchanged.
- `setw` is one-shot and never truncates; hex, fill, precision, and alignment stay until changed.
- `>>` leaves the newline behind, so `getline` after it returns an empty line.
- `'\n'` does not flush and `endl` does; `sync_with_stdio(false)` and `cin.tie(nullptr)` speed up the standard streams, at the cost of the synchronization guarantees.
- `std::osyncstream` (C++20) keeps a thread's output together; `std::spanstream` (C++23) streams over your own buffer.
- File modes decide creation and truncation; a failed open sets `failbit` and does not throw.
- `exceptions(failbit)` turns the end of a read loop into an exception.

## Concept Map Outline

- **Iostreams:** Formatting streams over stream buffers, with a state word and persistent formatting state.
  - **Layers:** Streams format and track state; stream buffers move characters.
    - **basic_ios and streambuf:** basic_ios holds a pointer to a streambuf that does the actual buffering and transport.
    - **Buffer types:** filebuf, stringbuf, spanbuf and syncbuf are the standard stream buffers.
    - **Locale per stream:** Each stream copies the global locale at construction and uses it for number formatting.
  - **State bits:** A state word records what went wrong with the last operation.
    - **failbit:** The operation did not succeed; it makes the stream convert to false.
    - **eofbit:** A read hit the end of input; it can be set even when the read succeeded.
    - **badbit:** The stream buffer lost integrity; a parse error never sets it.
    - **while (in >> x):** Put the extraction in the condition; looping on eof() repeats the last value.
    - **clear():** A failed stream ignores operations until clear(); str() does not reset the bits.
  - **Input styles:** Formatted and unformatted input behave differently around whitespace.
    - **Formatted operator>>:** Skips leading whitespace and parses a value; failure stores 0 for numbers.
    - **Unformatted functions:** get, getline, read, ignore and peek take characters as they are.
    - **Newline after >>:** operator>> leaves the newline, so a following getline returns an empty line.
  - **Output formatting:** Manipulators change formatting state, mostly permanently.
    - **Sticky manipulators:** hex, fixed, setfill, setprecision and alignment persist until changed.
    - **setw is one-shot:** Width applies to the next formatted output only and never truncates.
    - **endl versus newline:** endl writes a newline and flushes; '\n' does not flush.
  - **Performance and threads:** Standard streams are synchronized with C stdio by default.
    - **sync_with_stdio(false):** Call before any I/O; it drops C stdio mixing and the concurrent-access guarantee.
    - **cin.tie(nullptr):** Stops cout being flushed before every cin read.
    - **osyncstream:** C++20 stream that emits its buffered text to the target as one unit.
  - **Streams over memory and files:** Memory and file streams share the stream interface.
    - **String streams:** str() returns a copy and does not clear the state bits.
    - **spanstream (C++23):** Streams over a caller-owned buffer with no allocation; span() shows the written part.
    - **File open modes:** in|out requires an existing file and keeps content; out truncates; app appends.
    - **Exceptions mask:** exceptions(failbit) throws ios_base::failure, including at the end of a read loop.

## Standardese Quiz Questions

### Question 1 [warmup] ([ostream.formatted.reqmts])

What does this program print?

```cpp
#include <iomanip>
#include <iostream>

int main() {
  std::cout << std::hex << std::setw(4) << std::setfill('0') << 255 << ' ' << 255 << '\n';
}
```

A. `00ff ff`
B. `00ff 00ff`
C. `00ff 255`
D. `ff ff`

**Answer (A):** `00ff ff`

**Why:** `std::setw` applies only to the next formatted output and is then reset to zero, while `std::hex` and `std::setfill` stay in effect. The second `255` therefore prints in hex with no padding. The tempting `00ff 00ff` would need `setw(4)` repeated.

### Question 2 [warmup] ([string.io], [istream.formatted.arithmetic])

What does this program print?

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

int main() {
  std::istringstream in("5\nhello\n");
  int n;
  std::string line;
  in >> n;
  std::getline(in, line);
  std::cout << '[' << line << "]\n";
}
```

A. `[hello]`
B. `[5]`
C. `[]`
D. `[\n]`

**Answer (C):** `[]`

**Why:** `operator>>` for an integer stops at the newline and leaves it in the stream. `std::getline` then reads up to that newline, producing an empty string, and consumes the newline. Discard the rest of the line with `in.ignore(...)` before calling `getline`.

### Question 3 [warmup] ([facet.num.get.virtuals], [istream.formatted.arithmetic], [iostate.flags])

What does this program print?

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

int main() {
  std::istringstream in("abc");
  int x = 7;
  in >> x;
  std::cout << x << ' ' << in.eof() << ' ' << in.fail() << ' ' << in.bad() << '\n';
}
```

A. `7 0 1 0`
B. `0 1 1 0`
C. `0 0 1 1`
D. `0 0 1 0`

**Answer (D):** `0 0 1 0`

**Why:** The characters do not form a number, so the conversion fails: `failbit` is set and, since C++11, the value 0 is stored. The stream was not at the end of input when the failure was detected, so `eofbit` is clear. `badbit` is reserved for loss of integrity of the stream buffer, not for a parse error, and the old value 7 is not preserved.

### Question 4 [tricky] ([istream.formatted.arithmetic], [istream.sentry], [iostate.flags])

What does this program print?

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

int main() {
  std::istringstream in("1 2 3\n");
  int x;
  while (!in.eof()) {
    in >> x;
    std::cout << x << ' ';
  }
  std::cout << '\n';
}
```

A. `1 2 3 3 `
B. `1 2 3 `
C. `1 2 3 0 `
D. `1 2 3 ` and then it loops forever

**Answer (A):** `1 2 3 3 `

**Why:** After reading `3` the stream is not at EOF, because the newline is still unread, so `eof()` is false. The next `>>` skips the whitespace, reaches the end, and sets `eofbit` and `failbit` without storing anything, so `x` keeps the old value 3 and it is printed again. Testing `eof()` before reading is the bug; test the extraction itself with `while (in >> x)`.

### Question 5 [tricky] ([facet.num.get.virtuals], [iostate.flags])

What does this program print?

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

int main() {
  std::istringstream in("42");
  int x = 0;
  in >> x;
  std::cout << x << ' ' << in.eof() << ' ' << in.fail() << '\n';
}
```

A. `42 0 0`
B. `42 1 0`
C. `42 1 1`
D. `0 1 1`

**Answer (B):** `42 1 0`

**Why:** To know that the number has ended, the extraction must try to read one more character, and it finds the end of input. That sets `eofbit`, but the extraction itself succeeded, so `failbit` is clear and `x` is 42. This is why `eof()` alone cannot tell you whether the last read worked.

### Question 6 [tricky] ([stringbuf.members], [istream.sentry])

What does this program print?

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

int main() {
  std::istringstream in("42");
  int x = 0;
  in >> x;
  in.str("7");
  in >> x;
  std::cout << x << ' ' << in.fail() << '\n';
}
```

A. `7 0`
B. `42 1`
C. `42 0`
D. `0 1`

**Answer (B):** `42 1`

**Why:** `str()` replaces the buffer contents but does not touch the stream's state bits. The first read left `eofbit` set, so the second extraction's sentry fails, sets `failbit`, and leaves `x` at 42. Call `in.clear()` after `str(...)` to reuse the stream.

### Question 7 [standardese] ([iostate.flags])

What does this program print?

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

int main() {
  std::istringstream in("1 2");
  in.exceptions(std::ios::failbit);
  int x;
  try {
    while (in >> x) std::cout << x << ',';
    std::cout << "done\n";
  } catch (const std::ios_base::failure&) {
    std::cout << "threw\n";
  }
}
```

A. `1,2,done`
B. `1,2,` then `done`, because `eofbit` is not in the mask
C. `1,2,threw`
D. `threw` immediately, before any output

**Answer (C):** `1,2,threw`

**Why:** The idiomatic loop ends because the third extraction sets `failbit`. With `failbit` in the exceptions mask, setting it throws `std::ios_base::failure` instead of returning a stream that converts to false. The `done` line is never reached. The `eofbit` is set too, but it is the `failbit` that matches the mask.

### Question 8 [standardese] ([facet.num.get.virtuals])

What does this program print?

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

int main() {
  std::istringstream in("-1");
  unsigned x = 0;
  in >> x;
  std::cout << (x == std::numeric_limits<unsigned>::max()) << ' ' << in.fail() << '\n';
}
```

A. `1 0`
B. `0 1`
C. `0 0`
D. `1 1`

**Answer (A):** `1 0`

**Why:** The numeric extraction converts with the rules of `strtoull`, which accepts a leading minus sign for unsigned types and negates the result modulo the type's range. So `-1` becomes the maximum value and no failure is reported. The tempting `0 1` assumes the library rejects a negative number for an unsigned target; it does not.
