io: relax documented Seeker invariants that do not hold in practice

Use “or” instead of “and” to describe error behavior.
On error, nearly all Seeker implementations in the Go repo return
0 instead of “the new offset”. (Arguably on error “the new offset”
is the same as the previous offset, but some Seeker implementations
don't have that offset readily available.)

Don't claim that “any positive offsite is legal”.
In practice, most of the Seeker implementations within the Go standard
library do not allow “[s]eeking to any [arbitrary] positive offset”:
some reject all out-of-bounds offsets, and some reject only a subset
that happen to overflow some underlying representation. Since some
positive offsets may be rejected, we cannot claim that seeking to
those offsets “is legal”. However, to avoid invalidating existing
Seeker implemetations we must not require an implementation to reject
invalid positive offsets either.

This is technically a breaking change, since callers of Seek are no
longer allowed to assume that a Seek resulting in an arbitrary
positive offset will succeed. However, since basically none of the
existing implementations actually conformed to the documented behavior
I believe this falls under the “specification errors” exception to the
Go 1 compatibility policy.

Fixes #48316

Change-Id: Ib1b478599b20ad5361bcc97fe8ceb84f74e6d971
Reviewed-on: https://go-review.googlesource.com/c/go/+/349054
Trust: Bryan C. Mills <bcmills@google.com>
Run-TryBot: Bryan C. Mills <bcmills@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Rob Pike <r@golang.org>

1 files changed, 4 insertions, 3 deletions

diff --git a/src/io/io.go b/src/io/io.go
index 2724321ed9..2e697e7450 100644
--- a/src/io/io.go
+++ b/src/io/io.go
@@ -113,11 +113,12 @@ type Closer interface {
 // SeekCurrent means relative to the current offset, and
 // SeekEnd means relative to the end.
 // Seek returns the new offset relative to the start of the
-// file and an error, if any.
+// file or an error, if any.
 //
 // Seeking to an offset before the start of the file 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.
+// Seeking to any positive offset may be allowed, but if the new offset exceeds
+// the size of the underlying object the behavior of subsequent I/O operations
+// is implementation-dependent.
 type Seeker interface {
 	Seek(offset int64, whence int) (int64, error)
 }