Describe change-file-permissions-at in more detail

[sunfishcode]

change-file-permissions-at is vague about what it precisely does. This is necessary to some degree, due to differences between host operating systems. But it should at least say what it does on Unix and probably also Windows.

My rough idea when I proposed this function was that on Unix it would follow the user's umask. The umask is commonly 02, which means readable would be world-readable, writeable would be user/group-writeable, and executable would be world-executable.

[codefromthecrypt]

It seems the mode can't be read back by any of the functions defined here (e.g. not by stat), which makes less edge cases to describe for read-back.

I would recommend saying somehow, that when embedded in windows, you can't change the permissions of a directory and the execute bit has no meaning in files. Go has similar docs on this.