Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Errors, I/O and Files

Go io.Reader and io.Writer interfaces

Reference for Go io.Reader and io.Writer: method contracts, how Read returns n and err, implementing your own reader and writer, and composing them.

io.Reader and io.Writer are two one-method interfaces that most of Go's I/O is built on. A Reader produces bytes through Read; a Writer consumes them through Write. Files, network connections, buffers, HTTP bodies, gzip streams and hashes all implement one or both.

Because the interfaces are so small, they are easy to implement and easy to combine. A function that accepts an io.Reader does not care whether the data comes from a file, a string or a socket, and a function that accepts an io.Writer can print to the terminal, a log file or a test buffer.

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

Try it

Go Implementing a Reader and a Writer

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 The Read contract in action

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

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

type Writer interface {
	Write(p []byte) (n int, err error)
}
Name Description
p (Read) A buffer the reader fills with up to len(p) bytes. It is your memory; the reader must not keep it.
p (Write) The bytes to write. The writer must not modify or retain the slice.
n Number of bytes read into p (0 to len(p)) or written from p.
err Nil, io.EOF at the end of input, or another error.

Read contract: it reads up to len(p) bytes and returns how many. It may return fewer than asked without it being an error. It may return n > 0 together with an error, even io.EOF, so handle the bytes before the error. At the end it returns 0, io.EOF.

Write contract: it must return a non-nil error if n < len(p).

Usage notes

  • Loops: call Read until it returns an error, process buf[:n] each time, and treat io.EOF as the normal end. io.ReadAll, io.Copy and bufio.Scanner do this for you.
  • Short reads are normal. Network and pipe readers often return a few bytes; use io.ReadFull when you need an exact count.
  • Many types have more. Look for io.Closer, io.Seeker, io.ReaderAt, io.WriterTo and io.ReaderFrom; io.Copy uses the last two when they are present for speed.
  • Decorator pattern: a type that holds an io.Reader and implements Read itself, like upper above, adds behavior such as counting, hashing, decompression or rate limiting.
  • fmt.Fprintf and friends accept any io.Writer, so a custom writer receives formatted output without further code.
  • Not concurrency safe by default. Two goroutines writing to the same os.File or buffer can interleave; guard with a mutex.
  • Strings and buffers: strings.NewReader, bytes.NewReader, bytes.Buffer and strings.Builder give in-memory readers and writers, ideal for tests.