os: document Chown behavior when uid == -1 or gid == -1

[mark-rushakoff]

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

https://golang.org/pkg/os/

Does this issue reproduce with the latest release?

Yes, checked tip docs as well: https://tip.golang.org/pkg/os/ (Build version devel +d3026dd30a Thu Apr 5 18:54:31 2018 +0000.)

What did you do?

I read some code like os.Chown(path, -1, gid) and was unsure what uid == -1 meant, so I checked the docs.

What did you expect to see?

Explanation of behavior when uid == -1 (for any of Chown, Lchown, and (*File).Chown).

What did you see instead?

I had to trace through the os code to learn that it calls syscall.Chown, then I had to check man 2 chown to learn:

One of the owner or group id's may be left unchanged by specifying it as -1.

I also consulted http://pubs.opengroup.org/onlinepubs/9699919799/functions/chown.html which states

If owner or group is specified as (uid_t)-1 or (gid_t)-1, respectively, the corresponding ID of the file shall not be changed.

so I believe this behavior should be okay to add to Godoc.

[bradfitz]

@ianlancetaylor, this is news to me that we do this (by accident?). Are we trying to be POSIX-ish here, or did that just happen?

[bradfitz]

NeedsFix because we need to document it either way. But we need to decide which way.

[ianlancetaylor]

That's how POSIX works. Passing the owner or group as -1 leaves it unchanged. I note that we don't implement this feature on NaCl. On Windows and Plan 9 we don't implement Chown at all. So I think we should implement it in NaCl and document it in the os package.

[gopherbot]

Change https://golang.org/cl/106464 mentions this issue: os: document that Chown with -1 means to leave values unchanged, like POSIX