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

[zeripath]

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.

[ianlancetaylor]

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?

[zeripath]

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]

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