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.
type Reader interface { Read(p []byte) (n int, err error) } type Writer interface { Write(p []byte) (n int, err error) }
Try it
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.
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
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
Readuntil it returns an error, processbuf[:n]each time, and treatio.EOFas the normal end.io.ReadAll,io.Copyandbufio.Scannerdo this for you. - Short reads are normal. Network and pipe readers often return a few bytes; use
io.ReadFullwhen you need an exact count. - Many types have more. Look for
io.Closer,io.Seeker,io.ReaderAt,io.WriterToandio.ReaderFrom;io.Copyuses the last two when they are present for speed. - Decorator pattern: a type that holds an
io.Readerand implementsReaditself, likeupperabove, adds behavior such as counting, hashing, decompression or rate limiting. fmt.Fprintfand friends accept anyio.Writer, so a custom writer receives formatted output without further code.- Not concurrency safe by default. Two goroutines writing to the same
os.Fileor buffer can interleave; guard with a mutex. - Strings and buffers:
strings.NewReader,bytes.NewReader,bytes.Bufferandstrings.Buildergive in-memory readers and writers, ideal for tests.