Auto merge of #23353 - alexcrichton:stabilize-os, r=aturon

This commit starts to organize the `std::os::$platform` modules and in the
process stabilizes some of the functionality contained within. The organization
of these modules will reflect the organization of the standard library itself
with extension traits for primitives in the same corresponding module.

The OS-specific modules will grow more functionality over time including
concrete types that are not extending functionality of other structures, and
these will either go into the closest module in `std::os::$platform` or they
will grow a new module in the hierarchy.

The following items are now stable:

* `os::{unix, windows}`
* `unix::ffi`
* `unix::ffi::OsStrExt`
* `unix::ffi::OsStrExt::{from_bytes, as_bytes, to_cstring}`
* `unix::ffi::OsString`
* `unix::ffi::OsStringExt::{from_vec, into_vec}`
* `unix::process`
* `unix::process::CommandExt`
* `unix::process::CommandExt::{uid, gid}`
* `unix::process::ExitStatusExt`
* `unix::process::ExitStatusExt::signal`
* `unix::prelude`
* `windows::ffi`
* `windows::ffi::OsStringExt`
* `windows::ffi::OsStringExt::from_wide`
* `windows::ffi::OsStrExt`
* `windows::ffi::OsStrExt::encode_wide`
* `windows::prelude`

The following items remain unstable:

* `unix::io`
* `unix::io::{Fd, AsRawFd}`
* `unix::fs::{PermissionsExt, OpenOptionsExt}`
* `windows::io`
* `windows::io::{Handle, AsRawHandle}`
* `windows::io::{Socket, AsRawSocket}`
* `windows::fs`
* `windows::fs::OpenOptionsExt`

Due to the reorgnization of the platform extension modules, this commit is a
breaking change. Most imports can be fixed by adding the relevant libstd module
in the `use` path (such as `ffi` or `fs`).

[breaking-change]

3 files changed, 212 insertions, 167 deletions

diff --git a/src/libstd/sys/unix/ext.rs b/src/libstd/sys/unix/ext.rs
index 3dd05319194..0805949d560 100644
--- a/src/libstd/sys/unix/ext.rs
+++ b/src/libstd/sys/unix/ext.rs
@@ -29,183 +29,206 @@
 //! }
 //! ```
 
-#![unstable(feature = "std_misc")]
-
-use prelude::v1::*;
-
-use ffi::{CString, NulError, OsStr, OsString};
-use fs::{self, Permissions, OpenOptions};
-use net;
-use mem;
-use process;
-use sys;
-use sys::os_str::Buf;
-use sys_common::{AsInner, AsInnerMut, IntoInner, FromInner};
-use libc::{self, gid_t, uid_t};
-
-#[allow(deprecated)] use old_io;
-
-/// Raw file descriptors.
-pub type Fd = libc::c_int;
-
-/// Extract raw file descriptor
-pub trait AsRawFd {
-    /// Extract the raw file descriptor, without taking any ownership.
-    fn as_raw_fd(&self) -> Fd;
-}
+#![stable(feature = "rust1", since = "1.0.0")]
+
+/// Unix-specific extensions to general I/O primitives
+#[unstable(feature = "io_ext",
+           reason = "may want a slightly different organization or a more \
+                     general file descriptor primitive")]
+pub mod io {
+    #[allow(deprecated)] use old_io;
+    use fs;
+    use libc;
+    use net;
+    use sys_common::AsInner;
+
+    /// Raw file descriptors.
+    pub type Fd = libc::c_int;
+
+    /// Extract raw file descriptor
+    pub trait AsRawFd {
+        /// Extract the raw file descriptor, without taking any ownership.
+        fn as_raw_fd(&self) -> Fd;
+    }
 
-#[allow(deprecated)]
-impl AsRawFd for old_io::fs::File {
-    fn as_raw_fd(&self) -> Fd {
-        self.as_inner().fd()
+    #[allow(deprecated)]
+    impl AsRawFd for old_io::fs::File {
+        fn as_raw_fd(&self) -> Fd {
+            self.as_inner().fd()
+        }
     }
-}
 
-impl AsRawFd for fs::File {
-    fn as_raw_fd(&self) -> Fd {
-        self.as_inner().fd().raw()
+    impl AsRawFd for fs::File {
+        fn as_raw_fd(&self) -> Fd {
+            self.as_inner().fd().raw()
+        }
     }
-}
 
-#[allow(deprecated)]
-impl AsRawFd for old_io::pipe::PipeStream {
-    fn as_raw_fd(&self) -> Fd {
-        self.as_inner().fd()
+    #[allow(deprecated)]
+    impl AsRawFd for old_io::pipe::PipeStream {
+        fn as_raw_fd(&self) -> Fd {
+            self.as_inner().fd()
+        }
     }
-}
 
-#[allow(deprecated)]
-impl AsRawFd for old_io::net::pipe::UnixStream {
-    fn as_raw_fd(&self) -> Fd {
-        self.as_inner().fd()
+    #[allow(deprecated)]
+    impl AsRawFd for old_io::net::pipe::UnixStream {
+        fn as_raw_fd(&self) -> Fd {
+            self.as_inner().fd()
+        }
     }
-}
 
-#[allow(deprecated)]
-impl AsRawFd for old_io::net::pipe::UnixListener {
-    fn as_raw_fd(&self) -> Fd {
-        self.as_inner().fd()
+    #[allow(deprecated)]
+    impl AsRawFd for old_io::net::pipe::UnixListener {
+        fn as_raw_fd(&self) -> Fd {
+            self.as_inner().fd()
+        }
     }
-}
 
-#[allow(deprecated)]
-impl AsRawFd for old_io::net::pipe::UnixAcceptor {
-    fn as_raw_fd(&self) -> Fd {
-        self.as_inner().fd()
+    #[allow(deprecated)]
+    impl AsRawFd for old_io::net::pipe::UnixAcceptor {
+        fn as_raw_fd(&self) -> Fd {
+            self.as_inner().fd()
+        }
     }
-}
 
-#[allow(deprecated)]
-impl AsRawFd for old_io::net::tcp::TcpStream {
-    fn as_raw_fd(&self) -> Fd {
-        self.as_inner().fd()
+    #[allow(deprecated)]
+    impl AsRawFd for old_io::net::tcp::TcpStream {
+        fn as_raw_fd(&self) -> Fd {
+            self.as_inner().fd()
+        }
     }
-}
 
-#[allow(deprecated)]
-impl AsRawFd for old_io::net::tcp::TcpListener {
-    fn as_raw_fd(&self) -> Fd {
-        self.as_inner().fd()
+    #[allow(deprecated)]
+    impl AsRawFd for old_io::net::tcp::TcpListener {
+        fn as_raw_fd(&self) -> Fd {
+            self.as_inner().fd()
+        }
     }
-}
 
-#[allow(deprecated)]
-impl AsRawFd for old_io::net::tcp::TcpAcceptor {
-    fn as_raw_fd(&self) -> Fd {
-        self.as_inner().fd()
+    #[allow(deprecated)]
+    impl AsRawFd for old_io::net::tcp::TcpAcceptor {
+        fn as_raw_fd(&self) -> Fd {
+            self.as_inner().fd()
+        }
     }
-}
 
-#[allow(deprecated)]
-impl AsRawFd for old_io::net::udp::UdpSocket {
-    fn as_raw_fd(&self) -> Fd {
-        self.as_inner().fd()
+    #[allow(deprecated)]
+    impl AsRawFd for old_io::net::udp::UdpSocket {
+        fn as_raw_fd(&self) -> Fd {
+            self.as_inner().fd()
+        }
     }
-}
 
-impl AsRawFd for net::TcpStream {
-    fn as_raw_fd(&self) -> Fd { *self.as_inner().socket().as_inner() }
-}
-impl AsRawFd for net::TcpListener {
-    fn as_raw_fd(&self) -> Fd { *self.as_inner().socket().as_inner() }
-}
-impl AsRawFd for net::UdpSocket {
-    fn as_raw_fd(&self) -> Fd { *self.as_inner().socket().as_inner() }
+    impl AsRawFd for net::TcpStream {
+        fn as_raw_fd(&self) -> Fd { *self.as_inner().socket().as_inner() }
+    }
+    impl AsRawFd for net::TcpListener {
+        fn as_raw_fd(&self) -> Fd { *self.as_inner().socket().as_inner() }
+    }
+    impl AsRawFd for net::UdpSocket {
+        fn as_raw_fd(&self) -> Fd { *self.as_inner().socket().as_inner() }
+    }
 }
 
 ////////////////////////////////////////////////////////////////////////////////
 // OsString and OsStr
 ////////////////////////////////////////////////////////////////////////////////
 
-/// Unix-specific extensions to `OsString`.
-pub trait OsStringExt {
-    /// Create an `OsString` from a byte vector.
-    fn from_vec(vec: Vec<u8>) -> Self;
-
-    /// Yield the underlying byte vector of this `OsString`.
-    fn into_vec(self) -> Vec<u8>;
-}
-
-impl OsStringExt for OsString {
-    fn from_vec(vec: Vec<u8>) -> OsString {
-        FromInner::from_inner(Buf { inner: vec })
+/// Unix-specific extension to the primitives in the `std::ffi` module
+#[stable(feature = "rust1", since = "1.0.0")]
+pub mod ffi {
+    use ffi::{CString, NulError, OsStr, OsString};
+    use mem;
+    use prelude::v1::*;
+    use sys::os_str::Buf;
+    use sys_common::{FromInner, IntoInner, AsInner};
+
+    /// Unix-specific extensions to `OsString`.
+    #[stable(feature = "rust1", since = "1.0.0")]
+    pub trait OsStringExt {
+        /// Create an `OsString` from a byte vector.
+        #[stable(feature = "rust1", since = "1.0.0")]
+        fn from_vec(vec: Vec<u8>) -> Self;
+
+        /// Yield the underlying byte vector of this `OsString`.
+        #[stable(feature = "rust1", since = "1.0.0")]
+        fn into_vec(self) -> Vec<u8>;
     }
 
-    fn into_vec(self) -> Vec<u8> {
-        self.into_inner().inner
+    #[stable(feature = "rust1", since = "1.0.0")]
+    impl OsStringExt for OsString {
+        fn from_vec(vec: Vec<u8>) -> OsString {
+            FromInner::from_inner(Buf { inner: vec })
+        }
+        fn into_vec(self) -> Vec<u8> {
+            self.into_inner().inner
+        }
     }
-}
-
-/// Unix-specific extensions to `OsStr`.
-pub trait OsStrExt {
-    fn from_bytes(slice: &[u8]) -> &OsStr;
 
-    /// Get the underlying byte view of the `OsStr` slice.
-    fn as_bytes(&self) -> &[u8];
+    /// Unix-specific extensions to `OsStr`.
+    #[stable(feature = "rust1", since = "1.0.0")]
+    pub trait OsStrExt {
+        #[stable(feature = "rust1", since = "1.0.0")]
+        fn from_bytes(slice: &[u8]) -> &Self;
 
-    /// Convert the `OsStr` slice into a `CString`.
-    fn to_cstring(&self) -> Result<CString, NulError>;
-}
+        /// Get the underlying byte view of the `OsStr` slice.
+        #[stable(feature = "rust1", since = "1.0.0")]
+        fn as_bytes(&self) -> &[u8];
 
-impl OsStrExt for OsStr {
-    fn from_bytes(slice: &[u8]) -> &OsStr {
-        unsafe { mem::transmute(slice) }
-    }
-    fn as_bytes(&self) -> &[u8] {
-        &self.as_inner().inner
+        /// Convert the `OsStr` slice into a `CString`.
+        #[stable(feature = "rust1", since = "1.0.0")]
+        fn to_cstring(&self) -> Result<CString, NulError>;
     }
 
-    fn to_cstring(&self) -> Result<CString, NulError> {
-        CString::new(self.as_bytes())
+    #[stable(feature = "rust1", since = "1.0.0")]
+    impl OsStrExt for OsStr {
+        fn from_bytes(slice: &[u8]) -> &OsStr {
+            unsafe { mem::transmute(slice) }
+        }
+        fn as_bytes(&self) -> &[u8] {
+            &self.as_inner().inner
+        }
+        fn to_cstring(&self) -> Result<CString, NulError> {
+            CString::new(self.as_bytes())
+        }
     }
 }
 
-// Unix-specific extensions to `Permissions`
-pub trait PermissionsExt {
-    fn mode(&self) -> i32;
-    fn set_mode(&mut self, mode: i32);
-}
+/// Unix-specific extensions to primitives in the `std::fs` module.
+#[unstable(feature = "fs_ext",
+           reason = "may want a more useful mode abstraction")]
+pub mod fs {
+    use sys_common::{FromInner, AsInner, AsInnerMut};
+    use fs::{Permissions, OpenOptions};
+
+    /// Unix-specific extensions to `Permissions`
+    pub trait PermissionsExt {
+        fn mode(&self) -> i32;
+        fn set_mode(&mut self, mode: i32);
+    }
 
-impl PermissionsExt for Permissions {
-    fn mode(&self) -> i32 { self.as_inner().mode() }
+    impl PermissionsExt for Permissions {
+        fn mode(&self) -> i32 { self.as_inner().mode() }
 
-    fn set_mode(&mut self, mode: i32) {
-        *self = FromInner::from_inner(FromInner::from_inner(mode));
+        fn set_mode(&mut self, mode: i32) {
+            *self = FromInner::from_inner(FromInner::from_inner(mode));
+        }
     }
-}
 
-// Unix-specific extensions to `OpenOptions`
-pub trait OpenOptionsExt {
-    /// Set 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.
-    fn mode(&mut self, mode: i32) -> &mut Self;
-}
+    /// Unix-specific extensions to `OpenOptions`
+    pub trait OpenOptionsExt {
+        /// Set 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.
+        fn mode(&mut self, mode: i32) -> &mut Self;
+    }
 
-impl OpenOptionsExt for OpenOptions {
-    fn mode(&mut self, mode: i32) -> &mut OpenOptions {
-        self.as_inner_mut().mode(mode); self
+    impl OpenOptionsExt for OpenOptions {
+        fn mode(&mut self, mode: i32) -> &mut OpenOptions {
+            self.as_inner_mut().mode(mode); self
+        }
     }
 }
 
@@ -213,41 +236,58 @@ impl OpenOptionsExt for OpenOptions {
 // Process and Command
 ////////////////////////////////////////////////////////////////////////////////
 
-/// Unix-specific extensions to the `std::process::Command` builder
-pub trait CommandExt {
-    /// Sets the child process's user id. This translates to a
-    /// `setuid` call in the child process. Failure in the `setuid`
-    /// call will cause the spawn to fail.
-    fn uid(&mut self, id: uid_t) -> &mut process::Command;
+/// Unix-specific extensions to primitives in the `std::process` module.
+#[stable(feature = "rust1", since = "1.0.0")]
+pub mod process {
+    use prelude::v1::*;
+    use libc::{uid_t, gid_t};
+    use process;
+    use sys;
+    use sys_common::{AsInnerMut, AsInner};
+
+    /// Unix-specific extensions to the `std::process::Command` builder
+    #[stable(feature = "rust1", since = "1.0.0")]
+    pub trait CommandExt {
+        /// Sets the child process's user id. This translates to a
+        /// `setuid` call in the child process. Failure in the `setuid`
+        /// call will cause the spawn to fail.
+        #[stable(feature = "rust1", since = "1.0.0")]
+        fn uid(&mut self, id: uid_t) -> &mut process::Command;
+
+        /// Similar to `uid`, but sets the group id of the child process. This has
+        /// the same semantics as the `uid` field.
+        #[stable(feature = "rust1", since = "1.0.0")]
+        fn gid(&mut self, id: gid_t) -> &mut process::Command;
+    }
 
-    /// Similar to `uid`, but sets the group id of the child process. This has
-    /// the same semantics as the `uid` field.
-    fn gid(&mut self, id: gid_t) -> &mut process::Command;
-}
+    #[stable(feature = "rust1", since = "1.0.0")]
+    impl CommandExt for process::Command {
+        fn uid(&mut self, id: uid_t) -> &mut process::Command {
+            self.as_inner_mut().uid = Some(id);
+            self
+        }
 
-impl CommandExt for process::Command {
-    fn uid(&mut self, id: uid_t) -> &mut process::Command {
-        self.as_inner_mut().uid = Some(id);
-        self
+        fn gid(&mut self, id: gid_t) -> &mut process::Command {
+            self.as_inner_mut().gid = Some(id);
+            self
+        }
     }
 
-    fn gid(&mut self, id: gid_t) -> &mut process::Command {
-        self.as_inner_mut().gid = Some(id);
-        self
+    /// Unix-specific extensions to `std::process::ExitStatus`
+    #[stable(feature = "rust1", since = "1.0.0")]
+    pub trait ExitStatusExt {
+        /// If the process was terminated by a signal, returns that signal.
+        #[stable(feature = "rust1", since = "1.0.0")]
+        fn signal(&self) -> Option<i32>;
     }
-}
-
-/// Unix-specific extensions to `std::process::ExitStatus`
-pub trait ExitStatusExt {
-    /// If the process was terminated by a signal, returns that signal.
-    fn signal(&self) -> Option<i32>;
-}
 
-impl ExitStatusExt for process::ExitStatus {
-    fn signal(&self) -> Option<i32> {
-        match *self.as_inner() {
-            sys::process2::ExitStatus::Signal(s) => Some(s),
-            _ => None
+    #[stable(feature = "rust1", since = "1.0.0")]
+    impl ExitStatusExt for process::ExitStatus {
+        fn signal(&self) -> Option<i32> {
+            match *self.as_inner() {
+                sys::process2::ExitStatus::Signal(s) => Some(s),
+                _ => None
+            }
         }
     }
 }
@@ -259,9 +299,14 @@ impl ExitStatusExt for process::ExitStatus {
 /// A prelude for conveniently writing platform-specific code.
 ///
 /// Includes all extension traits, and some important type definitions.
+#[stable(feature = "rust1", since = "1.0.0")]
 pub mod prelude {
     #[doc(no_inline)]
-    pub use super::{Fd, AsRawFd, OsStrExt, OsStringExt, PermissionsExt};
+    pub use super::io::{Fd, AsRawFd};
+    #[doc(no_inline)] #[stable(feature = "rust1", since = "1.0.0")]
+    pub use super::ffi::{OsStrExt, OsStringExt};
     #[doc(no_inline)]
-    pub use super::{CommandExt, ExitStatusExt};
+    pub use super::fs::{PermissionsExt, OpenOptionsExt};
+    #[doc(no_inline)] #[stable(feature = "rust1", since = "1.0.0")]
+    pub use super::process::{CommandExt, ExitStatusExt};
 }
diff --git a/src/libstd/sys/unix/os.rs b/src/libstd/sys/unix/os.rs
index b0ad9ab6937..904341bfbc3 100644
--- a/src/libstd/sys/unix/os.rs
+++ b/src/libstd/sys/unix/os.rs
@@ -13,7 +13,7 @@
 #![allow(unused_imports)] // lots of cfg code here
 
 use prelude::v1::*;
-use os::unix::*;
+use os::unix::prelude::*;
 
 use error::Error as StdError;
 use ffi::{CString, CStr, OsString, OsStr, AsOsStr};
diff --git a/src/libstd/sys/unix/process2.rs b/src/libstd/sys/unix/process2.rs
index 03b77eb75d7..20c409154b8 100644
--- a/src/libstd/sys/unix/process2.rs
+++ b/src/libstd/sys/unix/process2.rs
@@ -9,6 +9,7 @@
 // except according to those terms.
 
 use prelude::v1::*;
+use os::unix::prelude::*;
 
 use collections::HashMap;
 use env;
@@ -17,7 +18,6 @@ use fmt;
 use io::{self, Error, ErrorKind};
 use libc::{self, pid_t, c_void, c_int, gid_t, uid_t};
 use mem;
-use os::unix::OsStrExt;
 use ptr;
 use sys::pipe2::AnonPipe;
 use sys::{self, retry, c, cvt};