From 39e08c6cd75da72059a58f05eb500b48124d563e Mon Sep 17 00:00:00 2001 From: "Bryan C. Mills" Date: Fri, 10 Sep 2021 10:47:03 -0400 Subject: [PATCH] io: relax documented Seeker invariants that do not hold in practice MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit 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 Run-TryBot: Bryan C. Mills TryBot-Result: Go Bot Reviewed-by: Brad Fitzpatrick Reviewed-by: Ian Lance Taylor Reviewed-by: Rob Pike --- src/io/io.go | 7 ++++--- 1 file 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) } -- 2.50.0