Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

io: Seeker: clarify expected sign of offset for SeekEnd #53474

Closed
gonzojive opened this issue Jun 21, 2022 · 3 comments
Closed

io: Seeker: clarify expected sign of offset for SeekEnd #53474

gonzojive opened this issue Jun 21, 2022 · 3 comments
Labels
Documentation FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@gonzojive
Copy link

gonzojive commented Jun 21, 2022

I suggest updating the documentation to clarify that a negative offset is expected to seek to a valid position within the file when SeekEnd is passed as whence to an io.Seeker. Current documentation:

Seeker is the interface that wraps the basic Seek method.

Seek sets the offset for the next Read or Write to offset, interpreted according to whence: SeekStart means relative to the start of the file, 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 or an error, if any.

Seeking to an offset before the start of the file is an error. 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.

I find "SeekEnd means relative to the end" ambiguous about the expected sign.

"SeekEnd means relative to the end (e.g., offset = -2 specifies the penultimate byte of the file)" would be clearer but is verbose.

@ianlancetaylor ianlancetaylor added Documentation help wanted NeedsFix The path to resolution is known, but the work has not been done. labels Jun 21, 2022
@ianlancetaylor ianlancetaylor added this to the Backlog milestone Jun 21, 2022
@ianlancetaylor
Copy link
Contributor

ianlancetaylor commented Jun 21, 2022

I don't see any ambiguity, but I'm OK with adding a sentence or adjusting the existing one.

The docs for the C function lseek say "SEEK_END: The file offset is set to the size of the file plus offset bytes."

@ianlancetaylor ianlancetaylor changed the title io.Seeker: Clarify expected sign of offset for SeekEnd io: Seeker: clarify expected sign of offset for SeekEnd Jun 21, 2022
howjmay added a commit to howjmay/go that referenced this issue Jun 22, 2022
Make the description of SeekEnd more clear.

close golang#53474
@gopherbot
Copy link

Change https://go.dev/cl/413614 mentions this issue: src/io: amend SeekerEnd description

howjmay added a commit to howjmay/go that referenced this issue Jun 24, 2022
@dmitshur dmitshur modified the milestones: Backlog, Go1.19 Jun 25, 2022
jproberts pushed a commit to jproberts/go that referenced this issue Aug 10, 2022
fixes golang#53474

Change-Id: I14c3dc800dc27233630a54592328bb0df1bbaa5d
GitHub-Last-Rev: 46f93cf
GitHub-Pull-Request: golang#53505
Reviewed-on: https://go-review.googlesource.com/c/go/+/413614
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: Emmanuel Odeke <emmanuel@orijtech.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Auto-Submit: Emmanuel Odeke <emmanuel@orijtech.com>
Run-TryBot: Ian Lance Taylor <iant@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
@gonzojive
Copy link
Author

gonzojive commented Oct 11, 2022 via email

@golang golang locked and limited conversation to collaborators Oct 11, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants