io/ioutil: document that WriteFile does not do a f.Sync

[prashanthpai]

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

$ go version
go version go1.8 linux/amd64

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

$ go env
GOARCH="amd64"
GOBIN=""
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/ppai/work"
GORACE=""
GOROOT="/home/ppai/go"
GOTOOLDIR="/home/ppai/go/pkg/tool/linux_amd64"
GCCGO="gccgo"
CC="gcc"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build569018824=/tmp/go-build -gno-record-gcc-switches"
CXX="g++"
CGO_ENABLED="1"
PKG_CONFIG="pkg-config"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"

What did you do?

Use ioutil.WriteFile.

What did you expect to see?

I'm sorry if the expectation is wrong but I expected the source of ioutil.WriteFile to have a call to
f.Sync()

What did you see instead?

No call to f.Sync() was made internally

If fixing this is acceptable, I'll be glad to send a small patch 👍

[mvdan]

Out of curiosity, why? In general, if you're writing to a file, you want to check for an f.Close() error. As long as you do that, I don't think a call to f.Sync() is necessary.

[dominikh]

@mvdan Closing a file doesn't issue a sync. At the same time, there are plenty of files for which you won't care, and syncing unnecessarily will incur a performance cost. Maybe this is a documentation issue and no change to the code should be made.

[mvdan]

My bad - I thought closing a file meant syncing it too, but I must have gotten confused. It's a bit bizarre that you could care about close errors but not about sync errors, though.

[dsnet]

Some discussion about f.Sync in WriteFile has been discussed in the past. See #17869.

While it may seem reasonable for f.Sync to be called in your use case, it not reasonable to inflict the cost of f.Sync upon every use of it. You can always work around this, by creating the file yourself and writing to it and then calling Sync.

This is indeed a documentation issue.

[bradfitz]

We can document the lack of fsync for Go 1.10 unless somebody sends a change for Go 1.9 which would be fine too.

[ianlancetaylor]

That is an odd sort of documentation to write. There are all kinds of functions that do not call os.File.Sync. Perhaps my expectations are wrong, but I would expect the reverse: I would expect that if ioutil.WriteFile called Sync, that that would be called out in the documentation. I would not expect the documentation to explicitly say that it does not call Sync.

[bradfitz]

I would agree, but this keeps coming up, so it makes me wonder if my expectations are wrong.

But I'm also fine not doing anything here again.

[robpike]

Lots of things don't call sync. This is not one worth singling out. I say stet.

[bradfitz]

Okay, fair enough. Closing.