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.
n, err := io.Copy(os.Stdout, strings.NewReader("hello\n"))
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
Core interfaces:
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.EOFis not a failure. Reading loops stop on it; only report other errors. Compare witherr == io.EOForerrors.Is(err, io.EOF).- A reader may return data and an error together. Process the
nbytes first, then look aterr. - Check
ReadAllsizes. On untrusted input wrap the source inio.LimitReaderso one request cannot exhaust memory. - Always close what you open, usually with
defer f.Close();io.Closeris the shared interface. - Prefer small interfaces in your own functions: accept
io.Readerandio.Writerinstead of*os.File, and tests can pass strings and buffers. io/ioutilis deprecated. Useio.ReadAll,io.Discard,io.NopCloserandos.ReadFileinstead.- Pipes are synchronous. A write on
io.Pipeblocks until a reader consumes it, so use two goroutines.