8.1 io and File Handling — Specification¶

Reference material. Each interface listed with method signature, preconditions, postconditions, and invariants. Sentinel-error tables follow the interface tables. Concurrency table at the end.

This file is a distillation of the io, os, io/fs, and bufio package documentation as of Go 1.22, with implementation notes that the docs leave implicit. For prose explanations, see senior.md. For production patterns, see professional.md.

1. io.Reader¶

type Reader interface {
    Read(p []byte) (n int, err error)
}

Errors other than io.EOF are reader-defined. io.ErrUnexpectedEOF is not returned by Read directly — it is generated by helpers (io.ReadFull, io.ReadAtLeast) when a Reader ends prematurely.

2. io.Writer¶

type Writer interface {
    Write(p []byte) (n int, err error)
}

io.ErrShortWrite is the conventional error for "I tried to write all of p but only n < len(p) bytes made it." Callers see it from io.Copy-like helpers; primitives raise their own errors.

3. io.Closer¶

type Closer interface {
    Close() error
}

A reader's Close releases its hold on the source; a writer's Close finalizes the destination. For composed writers (gzip, bufio), Close also writes any pending trailer or buffered data and is therefore a correctness concern, not just resource cleanup.

4. io.Seeker¶

type Seeker interface {
    Seek(offset int64, whence int) (int64, error)
}

5. io.ReaderAt¶

type ReaderAt interface {
    ReadAt(p []byte, off int64) (n int, err error)
}

Note the difference from Read: ReadAt MUST signal a short read with an error. This is stricter than Read's contract.

6. io.WriterAt¶

type WriterAt interface {
    WriteAt(p []byte, off int64) (n int, err error)
}

The O_APPEND interaction is a Linux quirk to know: opening a file with O_APPEND makes WriteAt's offset argument a lie. The kernel ignores it.

7. io.ReaderFrom¶

type ReaderFrom interface {
    ReadFrom(r Reader) (n int64, err error)
}

Implementations exist on *os.File (uses copy_file_range/splice when applicable), *bytes.Buffer, *bufio.Writer, *net.TCPConn, and io.Discard.

8. io.WriterTo¶

type WriterTo interface {
    WriteTo(w Writer) (n int64, err error)
}

io.Copy checks WriterTo first, then ReaderFrom, then falls back to its 32 KiB internal-buffer loop.

9. io.ByteReader / io.ByteWriter¶

type ByteReader interface { ReadByte() (byte, error) }
type ByteWriter interface { WriteByte(c byte) error }

encoding/binary.Uvarint and similar code prefer a ByteReader so they don't allocate buffers per byte. bufio.Reader and strings.Reader implement both.

10. io.RuneReader¶

type RuneReader interface {
    ReadRune() (r rune, size int, err error)
}

11. io.StringWriter¶

type StringWriter interface {
    WriteString(s string) (n int, err error)
}

Optional companion to Writer. io.WriteString(w, s) checks for it and falls back to w.Write([]byte(s)) if absent. Implementing it saves one allocation per call when the source is already a string.

12. io.ReadCloser, io.WriteCloser, etc.¶

The compositions below are pure interface combinations. They contain no methods of their own; the named methods are only those from the embedded interfaces.

Naming convention: alphabetical order of method names.

13. Sentinel errors in io¶

Use errors.Is(err, io.EOF) rather than err == io.EOF. Some readers wrap the sentinel (e.g., decompressors may produce *gzip.Error{Err: io.ErrUnexpectedEOF}).

14. Sentinel errors in os and io/fs¶

os.IsNotExist, os.IsExist, os.IsPermission exist for legacy reasons. New code uses errors.Is(err, fs.ErrNotExist) etc.

15. io.Pipe semantics¶

func Pipe() (*PipeReader, *PipeWriter)

The "one writer, one reader" recommendation is operational, not contractual — multiple writers/readers don't corrupt memory, but ordering becomes nondeterministic.

16. bufio.Reader reference¶

ReadSlice returning bufio.ErrBufferFull means the delimiter wasn't found in the buffer — the caller should keep accumulating, or grow the buffer.

17. bufio.Writer reference¶

Flush is mandatory before Close of the underlying writer. bufio.Writer has no Close method — it relies on the caller to flush and close the underlying stream in the right order.

18. bufio.Scanner reference¶

Default MaxScanTokenSize is 65536. A token larger than this without calling Buffer results in bufio.ErrTooLong, and the token is lost (the scanner advances past it).

19. os.File method semantics¶

20. os.OpenFile flags¶

os.Open is os.OpenFile(name, O_RDONLY, 0). os.Create is os.OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0o666).

21. Concurrency safety¶

22. io/fs interfaces¶

type FS interface {
    Open(name string) (File, error)
}

type File interface {
    Stat() (FileInfo, error)
    Read([]byte) (int, error)
    Close() error
}

fs.ValidPath(name) returns true for valid io/fs paths: forward slashes only, no leading slash, no . or .. components, no empty elements.

23. Path packages¶

filepath.Clean removes ./.. syntactically; it does NOT prevent traversal because .. after a symlink is filesystem-resolved differently. Use filepath.EvalSymlinks plus a containment check, or os.Root (Go 1.24+).

24. Default sizes and limits¶

25. What to read next¶

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