Auto merge of #25844 - alexcrichton:stabilize-fs-features, r=aturon

This commit stabilizes the following APIs, slating them all to be cherry-picked
into the 1.1 release.

* fs::FileType (and transitively the derived trait implementations)
* fs::Metadata::file_type
* fs::FileType::is_dir
* fs::FileType::is_file
* fs::FileType::is_symlink
* fs::DirEntry::metadata
* fs::DirEntry::file_type
* fs::DirEntry::file_name
* fs::set_permissions
* fs::symlink_metadata
* os::raw::{self, *}
* os::{android, bitrig, linux, ...}::raw::{self, *}
* os::{android, bitrig, linux, ...}::fs::MetadataExt
* os::{android, bitrig, linux, ...}::fs::MetadataExt::as_raw_stat
* os::unix::fs::PermissionsExt
* os::unix::fs::PermissionsExt::mode
* os::unix::fs::PermissionsExt::set_mode
* os::unix::fs::PermissionsExt::from_mode
* os::unix::fs::OpenOptionsExt
* os::unix::fs::OpenOptionsExt::mode
* os::unix::fs::DirEntryExt
* os::unix::fs::DirEntryExt::ino
* os::windows::fs::MetadataExt
* os::windows::fs::MetadataExt::file_attributes
* os::windows::fs::MetadataExt::creation_time
* os::windows::fs::MetadataExt::last_access_time
* os::windows::fs::MetadataExt::last_write_time
* os::windows::fs::MetadataExt::file_size

The `os::unix::fs::Metadata` structure was also removed entirely, moving all of
its associated methods into the `os::unix::fs::MetadataExt` trait instead. The
methods are all marked as `#[stable]` still.

As some minor cleanup, some deprecated and unstable fs apis were also removed:

* File::path
* Metadata::accessed
* Metadata::modified

Features that were explicitly left unstable include:

* fs::WalkDir - the semantics of this were not considered in the recent fs
  expansion RFC.
* fs::DirBuilder - it's still not 100% clear if the naming is right here and if
  the set of functionality exposed is appropriate.
* fs::canonicalize - the implementation on Windows here is specifically in
  question as it always returns a verbatim path. Additionally the Unix
  implementation is susceptible to buffer overflows on long paths unfortunately.
* fs::PathExt - as this is just a convenience trait, it is not stabilized at
  this time.
* fs::set_file_times - this funciton is still waiting on a time abstraction.

5 files changed, 105 insertions, 77 deletions

diff --git a/src/libstd/sys/unix/ext/fs.rs b/src/libstd/sys/unix/ext/fs.rs
index 7d982152dd6..97703b83056 100644
--- a/src/libstd/sys/unix/ext/fs.rs
+++ b/src/libstd/sys/unix/ext/fs.rs
@@ -16,11 +16,10 @@ use prelude::v1::*;
 
 use fs::{self, Permissions, OpenOptions};
 use io;
-use mem;
 use os::raw::c_long;
 use os::unix::raw;
 use path::Path;
-use sys::platform;
+use sys::fs::MetadataExt as UnixMetadataExt;
 use sys;
 use sys_common::{FromInner, AsInner, AsInnerMut};
 
@@ -64,14 +63,24 @@ pub const SETGID: raw::mode_t = 0o2000;
 pub const STICKY_BIT: raw::mode_t = 0o1000;
 
 /// Unix-specific extensions to `Permissions`
-#[unstable(feature = "fs_ext",
-           reason = "may want a more useful mode abstraction")]
+#[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.
+    #[stable(feature = "fs_ext", since = "1.1.0")]
     fn mode(&self) -> raw::mode_t;
+
+    /// Sets the underlying raw `mode_t` bits for this set of permissions.
+    #[stable(feature = "fs_ext", since = "1.1.0")]
     fn set_mode(&mut self, mode: raw::mode_t);
+
+    /// Creates a new instance of `Permissions` from the given set of Unix
+    /// permission bits.
+    #[stable(feature = "fs_ext", since = "1.1.0")]
     fn from_mode(mode: raw::mode_t) -> Self;
 }
 
+#[stable(feature = "fs_ext", since = "1.1.0")]
 impl PermissionsExt for Permissions {
     fn mode(&self) -> raw::mode_t { self.as_inner().mode() }
 
@@ -85,41 +94,23 @@ impl PermissionsExt for Permissions {
 }
 
 /// Unix-specific extensions to `OpenOptions`
-#[unstable(feature = "fs_ext",
-           reason = "may want a more useful mode abstraction")]
+#[stable(feature = "fs_ext", since = "1.1.0")]
 pub trait OpenOptionsExt {
     /// Sets the mode bits that a new file will be created with.
     ///
     /// If a new file is created as part of a `File::open_opts` call then this
     /// specified `mode` will be used as the permission bits for the new file.
+    #[stable(feature = "fs_ext", since = "1.1.0")]
     fn mode(&mut self, mode: raw::mode_t) -> &mut Self;
 }
 
+#[stable(feature = "fs_ext", since = "1.1.0")]
 impl OpenOptionsExt for OpenOptions {
     fn mode(&mut self, mode: raw::mode_t) -> &mut OpenOptions {
         self.as_inner_mut().mode(mode); self
     }
 }
 
-#[unstable(feature = "metadata_ext", reason = "recently added API")]
-pub struct Metadata(sys::fs::FileAttr);
-
-#[unstable(feature = "metadata_ext", reason = "recently added API")]
-pub trait MetadataExt {
-    fn as_raw(&self) -> &Metadata;
-}
-
-impl MetadataExt for fs::Metadata {
-    fn as_raw(&self) -> &Metadata {
-        let inner: &sys::fs::FileAttr = self.as_inner();
-        unsafe { mem::transmute(inner) }
-    }
-}
-
-impl AsInner<platform::raw::stat> for Metadata {
-    fn as_inner(&self) -> &platform::raw::stat { self.0.as_inner() }
-}
-
 // Hm, why are there casts here to the returned type, shouldn't the types always
 // be the same? Right you are! Turns out, however, on android at least the types
 // in the raw `stat` structure are not the same as the types being returned. Who
@@ -127,33 +118,72 @@ impl AsInner<platform::raw::stat> for Metadata {
 //
 // As a result to make sure this compiles for all platforms we do the manual
 // casts and rely on manual lowering to `stat` if the raw type is desired.
-#[unstable(feature = "metadata_ext", reason = "recently added API")]
-impl Metadata {
-    pub fn dev(&self) -> raw::dev_t { self.0.raw().st_dev as raw::dev_t }
-    pub fn ino(&self) -> raw::ino_t { self.0.raw().st_ino as raw::ino_t }
-    pub fn mode(&self) -> raw::mode_t { self.0.raw().st_mode as raw::mode_t }
-    pub fn nlink(&self) -> raw::nlink_t { self.0.raw().st_nlink as raw::nlink_t }
-    pub fn uid(&self) -> raw::uid_t { self.0.raw().st_uid as raw::uid_t }
-    pub fn gid(&self) -> raw::gid_t { self.0.raw().st_gid as raw::gid_t }
-    pub fn rdev(&self) -> raw::dev_t { self.0.raw().st_rdev as raw::dev_t }
-    pub fn size(&self) -> raw::off_t { self.0.raw().st_size as raw::off_t }
-    pub fn atime(&self) -> raw::time_t { self.0.raw().st_atime }
-    pub fn atime_nsec(&self) -> c_long { self.0.raw().st_atime_nsec as c_long }
-    pub fn mtime(&self) -> raw::time_t { self.0.raw().st_mtime }
-    pub fn mtime_nsec(&self) -> c_long { self.0.raw().st_mtime_nsec as c_long }
-    pub fn ctime(&self) -> raw::time_t { self.0.raw().st_ctime }
-    pub fn ctime_nsec(&self) -> c_long { self.0.raw().st_ctime_nsec as c_long }
-
-    pub fn blksize(&self) -> raw::blksize_t {
-        self.0.raw().st_blksize as raw::blksize_t
+#[stable(feature = "metadata_ext", since = "1.1.0")]
+pub trait MetadataExt {
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn dev(&self) -> raw::dev_t;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn ino(&self) -> raw::ino_t;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn mode(&self) -> raw::mode_t;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn nlink(&self) -> raw::nlink_t;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn uid(&self) -> raw::uid_t;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn gid(&self) -> raw::gid_t;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn rdev(&self) -> raw::dev_t;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn size(&self) -> raw::off_t;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn atime(&self) -> raw::time_t;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn atime_nsec(&self) -> c_long;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn mtime(&self) -> raw::time_t;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn mtime_nsec(&self) -> c_long;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn ctime(&self) -> raw::time_t;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn ctime_nsec(&self) -> c_long;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn blksize(&self) -> raw::blksize_t;
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
+    fn blocks(&self) -> raw::blkcnt_t;
+}
+
+impl MetadataExt for fs::Metadata {
+    fn dev(&self) -> raw::dev_t { self.as_raw_stat().st_dev as raw::dev_t }
+    fn ino(&self) -> raw::ino_t { self.as_raw_stat().st_ino as raw::ino_t }
+    fn mode(&self) -> raw::mode_t { self.as_raw_stat().st_mode as raw::mode_t }
+    fn nlink(&self) -> raw::nlink_t { self.as_raw_stat().st_nlink as raw::nlink_t }
+    fn uid(&self) -> raw::uid_t { self.as_raw_stat().st_uid as raw::uid_t }
+    fn gid(&self) -> raw::gid_t { self.as_raw_stat().st_gid as raw::gid_t }
+    fn rdev(&self) -> raw::dev_t { self.as_raw_stat().st_rdev as raw::dev_t }
+    fn size(&self) -> raw::off_t { self.as_raw_stat().st_size as raw::off_t }
+    fn atime(&self) -> raw::time_t { self.as_raw_stat().st_atime }
+    fn atime_nsec(&self) -> c_long { self.as_raw_stat().st_atime_nsec as c_long }
+    fn mtime(&self) -> raw::time_t { self.as_raw_stat().st_mtime }
+    fn mtime_nsec(&self) -> c_long { self.as_raw_stat().st_mtime_nsec as c_long }
+    fn ctime(&self) -> raw::time_t { self.as_raw_stat().st_ctime }
+    fn ctime_nsec(&self) -> c_long { self.as_raw_stat().st_ctime_nsec as c_long }
+
+    fn blksize(&self) -> raw::blksize_t {
+        self.as_raw_stat().st_blksize as raw::blksize_t
     }
-    pub fn blocks(&self) -> raw::blkcnt_t {
-        self.0.raw().st_blocks as raw::blkcnt_t
+    fn blocks(&self) -> raw::blkcnt_t {
+        self.as_raw_stat().st_blocks as raw::blkcnt_t
     }
 }
 
-#[unstable(feature = "dir_entry_ext", reason = "recently added API")]
+/// Unix-specific extension methods for `fs::DirEntry`
+#[stable(feature = "dir_entry_ext", since = "1.1.0")]
 pub trait DirEntryExt {
+    /// Returns the underlying `d_ino` field in the contained `dirent`
+    /// structure.
+    #[stable(feature = "dir_entry_ext", since = "1.1.0")]
     fn ino(&self) -> raw::ino_t;
 }
 
diff --git a/src/libstd/sys/unix/ext/raw.rs b/src/libstd/sys/unix/ext/raw.rs
index 8fe4b90456a..fa380abe6c5 100644
--- a/src/libstd/sys/unix/ext/raw.rs
+++ b/src/libstd/sys/unix/ext/raw.rs
@@ -10,11 +10,11 @@
 
 //! Unix-specific primitives available on all unix platforms
 
-#![unstable(feature = "raw_ext", reason = "recently added API")]
+#![stable(feature = "raw_ext", since = "1.1.0")]
 
-pub type uid_t = u32;
-pub type gid_t = u32;
-pub type pid_t = i32;
+#[stable(feature = "raw_ext", since = "1.1.0")] pub type uid_t = u32;
+#[stable(feature = "raw_ext", since = "1.1.0")] pub type gid_t = u32;
+#[stable(feature = "raw_ext", since = "1.1.0")] pub type pid_t = i32;
 
 #[doc(inline)]
 pub use sys::platform::raw::{dev_t, ino_t, mode_t, nlink_t, off_t, blksize_t};
diff --git a/src/libstd/sys/unix/fs.rs b/src/libstd/sys/unix/fs.rs
index 58e205a01ca..128284834ab 100644
--- a/src/libstd/sys/unix/fs.rs
+++ b/src/libstd/sys/unix/fs.rs
@@ -69,42 +69,33 @@ impl FileAttr {
         FilePermissions { mode: (self.stat.st_mode as mode_t) & 0o777 }
     }
 
-    pub fn accessed(&self) -> u64 {
-        self.mktime(self.stat.st_atime as u64, self.stat.st_atime_nsec as u64)
-    }
-    pub fn modified(&self) -> u64 {
-        self.mktime(self.stat.st_mtime as u64, self.stat.st_mtime_nsec as u64)
-    }
-
     pub fn file_type(&self) -> FileType {
         FileType { mode: self.stat.st_mode as mode_t }
     }
-
-    pub fn raw(&self) -> &raw::stat { &self.stat }
-
-    // times are in milliseconds (currently)
-    fn mktime(&self, secs: u64, nsecs: u64) -> u64 {
-        secs * 1000 + nsecs / 1000000
-    }
 }
 
 impl AsInner<raw::stat> for FileAttr {
     fn as_inner(&self) -> &raw::stat { &self.stat }
 }
 
-#[unstable(feature = "metadata_ext", reason = "recently added API")]
+/// OS-specific extension methods for `fs::Metadata`
+#[stable(feature = "metadata_ext", since = "1.1.0")]
 pub trait MetadataExt {
+    /// Gain a reference to the underlying `stat` structure which contains the
+    /// raw information returned by the OS.
+    ///
+    /// The contents of the returned `stat` are **not** consistent across Unix
+    /// platforms. The `os::unix::fs::MetadataExt` trait contains the cross-Unix
+    /// abstractions contained within the raw stat.
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
     fn as_raw_stat(&self) -> &raw::stat;
 }
 
+#[stable(feature = "metadata_ext", since = "1.1.0")]
 impl MetadataExt for ::fs::Metadata {
     fn as_raw_stat(&self) -> &raw::stat { &self.as_inner().stat }
 }
 
-impl MetadataExt for ::os::unix::fs::Metadata {
-    fn as_raw_stat(&self) -> &raw::stat { self.as_inner() }
-}
-
 impl FilePermissions {
     pub fn readonly(&self) -> bool { self.mode & 0o222 == 0 }
     pub fn set_readonly(&mut self, readonly: bool) {
diff --git a/src/libstd/sys/windows/ext/fs.rs b/src/libstd/sys/windows/ext/fs.rs
index 28d9b3e0476..f629e983ce5 100644
--- a/src/libstd/sys/windows/ext/fs.rs
+++ b/src/libstd/sys/windows/ext/fs.rs
@@ -21,7 +21,8 @@ use sys;
 use sys_common::{AsInnerMut, AsInner};
 
 /// Windows-specific extensions to `OpenOptions`
-#[unstable(feature = "fs_ext", reason = "may require more thought/methods")]
+#[unstable(feature = "open_options_ext",
+           reason = "may require more thought/methods")]
 pub trait OpenOptionsExt {
     /// Overrides the `dwDesiredAccess` argument to the call to `CreateFile`
     /// with the specified value.
@@ -66,39 +67,45 @@ impl OpenOptionsExt for OpenOptions {
 
 /// Extension methods for `fs::Metadata` to access the raw fields contained
 /// within.
-#[unstable(feature = "metadata_ext", reason = "recently added API")]
+#[stable(feature = "metadata_ext", since = "1.1.0")]
 pub trait MetadataExt {
     /// Returns the value of the `dwFileAttributes` field of this metadata.
     ///
     /// This field contains the file system attribute information for a file
     /// or directory.
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
     fn file_attributes(&self) -> u32;
 
     /// Returns the value of the `ftCreationTime` field of this metadata.
     ///
     /// The returned 64-bit value represents the number of 100-nanosecond
     /// intervals since January 1, 1601 (UTC).
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
     fn creation_time(&self) -> u64;
 
     /// Returns the value of the `ftLastAccessTime` field of this metadata.
     ///
     /// The returned 64-bit value represents the number of 100-nanosecond
     /// intervals since January 1, 1601 (UTC).
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
     fn last_access_time(&self) -> u64;
 
     /// Returns the value of the `ftLastWriteTime` field of this metadata.
     ///
     /// The returned 64-bit value represents the number of 100-nanosecond
     /// intervals since January 1, 1601 (UTC).
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
     fn last_write_time(&self) -> u64;
 
     /// Returns the value of the `nFileSize{High,Low}` fields of this
     /// metadata.
     ///
     /// The returned value does not have meaning for directories.
+    #[stable(feature = "metadata_ext", since = "1.1.0")]
     fn file_size(&self) -> u64;
 }
 
+#[stable(feature = "metadata_ext", since = "1.1.0")]
 impl MetadataExt for Metadata {
     fn file_attributes(&self) -> u32 { self.as_inner().attrs() }
     fn creation_time(&self) -> u64 { self.as_inner().created() }
diff --git a/src/libstd/sys/windows/ext/raw.rs b/src/libstd/sys/windows/ext/raw.rs
index 656e480ad09..e1796d4b5f0 100644
--- a/src/libstd/sys/windows/ext/raw.rs
+++ b/src/libstd/sys/windows/ext/raw.rs
@@ -10,12 +10,12 @@
 
 //! Windows-specific primitives
 
-#![unstable(feature = "raw_ext", reason = "recently added API")]
+#[stable(feature = "raw_ext", since = "1.1.0")]
 
-use os::raw;
+use os::raw::c_void;
 
-pub type HANDLE = *mut raw::c_void;
+#[stable(feature = "raw_ext", since = "1.1.0")] pub type HANDLE = *mut c_void;
 #[cfg(target_pointer_width = "32")]
-pub type SOCKET = u32;
+#[stable(feature = "raw_ext", since = "1.1.0")] pub type SOCKET = u32;
 #[cfg(target_pointer_width = "64")]
-pub type SOCKET = u64;
+#[stable(feature = "raw_ext", since = "1.1.0")] pub type SOCKET = u64;