diff options
author | Russ Cox <rsc@golang.org> | 2011-06-22 19:33:07 -0400 |
---|---|---|
committer | Russ Cox <rsc@golang.org> | 2011-06-22 19:33:07 -0400 |
commit | 36b5e1d6986d38aa47d9c8e3147b2dd488d22155 (patch) | |
tree | f3bf70d739e90a43d22528464463d9e054129d55 | |
parent | cd7826e5f6d187cd8f555f36d5654a372e95dba8 (diff) | |
download | go-36b5e1d6986d38aa47d9c8e3147b2dd488d22155.tar.gz go-36b5e1d6986d38aa47d9c8e3147b2dd488d22155.zip |
io: clarify Read, ReadAt, Copy, Copyn EOF behavior
R=golang-dev, bradfitz, iant, dsymonds, nigeltao, r
CC=golang-dev
https://golang.org/cl/4629062
-rw-r--r-- | src/pkg/io/io.go | 55 |
1 files changed, 37 insertions, 18 deletions
diff --git a/src/pkg/io/io.go b/src/pkg/io/io.go index 5080da2ea0..790cf94e7c 100644 --- a/src/pkg/io/io.go +++ b/src/pkg/io/io.go @@ -31,15 +31,24 @@ var ErrUnexpectedEOF os.Error = &Error{"unexpected EOF"} // Reader is the interface that wraps the basic Read method. // // 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. +// 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 rather than block waiting for more. +// 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 == os.EOF or err == nil. The next Read should +// return 0, os.EOF regardless. // -// At the end of the input stream, Read returns 0, os.EOF. -// Read may return a non-zero number of bytes with a non-nil err. -// In particular, a Read that exhausts the input may return n > 0, os.EOF. +// 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. type Reader interface { Read(p []byte) (n int, err os.Error) } @@ -127,19 +136,22 @@ type WriterTo interface { // ReaderAt is the interface that wraps the basic ReadAt method. // // ReadAt reads len(p) bytes into p starting at offset off in the -// underlying data stream. It returns the number of bytes +// underlying input source. It returns the number of bytes // read (0 <= n <= len(p)) and any error encountered. // -// 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. +// 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. // -// At the end of the input stream, ReadAt returns 0, os.EOF. -// ReadAt may return a non-zero number of bytes with a non-nil err. -// In particular, a ReadAt that exhausts the input may return n > 0, os.EOF. +// 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 ReadAt is reading from an data stream with a seek offset, +// If the n = len(p) bytes returned by ReadAt are at the end of the +// input source, ReadAt may return either err == os.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. type ReaderAt interface { @@ -237,7 +249,10 @@ func ReadFull(r Reader, buf []byte) (n int, err os.Error) { } // Copyn copies n bytes (or until an error) from src to dst. -// It returns the number of bytes copied and the error, if any. +// It returns the number of bytes copied and the earliest +// error encountered while copying. Because Read can +// return the full amount requested as well as an error +// (including os.EOF), so can Copyn. // // If dst implements the ReaderFrom interface, // the copy is implemented by calling dst.ReadFrom(src). @@ -283,7 +298,11 @@ func Copyn(dst Writer, src Reader, n int64) (written int64, err os.Error) { // 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 error, if any. +// copied and the first error encountered while copying, if any. +// +// A successful Copy returns err == nil, not err == os.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 dst implements the ReaderFrom interface, // the copy is implemented by calling dst.ReadFrom(src). |