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

Jump to bottom

os: clarify documentation for O_TRUNC #28699

Closed
bcmills opened this issue Nov 9, 2018 · 3 comments
Closed

os: clarify documentation for O_TRUNC #28699

bcmills opened this issue Nov 9, 2018 · 3 comments
Labels
Documentation FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
Go1.12

Comments

@bcmills
Copy link
Contributor

bcmills commented Nov 9, 2018 •
edited

The comment for os.O_TRUNC currently says:

go/src/os/file.go

Line 76 in 78c0e1f

O_TRUNC int = syscall.O_TRUNC // if possible, truncate file when opened.

The “if possible” part of that comment is ambiguous: on Linux it seems to mean “if the file is a regular file or symlink to a regular file” (i.e., not a stream like /dev/stdout), but it could be “impossible” to truncate the file for other reasons (such as a permission error), and os.OpenFile with os.O_TRUNC seems to report an error in those cases.

We should drop the “if possible” phrase and instead explicitly document the conditions under which O_TRUNC is ignored.
@bcmills bcmills added Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Nov 9, 2018
@bcmills bcmills added this to the Go1.12 milestone Nov 9, 2018
@bcmills
Copy link
Contributor Author

bcmills commented Nov 9, 2018

(CC @rsc @robpike @ianlancetaylor)

@robpike
Copy link
Contributor

robpike commented Nov 10, 2018

I fear that making the os package document every aspect, for every OS, of the calls it wraps is a Sisyphean endeavor and not worth pursuing.

@gopherbot
Copy link

Change https://golang.org/cl/155177 mentions this issue: os: clarify O_TRUNC comment

@golang golang locked and limited conversation to collaborators Dec 20, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Milestone
Go1.12
Development

No branches or pull requests
3 participants
@robpike @bcmills @gopherbot