Documentation for `std::fs::set_permissions` doesn't cover symlink behavior

[sunfishcode]

The documentation for std::fs::set_permissions doesn't say what it does if the given path names a symlink.

Experimentally, it seems that on Unix-family platforms it follows symlinks, while on Windows it does not. Though surprising, it's likely just a result of using the chmod and SetFileAttributes functions on their respective platform. The documentation does say that use of those functions isn't guaranteed, so it'd be useful to document what guarantees are intended, if any.

[lolbinarycat]

requesting prioritization due to possible relation to CVE-2025-27591.

[ChrisDenton]

Note that libs/libs-api doesn't generally use prioritisation labels, So I've nominated it for @rust-lang/libs-api discussion.

[Amanieu]

We discussed this in the @rust-lang/libs-api meeting. Considering that on Unix it's not possible to manipulate the permissions of a symlink (there isn't even a syscall for it on Linux), the question was whether we should change the Windows behavior. The consensus was to leave the behavior as it is and document the difference.

One open question was whether this affects WASI since it needs to support both Unix and Windows host platforms. We may revisit this decision if it turns out to cause problems in WASI.