From: Michael Diamond <dimo414@gmail.com>
Date: Fri, 19 Nov 2021 18:58:24 +0000 (-0800)
Subject: Add a caveat to std::os::windows::fs::symlink_file
X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=9c3b0d81ef4ebcb1f1ca9d17bf222d832e513140;p=rust.git

Add a caveat to std::os::windows::fs::symlink_file

This is similar to the note on [Python's `os.symlink()`](https://docs.python.org/3/library/os.html#os.symlink). Some additional notes in https://github.com/dimo414/bkt/issues/3.
---

diff --git a/library/std/src/os/windows/fs.rs b/library/std/src/os/windows/fs.rs
index be35ab0ca1e..31d1e3c1e42 100644
--- a/library/std/src/os/windows/fs.rs
+++ b/library/std/src/os/windows/fs.rs
@@ -543,6 +543,16 @@ fn is_symlink_file(&self) -> bool {
 ///     Ok(())
 /// }
 /// ```
+///
+/// # Limitations
+///
+/// Windows treats symlink creation as a [privileged action][symlink-security],
+/// therefore this function is likely to fail unless the user makes changes to
+/// their system to permit symlink creation. Users can try enabling Developer
+/// Mode, granting the `SeCreateSymbolicLinkPrivilege` privilege, or running
+/// the process as an administrator.
+///
+/// [symlink-security]: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links
 #[stable(feature = "symlink", since = "1.1.0")]
 pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
     sys::fs::symlink_inner(original.as_ref(), link.as_ref(), false)
@@ -572,6 +582,16 @@ pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io:
 ///     Ok(())
 /// }
 /// ```
+///
+/// # Limitations
+///
+/// Windows treats symlink creation as a [privileged action][symlink-security],
+/// therefore this function is likely to fail unless the user makes changes to
+/// their system to permit symlink creation. Users can try enabling Developer
+/// Mode, granting the `SeCreateSymbolicLinkPrivilege` privilege, or running
+/// the process as an administrator.
+///
+/// [symlink-security]: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links
 #[stable(feature = "symlink", since = "1.1.0")]
 pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
     sys::fs::symlink_inner(original.as_ref(), link.as_ref(), true)