Package io

Overview ▹

Overview ▾

Package io provides basic interfaces to I/O primitives.
Its primary job is to wrap existing implementations of such primitives,
such as those in package os, into shared public interfaces that
abstract the functionality, plus some other related primitives.

Because these interfaces and primitives wrap lower-level operations with
various implementations, unless otherwise informed clients should not
assume they are safe for parallel execution.

Package files

Internal call graph ▹

Internal call graph ▾

In the call graph viewer below, each node
is a function belonging to this package
and its children are the functions it
calls—perhaps dynamically.

The root nodes are the entry points of the
package: functions that may be called from
outside the package.
There may be non-exported or anonymous
functions among them if they are called
dynamically from another package.

Click a node to visit that function's source code.
From there you can visit its callers by
clicking its declaring func
token.

Functions may be omitted if they were
determined to be unreachable in the
particular programs or tests that were
analyzed.

Variables

EOF is the error returned by Read when no more input is available.
Functions should return EOF only to signal a graceful end of input.
If the EOF occurs unexpectedly in a structured data stream,
the appropriate error is either ErrUnexpectedEOF or some other error
giving more detail.

Copy copies from src to dst until either EOF is reached
on src or an error occurs. It returns the number of bytes
copied and the first error encountered while copying, if any.

A successful Copy returns err == nil, not err == EOF.
Because Copy is defined to read from src until EOF, it does
not treat an EOF from Read as an error to be reported.

If src implements the WriterTo interface,
the copy is implemented by calling src.WriteTo(dst).
Otherwise, if dst implements the ReaderFrom interface,
the copy is implemented by calling dst.ReadFrom(src).

ReadAtLeast reads from r into buf until it has read at least min bytes.
It returns the number of bytes copied and an error if fewer bytes were read.
The error is EOF only if no bytes were read.
If an EOF happens after reading fewer than min bytes,
ReadAtLeast returns ErrUnexpectedEOF.
If min is greater than the length of buf, ReadAtLeast returns ErrShortBuffer.
On return, n >= min if and only if err == nil.

ReadFull reads exactly len(buf) bytes from r into buf.
It returns the number of bytes copied and an error if fewer bytes were read.
The error is EOF only if no bytes were read.
If an EOF happens after reading some but not all the bytes,
ReadFull returns ErrUnexpectedEOF.
On return, n == len(buf) if and only if err == nil.

Pipe creates a synchronous in-memory pipe.
It can be used to connect code expecting an io.Reader
with code expecting an io.Writer.
Reads on one end are matched with writes on the other,
copying data directly between the two; there is no internal buffering.
It is safe to call Read and Write in parallel with each other or with
Close. Close will complete once pending I/O is done. Parallel calls to
Read, and parallel calls to Write, are also safe:
the individual calls will be gated sequentially.

Read implements the standard Read interface:
it reads data from the pipe, blocking until a writer
arrives or the write end is closed.
If the write end is closed with an error, that error is
returned as err; otherwise err is EOF.

Write implements the standard Write interface:
it writes data to the pipe, blocking until readers
have consumed all the data or the read end is closed.
If the read end is closed with an error, that err is
returned as err; otherwise err is ErrClosedPipe.

Read reads up to len(p) bytes into p. It returns the number of bytes
read (0 <= n <= len(p)) and any error encountered. Even if Read
returns n < len(p), it may use all of p as scratch space during the call.
If some data is available but not len(p) bytes, Read conventionally
returns what is available instead of waiting for more.

When Read encounters an error or end-of-file condition after
successfully reading n > 0 bytes, it returns the number of
bytes read. It may return the (non-nil) error from the same call
or return the error (and n == 0) from a subsequent call.
An instance of this general case is that a Reader returning
a non-zero number of bytes at the end of the input stream may
return either err == EOF or err == nil. The next Read should
return 0, EOF regardless.

Callers should always process the n > 0 bytes returned before
considering the error err. Doing so correctly handles I/O errors
that happen after reading some bytes and also both of the
allowed EOF behaviors.

Implementations of Read are discouraged from returning a
zero byte count with a nil error, except when len(p) == 0.
Callers should treat a return of 0 and nil as indicating that
nothing happened; in particular it does not indicate EOF.

MultiReader returns a Reader that's the logical concatenation of
the provided input readers. They're read sequentially. Once all
inputs have returned EOF, Read will return EOF. If any of the readers
return a non-nil, non-EOF error, Read will return that error.

TeeReader returns a Reader that writes to w what it reads from r.
All reads from r performed through it are matched with
corresponding writes to w. There is no internal buffering -
the write must complete before the read completes.
Any error encountered while writing is reported as a read error.

ReadAt reads len(p) bytes into p starting at offset off in the
underlying input source. It returns the number of bytes
read (0 <= n <= len(p)) and any error encountered.

When ReadAt returns n < len(p), it returns a non-nil error
explaining why more bytes were not returned. In this respect,
ReadAt is stricter than Read.

Even if ReadAt returns n < len(p), it may use all of p as scratch
space during the call. If some data is available but not len(p) bytes,
ReadAt blocks until either all the data is available or an error occurs.
In this respect ReadAt is different from Read.

If the n = len(p) bytes returned by ReadAt are at the end of the
input source, ReadAt may return either err == EOF or err == nil.

If ReadAt is reading from an input source with a seek offset,
ReadAt should not affect nor be affected by the underlying
seek offset.

Clients of ReadAt can execute parallel ReadAt calls on the
same input source.

Seek sets the offset for the next Read or Write to offset,
interpreted according to whence: 0 means relative to the origin of
the file, 1 means relative to the current offset, and 2 means
relative to the end. Seek returns the new offset and an error, if
any.

Seeking to a negative offset is an error. Seeking to any positive
offset is legal, but the behavior of subsequent I/O operations on
the underlying object is implementation-dependent.

Write writes len(p) bytes from p to the underlying data stream.
It returns the number of bytes written from p (0 <= n <= len(p))
and any error encountered that caused the write to stop early.
Write must return a non-nil error if it returns n < len(p).
Write must not modify the slice data, even temporarily.

WriteAt writes len(p) bytes from p to the underlying data stream
at offset off. It returns the number of bytes written from p (0 <= n <= len(p))
and any error encountered that caused the write to stop early.
WriteAt must return a non-nil error if it returns n < len(p).

If WriteAt is writing to a destination with a seek offset,
WriteAt should not affect nor be affected by the underlying
seek offset.

Clients of WriteAt can execute parallel WriteAt calls on the same
destination if the ranges do not overlap.