Clarify that `fs::copy` dereferences symlinks instead of copying the link itself

[ginnyTheCat]

Location

std::fs::copy

Summary

fs::copy, when being called with a symlink as from, does not copy the symlink itself but dereferences it and copies the file behind the symlink. The Rust docs do not really mention this, even if it discoverable that this is the behaviour as the docs mentions not being able to copy symlinks to directories. I think explicitly mentioning this, however, would be a nice addition.

[workingjubilee]

I actually don't think any specific behavior is intended here, though I've seen this issue also.

[ginnyTheCat]

Sorry for asking but I'm having trouble understanding your message.

Currently on linux it copies the content of the file, on windows it uses CopyFileExW without the COPY_FILE_COPY_SYMLINK flag set and on macos it opens the file as well (which should follow the symlink) and uses fclonefileat without the CLONE_NOFOLLOW flag set. Maybe there is a platform where it does behave like this, however that platform probably violates the error case "from is [not] a symlink to a regular file" documented in the docs atm as it would likely also allow copying symlinks to directories.