Auto merge of #44624 - tmerr:master, r=sfackler

Retain suid/sgid/sticky bits in Metadata.permissions

Most users would expect set_permissions(Metadata.permissions()) to be
non-destructive. While we can't guarantee this, we can at least pass
the needed info to chmod.

Also update the PermissionsExt documentation to disambiguate what it
contains, and to refer to the underlying value as `st_mode` rather than
its type `mode_t`.

Closes #44147

src/libstd/fs.rs

@@ -2160,6 +2160,27 @@ mod tests {
         check!(fs::remove_file(&filename));
     }
 
+    #[test]
+    #[cfg(unix)]
+    fn set_get_unix_permissions() {
+        use os::unix::fs::PermissionsExt;
+
+        let tmpdir = tmpdir();
+        let filename = &tmpdir.join("set_get_unix_permissions");
+        check!(fs::create_dir(filename));
+        let mask = 0o7777;
+
+        check!(fs::set_permissions(filename,
+                                   fs::Permissions::from_mode(0)));
+        let metadata0 = check!(fs::metadata(filename));
+        assert_eq!(mask & metadata0.permissions().mode(), 0);
+
+        check!(fs::set_permissions(filename,
+                                   fs::Permissions::from_mode(0o1777)));
+        let metadata1 = check!(fs::metadata(filename));
+        assert_eq!(mask & metadata1.permissions().mode(), 0o1777);
+    }
+
     #[test]
     #[cfg(windows)]
     fn file_test_io_seek_read_write() {

src/libstd/sys/unix/ext/fs.rs

@@ -68,8 +68,8 @@ impl FileExt for fs::File {
 /// Unix-specific extensions to `Permissions`
 #[stable(feature = "fs_ext", since = "1.1.0")]
 pub trait PermissionsExt {
-    /// Returns the underlying raw `mode_t` bits that are the standard Unix
+    /// Returns the underlying raw `st_mode` bits that contain the standard
-    /// permissions for this file.
+    /// Unix permissions for this file.
     ///
     /// # Examples
     ///

src/libstd/sys/unix/fs.rs

@@ -95,7 +95,7 @@ pub struct DirBuilder { mode: mode_t }
 impl FileAttr {
     pub fn size(&self) -> u64 { self.stat.st_size as u64 }
     pub fn perm(&self) -> FilePermissions {
-        FilePermissions { mode: (self.stat.st_mode as mode_t) & 0o777 }
+        FilePermissions { mode: (self.stat.st_mode as mode_t) }
     }
 
     pub fn file_type(&self) -> FileType {