8.6 bufio — Specification¶

Reference material. Method signatures, semantics, errors, defaults. Distilled from the Go 1.22 standard library, with implementation notes the docs leave implicit.

For prose, see senior.md. For the foundational Reader/Writer contracts that bufio builds on, see ../01-io-and-file-handling/specification.md.

1. Constants and defaults¶

2. Sentinel errors¶

3. bufio.Reader constructors¶

func NewReader(rd io.Reader) *Reader
func NewReaderSize(rd io.Reader, size int) *Reader

4. bufio.Reader methods¶

ReadSlice error matrix¶

Peek error matrix¶

Read behaviour¶

5. bufio.Writer constructors¶

func NewWriter(w io.Writer) *Writer
func NewWriterSize(w io.Writer, size int) *Writer

6. bufio.Writer methods¶

Flush semantics¶

• Pushes buf[:n] to the underlying writer in one call.
• If the underlying Write returns m < n with err == nil, error is io.ErrShortWrite; remaining buf[n-m:n] shifts to buf[:n-m].
• If underlying Write returns an error, error is sticky in b.err; n updated to reflect actual bytes sent.

bufio.Writer has no Close method¶

Caller must Flush then close the underlying writer. bufio.Writer deliberately does not own the sink.

7. bufio.ReadWriter¶

type ReadWriter struct {
    *Reader
    *Writer
}

func NewReadWriter(r *Reader, w *Writer) *ReadWriter

A pair of pointers, no methods of its own. All Reader and Writer methods are inherited via embedding. Reads do not flush writes. The two halves share no state; you can pair any *Reader with any *Writer.

8. bufio.Scanner constructor¶

func NewScanner(r io.Reader) *Scanner

Lazy: the internal buffer is allocated on the first call to Scan.

9. bufio.Scanner methods¶

Default split: bufio.ScanLines. Default max: bufio.MaxScanTokenSize (65536).

10. bufio.SplitFunc¶

type SplitFunc func(data []byte, atEOF bool) (advance int, token []byte, err error)

Constraints: - advance >= 0. Negative advance triggers ErrNegativeAdvance. - advance <= len(data). Larger triggers ErrAdvanceTooFar. - At atEOF == true && len(data) > 0, returning (0, nil, nil) is a bug; the scanner panics.

11. Built-in SplitFuncs¶

12. Scanner token-loss behaviour¶

13. Concurrency table¶

Reset is not a synchronisation point. Calling Reset from one goroutine while another is mid-method is a race detected by -race.

14. Method-by-method allocation¶

15. Layered close order¶

For a stack of os.File → bufio.Writer → codec writer (gzip, etc.):

1. Close codec writer (writes its trailer into bufio).
2. Flush bufio writer (pushes all bytes to file).
3. Close file.

In defer form (LIFO), declare in reverse: file close, bufio flush, codec close. The first-declared defer runs last.

16. bufio.Writer.ReadFrom short-circuit¶

io.Copy(bw, r) invokes bw.ReadFrom(r). The implementation:

1. If buffer has bytes, drain via underlying Write.
2. If underlying writer implements io.ReaderFrom, defer to it.
3. Otherwise, loop: fill buffer from r, write to underlying.

Returns total bytes written; first error stops the loop.

17. bufio.Reader.WriteTo short-circuit¶

io.Copy(w, br) invokes br.WriteTo(w). The implementation:

1. Send buffered bytes (buf[r:w]) to w.
2. If underlying reader implements io.WriterTo, defer to it.
3. Otherwise, loop: read into buffer, write to w.

Returns total bytes; first error stops the loop. EOF normalised to nil on return.

18. Scanner cannot be reused¶

There is no Reset method on Scanner. After Scan returns false, the scanner is done. Construct a new Scanner for a new source. Pooling the underlying buffer is possible but rarely worth the complexity; pool the underlying source instead.

19. Build-time / type information¶

type Reader struct { /* unexported */ }
type Writer struct { /* unexported */ }
type Scanner struct { /* unexported */ }
type ReadWriter struct {
    *Reader
    *Writer
}
type SplitFunc func(data []byte, atEOF bool) (advance int, token []byte, err error)

All of Reader, Writer, Scanner have unexported fields; you must use the constructors to create them.

Reader implements io.Reader, io.ByteReader, io.RuneReader, io.WriterTo. Writer implements io.Writer, io.ByteWriter, io.StringWriter, io.ReaderFrom.

20. What to read next¶

• senior.md — prose form of these tables with examples.
• find-bug.md — bugs that result from violating items above.
• optimize.md — performance implications of the defaults.