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 rust-lang#44147

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
-    /// permissions for this file.
+    /// Returns the 12 least significant bits of `st_mode` which are the
+    /// standard 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) & 0o7777 }
     }
 
     pub fn file_type(&self) -> FileType {