Clarify behavior of std::fs::hard_link when second path already exists.

[geeklint]

Location

Documentation of the std::fs::hard_link function, e.g. https://doc.rust-lang.org/std/fs/fn.hard_link.html

Summary

The function currently doesn't specify what happens if the second parameter (link / "the destination") already exists.

The note for unix systems and linux's man pages lead me to believe it will return an error in this case, but I don't think one should have to read linux man pages to determine the behavior of a rust function and it's not obvious if this is the intended rust behavior across platforms or if the behavior would be platform-specific.

Assuming it's not platform-specific, I think it'd be sufficient to add a bullet point to the # Errors section as a second documented error case.

[Harshit933]

@rustbot claim

[hkBst]

The code responsible for this redirects to fs_imp::link which is defined up top as use crate::sys::fs as fs_imp;. If we look at the sys mod we find pub use pal::*;, so we look at the pal mod where it basically says that depending on the target_os use an implementation specific for that target_os, so for unix we look in pal::unix::fs, for windows we look in pal::windows::fs. In this way you can drill down to the actual kernel calls being made, but I'm not sure this is viable way to proceed.

Perhaps a better way is to write a small program to do the hard link creation with an existing file at the link location and run that on a few platforms and see what happens. Report back with your findings and maybe it will then be clear what behavior to document.