What is the difference between io.EOF and io.ErrUnexpectedEOF, and when does io.ReadFull return each?

## Two sentinels, one event At the byte layer there is only one thing that happens: the source stops producing. Whether that is fine or catastrophic depends entirely on what the reading code was expecting at that moment. Go gives the two interpretations two different values in the `io` package: - `io.EOF` — the stream ended, and an ending was permissible here. - `io.ErrUnexpectedEOF` — the stream ended in the middle of something that required more bytes. Neither can be derived from the stream itself. `io.ErrUnexpectedEOF` only ever comes from a layer that knew how many bytes it needed. ## The rule io.ReadFull implements `io.ReadFull(r Reader, buf []byte) (n int, err error)` reads exactly `len(buf)` bytes, looping over `Read` until the buffer is full. Its results are the canonical statement of the distinction: | bytes read | error | |---|---| | `len(buf)` | `nil` | | `0` | `io.EOF` | | `0 < n < len(buf)` | `io.ErrUnexpectedEOF` | Read that table as three answers to three different questions. Zero bytes means the stream ended cleanly *between* items — nothing was in progress, so the ending is legal and the caller usually treats it as "done". A partial read means an item was in progress and the source died inside it — that is corruption, and it must surface as a failure. `io.ReadAtLeast(r, buf, min)` generalises it: same three outcomes, measured against `min` rather than the whole buffer. ## Why this makes a record format parseable The practical payoff is in a loop over framed records. Suppose each record is a fixed 8-byte header followed by a payload whose length the header carries: ``` for { hdr := make([]byte, 8) _, err := io.ReadFull(r, hdr) if err == io.EOF { return nil // clean end, between records } if err != nil { return err // includes io.ErrUnexpectedEOF: truncated header } body := make([]byte, payloadLen(hdr)) if _, err := io.ReadFull(r, body); err != nil { return err // a short body is never a clean end } emit(hdr, body) } ``` Every termination is now classified. Compare that with a loop built on bare `Read` and a byte-slice accumulator: when the input stops, you get `io.EOF` and no information about whether you were mid-record. That ambiguity is how truncated inputs get accepted as complete. Notice the second `io.ReadFull`: once the header has been read, an ending is *never* legal until the body is complete, so any error — including `io.EOF` — is a failure there. In a body read you must not special-case `io.EOF`; letting it through is the classic truncation hole. ## Where else the pair shows up Several standard-library layers that decode fixed-size or length-delimited data promote a mid-item ending to `io.ErrUnexpectedEOF` before returning it to you, because they know the shape of what they were reading. When you write such a layer yourself, do the same: your caller has no way to know an ending was illegal unless you say so. Both values are ordinary sentinels, so both are testable with `errors.Is(err, io.ErrUnexpectedEOF)` as well as `==`. Because `io.ErrUnexpectedEOF` is a distinct value and not a wrapper around `io.EOF`, `errors.Is(err, io.EOF)` is **false** for it — a truncation will not accidentally match an end-of-stream test. ## The judgment to carry away If your code can articulate how many bytes it still owes the format, translate an ending at that point into `io.ErrUnexpectedEOF` (or a domain error that says which record died). If it genuinely has no expectation — a plain copy, a log tail — then an ending is just an ending and `io.EOF` is right. The distinction is not about the transport; it is about the contract the reading layer has with the format.