Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Errors, I/O and Files

Go io package

Reference for the Go io package: Reader and Writer interfaces, Copy, ReadAll, ReadFull, MultiWriter, TeeReader, LimitReader, Pipe, SectionReader and io.EOF.

The package io defines the small interfaces that almost all input and output in Go is built on, and a toolbox of helpers that combine them. Files, network connections, HTTP bodies, compressed streams, buffers and strings all implement io.Reader or io.Writer, so a function that takes a reader works with every one of them.

The helpers wrap readers and writers into new ones: limit how much can be read, duplicate what is written, copy from one to the other, or connect a writer to a reader through a pipe. Together with bufio and os this is the core of Go's I/O model.

Go
n, err := io.Copy(os.Stdout, strings.NewReader("hello\n"))

Try it

Go Combining readers and writers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Pipe, ReadFull and io.EOF

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Core interfaces:

Go
type Reader interface{ Read(p []byte) (n int, err error) }
type Writer interface{ Write(p []byte) (n int, err error) }
type Closer interface{ Close() error }
type ReaderFrom interface{ ReadFrom(r Reader) (n int64, err error) }
type WriterTo interface{ WriteTo(w Writer) (n int64, err error) }
type ReaderAt interface{ ReadAt(p []byte, off int64) (n int, err error) }
type Seeker interface{ Seek(offset int64, whence int) (int64, error) }
type ByteReader interface{ ReadByte() (byte, error) }
type StringWriter interface{ WriteString(s string) (n int, err error) }

Combined interfaces such as ReadWriter, ReadCloser, WriteCloser and ReadWriteCloser join them. Main functions:

Function Description
Copy(dst, src) Copies until EOF; returns bytes copied.
CopyN, CopyBuffer Copy a fixed count, or with a caller-supplied buffer.
ReadAll(r) Reads until EOF into a new slice.
ReadFull, ReadAtLeast Read exactly or at least N bytes.
WriteString(w, s) Writes a string to any Writer.
LimitReader, MultiReader, TeeReader, NewSectionReader Wrap readers.
MultiWriter, Pipe Fan out writes; connect a writer to a reader.
NopCloser, Discard A Closer that does nothing; a writer that discards everything.

Errors: io.EOF marks a clean end of input, io.ErrUnexpectedEOF an end in the middle of a fixed-size read, io.ErrShortWrite a write that stopped early, io.ErrClosedPipe a use of a closed pipe.

Usage notes

  • io.EOF is not a failure. Reading loops stop on it; only report other errors. Compare with err == io.EOF or errors.Is(err, io.EOF).
  • A reader may return data and an error together. Process the n bytes first, then look at err.
  • Check ReadAll sizes. On untrusted input wrap the source in io.LimitReader so one request cannot exhaust memory.
  • Always close what you open, usually with defer f.Close(); io.Closer is the shared interface.
  • Prefer small interfaces in your own functions: accept io.Reader and io.Writer instead of *os.File, and tests can pass strings and buffers.
  • io/ioutil is deprecated. Use io.ReadAll, io.Discard, io.NopCloser and os.ReadFile instead.
  • Pipes are synchronous. A write on io.Pipe blocks until a reader consumes it, so use two goroutines.