os: clarify documentation for O_TRUNC

[bcmills]

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]

(CC @rsc @robpike @ianlancetaylor)

[robpike]

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]

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