os: document that os.Rename will overwrite any existing file

[raboof]

TestRenameOverwriteDest suggests that on all OS'es except plan9, when the target path of os.Rename already exists, it will be replaced.

It might be nice to add that to the docs: for example on Windows it is not obvious (syscall_windows.go explicitly adds the MOVEFILE_REPLACE_EXISTING flag - there's no way to tell without either looking at the code or testing)

[ianlancetaylor]

Seems like if we are going to document it we should make sure that Plan 9 behaves that way too.

[raboof]

Wait, I'm confused - https://github.com/golang/go/blob/master/src/syscall/syscall_windows.go#L423 does not look like it actually would overwrite the target file, while https://github.com/golang/go/blob/master/src/internal/syscall/windows/syscall_windows.go#L130 does.

[ianlancetaylor]

os.Rename uses windows.Rename from internal/syscall/windows.

[rsc]

Filed #13844 for Plan 9 and will write docs.

[gopherbot]

CL https://golang.org/cl/18332 mentions this issue.