std(docs): clarify how std::fs::set_permisions works with symlinks

fixes https://github.com/rust-lang/rust/issues/75942
fixes https://github.com/rust-lang/rust/issues/124201

1 files changed, 13 insertions, 0 deletions

diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs
index 801baf3d990..1fe180066ce 100644
--- a/library/std/src/fs.rs
+++ b/library/std/src/fs.rs
@@ -2980,6 +2980,19 @@ pub fn read_dir<P: AsRef<Path>>(path: P) -> io::Result<ReadDir> {
 ///
 /// [changes]: io#platform-specific-behavior
 ///
+/// # Symlinks
+/// On UNIX systems, it is impossible to manipulate the permission bits of a symlink itself[^1].
+/// Because of this, on those systems, this function will update the permission bits
+/// of the file pointed to by the symlink.
+///
+/// Note that this behavior can lead to privalage escalation vulnerabilites,
+/// where the ability to write a symlink in one directory allows you to
+/// cause the permissions of another directory to be modified.
+///
+/// For this reason, using this function with symlinks should be avoided.
+/// When possible, permissions should be set at creation time instead.
+///
+/// [^1]: even if it were possible, the permissions on a symlink are ignored.
 /// # Errors
 ///
 /// This function will return an error in the following situations, but is not