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

io/ioutil: docs for WriteFile should make it clear that it does not change permissions #35711

Closed
zeripath opened this issue Nov 20, 2019 · 3 comments
Closed

io/ioutil: docs for WriteFile should make it clear that it does not change permissions #35711

zeripath opened this issue Nov 20, 2019 · 3 comments
Labels
Documentation FrozenDueToAge WaitingForInfo Issue is not actionable because of missing required information, which needs to be provided.
Milestone
Unplanned

Comments

@zeripath
Copy link

What version of Go are you using (go version)?

$ go version
go version go1.13.1 linux/amd64

Does this issue reproduce with the latest release?

yes

What operating system and processor architecture are you using (go env)?

go env Output
$ go env
GO111MODULE=""
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/andrew/.cache/go-build"
GOENV="/home/andrew/.config/go/env"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/andrew/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/usr/lib/go-1.13"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/usr/lib/go-1.13/pkg/tool/linux_amd64"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/home/andrew/go/src/code.gitea.io/gitea/go.mod"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build028639981=/tmp/go-build -gno-record-gcc-switches"

What did you do?

Say you had some-extant-file with mode 0644 and you run:

ioutil.WriteFile("some-extant-file", []byte("new data"), 0777)

What did you expect to see?

From a cursory glance of the documentation you would expect that the mode of some-extant-file would change to 0777.

What did you see instead?

It doesn't change mode - as is implied by the documentation saying it "truncates the file"

I think the documentation for ioutil.WriteFile should be clearer that when the file is already extant its mode will not change. This is implied by the current documentation, but it is subtle and a quick review of the docs will lead to and has led to developers & reviewers missing this important note causing bugs.
@zeripath zeripath changed the title ioutil.WriteFile should make it clear that it does not change permissions Docs ioutil.WriteFile should make it clear that it does not change permissions Nov 20, 2019
@zeripath zeripath changed the title Docs ioutil.WriteFile should make it clear that it does not change permissions Docs for ioutil.WriteFile should make it clear that it does not change permissions Nov 20, 2019
@ianlancetaylor
Copy link
Contributor

When I read the docs for ioutil.WriteFile they seem to me to be precise and accurate.

WriteFile writes data to a file named by filename. If the file does not exist, WriteFile creates it with permissions perm; otherwise WriteFile truncates it before writing.

It seems clear to me that the permissions are used only if the file does not exist. If the file does exist, it is truncated, but the permissions are not changed.

Go's documentation aims for correctness, precision, and brevity. Making docs longer on average makes them harder to understand.

That said, do you have a specific suggestion for how to make the docs clearer?

@ianlancetaylor ianlancetaylor changed the title Docs for ioutil.WriteFile should make it clear that it does not change permissions io/ioutil: docs for WriteFile should make it clear that it does not change permissions Nov 20, 2019
@ianlancetaylor ianlancetaylor added the WaitingForInfo Issue is not actionable because of missing required information, which needs to be provided. label Nov 20, 2019
@ianlancetaylor ianlancetaylor added this to the Unplanned milestone Nov 20, 2019
@zeripath
Copy link
Author

It's fairly subtle and I can easily see why non-native English speakers have missed it.

I think if you add the post script, "...without changing permissions." then it's completely clear and totally unambiguous.

@gopherbot
Copy link

Change https://golang.org/cl/218417 mentions this issue: io/ioutil: update WriteFile doc to make it clearer that it does not

@francislavoie francislavoie mentioned this issue May 24, 2020
Closed
@golang golang locked and limited conversation to collaborators Jun 4, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation FrozenDueToAge WaitingForInfo Issue is not actionable because of missing required information, which needs to be provided.
Projects
None yet
Milestone
Unplanned
Development

No branches or pull requests
3 participants
@zeripath @ianlancetaylor @gopherbot