From db16ca7c839c6dcc5a3103b5e0b37239dd21e450 Mon Sep 17 00:00:00 2001 From: David LeGare Date: Fri, 5 May 2017 20:35:07 -0500 Subject: Update documention in windows::ffi --- src/libstd/sys/windows/ext/ffi.rs | 42 ++++++++++++++++++++++++++++++++++----- src/libstd/sys/windows/ext/mod.rs | 10 ++++++---- src/libstd/sys_common/wtf8.rs | 1 + 3 files changed, 44 insertions(+), 9 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/sys/windows/ext/ffi.rs b/src/libstd/sys/windows/ext/ffi.rs index 253787546c1..cb13595fcd6 100644 --- a/src/libstd/sys/windows/ext/ffi.rs +++ b/src/libstd/sys/windows/ext/ffi.rs @@ -26,8 +26,22 @@ pub trait OsStringExt { /// Creates an `OsString` from a potentially ill-formed UTF-16 slice of /// 16-bit code units. /// - /// This is lossless: calling `.encode_wide()` on the resulting string + /// This is lossless: calling [`encode_wide()`] on the resulting string /// will always return the original code units. + /// + /// # Examples + /// + /// ``` + /// use std::ffi::OsString; + /// use std::os::windows::prelude::*; + /// + /// // UTF-16 encoding for "Unicode". + /// let source = [0x0055, 0x006E, 0x0069, 0x0063, 0x006F, 0x0064, 0x0065]; + /// + /// let string = OsString::from_wide(&source[..]); + /// ``` + /// + /// [`encode_wide()`]: ./trait.OsStrExt.html#tymethod.encode_wide #[stable(feature = "rust1", since = "1.0.0")] fn from_wide(wide: &[u16]) -> Self; } @@ -42,11 +56,29 @@ impl OsStringExt for OsString { /// Windows-specific extensions to `OsStr`. #[stable(feature = "rust1", since = "1.0.0")] pub trait OsStrExt { - /// Re-encodes an `OsStr` as a wide character sequence, - /// i.e. potentially ill-formed UTF-16. + /// Re-encodes an `OsStr` as a wide character sequence, i.e. potentially + /// ill-formed UTF-16. + /// + /// This is lossless: calling [`OsString::from_wide()`] and then + /// `encode_wide()` on the result will yield the original code units. + /// Note that the encoding does not add a final null terminator. + /// + /// # Examples + /// + /// ``` + /// use std::ffi::OsString; + /// use std::os::windows::prelude::*; + /// + /// // UTF-16 encoding for "Unicode". + /// let source = [0x0055, 0x006E, 0x0069, 0x0063, 0x006F, 0x0064, 0x0065]; + /// + /// let string = OsString::from_wide(&source[..]); + /// + /// let result: Vec = string.encode_wide().collect(); + /// assert_eq!(&source[..], &result[..]); + /// ``` /// - /// This is lossless. Note that the encoding does not include a final - /// null. + /// [`OsString::from_wide()`]: ./trait.OsStringExt.html#tymethod.from_wide #[stable(feature = "rust1", since = "1.0.0")] fn encode_wide(&self) -> EncodeWide; } diff --git a/src/libstd/sys/windows/ext/mod.rs b/src/libstd/sys/windows/ext/mod.rs index f12e50cc923..e07acad5e46 100644 --- a/src/libstd/sys/windows/ext/mod.rs +++ b/src/libstd/sys/windows/ext/mod.rs @@ -8,11 +8,13 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Experimental extensions to `std` for Windows. +//! Platform-specific extensions to `std` for Windows. //! -//! For now, this module is limited to extracting handles, file -//! descriptors, and sockets, but its functionality will grow over -//! time. +//! Provides access to platform-level information for Windows, and exposes +//! Windows-specific idioms that would otherwise be inappropriate as part +//! the core `std` library. These extensions allow developers to use +//! `std` types and idioms with Windows in a way that the noraml +//! platform-agnostic idioms would not normally support. #![stable(feature = "rust1", since = "1.0.0")] diff --git a/src/libstd/sys_common/wtf8.rs b/src/libstd/sys_common/wtf8.rs index 79aaf34ce2e..df5e4ef1d88 100644 --- a/src/libstd/sys_common/wtf8.rs +++ b/src/libstd/sys_common/wtf8.rs @@ -750,6 +750,7 @@ impl<'a> Iterator for Wtf8CodePoints<'a> { } } +/// Generates a wide character sequence for potentially ill-formed UTF-16. #[stable(feature = "rust1", since = "1.0.0")] #[derive(Clone)] pub struct EncodeWide<'a> { -- cgit 1.4.1-3-g733a5 From e406cd1ec9abb77236318db30e362e4654411a1a Mon Sep 17 00:00:00 2001 From: David LeGare Date: Fri, 5 May 2017 20:35:35 -0500 Subject: Update documentation in windows::ffi --- src/libstd/sys/windows/ext/fs.rs | 112 +++++++++++++++++++++++++++++++-------- 1 file changed, 91 insertions(+), 21 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/sys/windows/ext/fs.rs b/src/libstd/sys/windows/ext/fs.rs index c63dd8a47ca..ea322b9822a 100644 --- a/src/libstd/sys/windows/ext/fs.rs +++ b/src/libstd/sys/windows/ext/fs.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Windows-specific extensions for the primitives in `std::fs` +//! Windows-specific extensions for the primitives in the `std::fs` module. #![stable(feature = "rust1", since = "1.0.0")] @@ -35,6 +35,25 @@ pub trait FileExt { /// Note that similar to `File::read`, it is not an error to return with a /// short read. When returning from such a short read, the file pointer is /// still updated. + /// + /// # Examples + /// + /// ``` + /// use std::io; + /// use std::io::prelude::*; + /// use std::fs::File; + /// use std::os::windows::prelude::*; + /// + /// # fn foo() -> io::Result<()> { + /// let mut file = File::open("foo.txt")?; + /// let mut buffer = [0; 10]; + /// + /// // Read 10 bytes, starting 72 bytes from the + /// // start of the file. + /// file.seek_read(&mut buffer[..], 72)?; + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "file_offset", since = "1.15.0")] fn seek_read(&self, buf: &mut [u8], offset: u64) -> io::Result; @@ -52,6 +71,23 @@ pub trait FileExt { /// Note that similar to `File::write`, it is not an error to return a /// short write. When returning from such a short write, the file pointer /// is still updated. + /// + /// # Examples + /// + /// ``` + /// use std::io::prelude::*; + /// use std::fs::File; + /// use std::os::windows::prelude::*; + /// + /// # fn foo() -> std::io::Result<()> { + /// let mut buffer = File::create("foo.txt")?; + /// + /// // Write a byte string starting 72 bytes from + /// // the start of the file. + /// buffer.write(b"some bytes", offset)?; + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "file_offset", since = "1.15.0")] fn seek_write(&self, buf: &[u8], offset: u64) -> io::Result; } @@ -70,13 +106,13 @@ impl FileExt for fs::File { /// Windows-specific extensions to `OpenOptions` #[stable(feature = "open_options_ext", since = "1.10.0")] pub trait OpenOptionsExt { - /// Overrides the `dwDesiredAccess` argument to the call to `CreateFile` + /// Overrides the `dwDesiredAccess` argument to the call to [`CreateFile`] /// with the specified value. /// /// This will override the `read`, `write`, and `append` flags on the /// `OpenOptions` structure. This method provides fine-grained control over /// the permissions to read, write and append data, attributes (like hidden - /// and system) and extended attributes. + /// and system), and extended attributes. /// /// # Examples /// @@ -88,16 +124,20 @@ pub trait OpenOptionsExt { /// // to call `stat()` on the file /// let file = OpenOptions::new().access_mode(0).open("foo.txt"); /// ``` + /// + /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx #[stable(feature = "open_options_ext", since = "1.10.0")] fn access_mode(&mut self, access: u32) -> &mut Self; - /// Overrides the `dwShareMode` argument to the call to `CreateFile` with + /// Overrides the `dwShareMode` argument to the call to [`CreateFile`] with /// the specified value. /// /// By default `share_mode` is set to - /// `FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE`. Specifying - /// less permissions denies others to read from, write to and/or delete the - /// file while it is open. + /// `FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE`. This allows + /// other processes to to read, write, and delete/rename the same file + /// while it is open. Removing any of the flags will prevent other + /// processes from performing the corresponding operation until the file + /// handle is closed. /// /// # Examples /// @@ -106,42 +146,46 @@ pub trait OpenOptionsExt { /// use std::os::windows::fs::OpenOptionsExt; /// /// // Do not allow others to read or modify this file while we have it open - /// // for writing + /// // for writing. /// let file = OpenOptions::new().write(true) /// .share_mode(0) /// .open("foo.txt"); /// ``` + /// + /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx #[stable(feature = "open_options_ext", since = "1.10.0")] fn share_mode(&mut self, val: u32) -> &mut Self; /// Sets extra flags for the `dwFileFlags` argument to the call to - /// `CreateFile2` (or combines it with `attributes` and `security_qos_flags` - /// to set the `dwFlagsAndAttributes` for `CreateFile`). + /// [`CreateFile2`] to the specified value (or combines it with + /// `attributes` and `security_qos_flags` to set the `dwFlagsAndAttributes` + /// for [`CreateFile`]). /// - /// Custom flags can only set flags, not remove flags set by Rusts options. - /// This options overwrites any previously set custom flags. + /// Custom flags can only set flags, not remove flags set by Rust's options. + /// This option overwrites any previously set custom flags. /// /// # Examples /// - /// ```rust,ignore + /// ```ignore /// extern crate winapi; /// use std::fs::OpenOptions; /// use std::os::windows::fs::OpenOptionsExt; /// /// let mut options = OpenOptions::new(); /// options.create(true).write(true); - /// if cfg!(windows) { - /// options.custom_flags(winapi::FILE_FLAG_DELETE_ON_CLOSE); - /// } + /// options.custom_flags(winapi::FILE_FLAG_DELETE_ON_CLOSE); /// let file = options.open("foo.txt"); /// ``` + /// + /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx + /// [`CreateFile2`]: https://msdn.microsoft.com/en-us/library/windows/desktop/hh449422.aspx #[stable(feature = "open_options_ext", since = "1.10.0")] fn custom_flags(&mut self, flags: u32) -> &mut Self; - /// Sets the `dwFileAttributes` argument to the call to `CreateFile2` to + /// Sets the `dwFileAttributes` argument to the call to [`CreateFile2`] to /// the specified value (or combines it with `custom_flags` and /// `security_qos_flags` to set the `dwFlagsAndAttributes` for - /// `CreateFile`). + /// [`CreateFile`]). /// /// If a _new_ file is created because it does not yet exist and ///`.create(true)` or `.create_new(true)` are specified, the new file is @@ -155,7 +199,7 @@ pub trait OpenOptionsExt { /// /// # Examples /// - /// ```rust,ignore + /// ```ignore /// extern crate winapi; /// use std::fs::OpenOptions; /// use std::os::windows::fs::OpenOptionsExt; @@ -164,12 +208,38 @@ pub trait OpenOptionsExt { /// .attributes(winapi::FILE_ATTRIBUTE_HIDDEN) /// .open("foo.txt"); /// ``` + /// + /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx + /// [`CreateFile2`]: https://msdn.microsoft.com/en-us/library/windows/desktop/hh449422.aspx #[stable(feature = "open_options_ext", since = "1.10.0")] fn attributes(&mut self, val: u32) -> &mut Self; - /// Sets the `dwSecurityQosFlags` argument to the call to `CreateFile2` to + /// Sets the `dwSecurityQosFlags` argument to the call to [`CreateFile2`] to /// the specified value (or combines it with `custom_flags` and `attributes` - /// to set the `dwFlagsAndAttributes` for `CreateFile`). + /// to set the `dwFlagsAndAttributes` for [`CreateFile`]). + /// + /// By default, `security_qos_flags` is set to `SECURITY_ANONYMOUS`. For + /// information about possible values, see [Impersonation Levels] on the + /// Windows Dev Center site. + /// + /// # Examples + /// + /// ```ignore + /// use std::fs::OpenOptions; + /// use std::os::windows::fs::OpenOptionsExt; + /// + /// let options = OpenOptions::new(); + /// options.write(true).create(true); + /// + /// // Sets the flag value to `SecurityIdentification`. + /// options.security_qos_flags(1); + /// + /// let file = options.open("foo.txt"); + /// ``` + /// + /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx + /// [`CreateFile2`]: https://msdn.microsoft.com/en-us/library/windows/desktop/hh449422.aspx + /// [Impersonation Levels]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa379572.aspx #[stable(feature = "open_options_ext", since = "1.10.0")] fn security_qos_flags(&mut self, flags: u32) -> &mut OpenOptions; } -- cgit 1.4.1-3-g733a5 From 76128b32ccaed5576331ec10e8bdf2c5919978d5 Mon Sep 17 00:00:00 2001 From: David LeGare Date: Sat, 6 May 2017 23:05:47 -0500 Subject: Update documentation in windows::fs --- src/libstd/sys/windows/ext/fs.rs | 137 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 127 insertions(+), 10 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/sys/windows/ext/fs.rs b/src/libstd/sys/windows/ext/fs.rs index e2e405db276..d49c884cb9f 100644 --- a/src/libstd/sys/windows/ext/fs.rs +++ b/src/libstd/sys/windows/ext/fs.rs @@ -18,7 +18,9 @@ use path::Path; use sys; use sys_common::{AsInnerMut, AsInner}; -/// Windows-specific extensions to `File` +/// Windows-specific extensions to [`File`]. +/// +/// [`File`]: ../../../fs/struct.File.html #[stable(feature = "file_offset", since = "1.15.0")] pub trait FileExt { /// Seeks to a given position and reads a number of bytes. @@ -103,7 +105,9 @@ impl FileExt for fs::File { } } -/// Windows-specific extensions to `OpenOptions` +/// Windows-specific extensions to [`OpenOptions`]. +/// +/// [`OpenOptions`]: ../../../fs/struct.OpenOptions.html #[stable(feature = "open_options_ext", since = "1.10.0")] pub trait OpenOptionsExt { /// Overrides the `dwDesiredAccess` argument to the call to [`CreateFile`] @@ -267,35 +271,134 @@ impl OpenOptionsExt for OpenOptions { } } -/// Extension methods for `fs::Metadata` to access the raw fields contained +/// Extension methods for [`fs::Metadata`] to access the raw fields contained /// within. +/// +/// The data members that this trait exposes correspond to the members +/// of the [`BY_HANDLE_FILE_INFORMATION`] structure. +/// +/// [`fs::Metadata`]: ../../../fs/struct.Metadata.html +/// [`BY_HANDLE_FILE_INFORMATION`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363788.aspx #[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. + /// or directory. For possible values and their descriptions, see + /// [File Attribute Constants] in the Windows Dev Center. + /// + /// # Examples + /// + /// ```ignore + /// use std::io; + /// use std::io::prelude::*; + /// use std::fs::File; + /// use std::os::windows::prelude::*; + /// + /// # fn foo() -> io::Result<()> { + /// let mut file = File::open("foo.txt")?; + /// let attributes = file.file_attributes(); + /// # } + /// ``` + /// + /// [File Attribute Constants]: https://msdn.microsoft.com/en-us/library/windows/desktop/gg258117.aspx #[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). + /// The returned 64-bit value is equivalent to a [`FILETIME`] struct, + /// which represents the number of 100-nanosecond intervals since + /// January 1, 1601 (UTC). The struct is automatically + /// converted to a `u64` value, as that is the recommended way + /// to use it. + /// + /// If the underlying filesystem does not support creation time, the + /// returned value is 0. + /// + /// # Examples + /// + /// ```ignore + /// use std::io; + /// use std::io::prelude::*; + /// use std::fs::File; + /// use std::os::windows::prelude::*; + /// + /// # fn foo() -> io::Result<()> { + /// let mut file = File::open("foo.txt")?; + /// let creation_time = file.creation_time(); + /// # } + /// ``` + /// + /// [`FILETIME`]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms724284.aspx #[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). + /// The returned 64-bit value is equivalent to a [`FILETIME`] struct, + /// which represents the number of 100-nanosecond intervals since + /// January 1, 1601 (UTC). The struct is automatically + /// converted to a `u64` value, as that is the recommended way + /// to use it. + /// + /// For a file, the value specifies the last time that a file was read + /// from or written to. For a directory, the value specifies when + /// the directory was created. For both files and directories, the + /// specified date is correct, but the time of day is always set to + /// midnight. + /// + /// If the underlying filesystem does not support last access time, the + /// returned value is 0. + /// + /// # Examples + /// + /// ```ignore + /// use std::io; + /// use std::io::prelude::*; + /// use std::fs::File; + /// use std::os::windows::prelude::*; + /// + /// # fn foo() -> io::Result<()> { + /// let mut file = File::open("foo.txt")?; + /// let last_access_time = file.last_access_time(); + /// # } + /// ``` + /// + /// [`FILETIME`]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms724284.aspx #[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). + /// The returned 64-bit value is equivalent to a [`FILETIME`] struct, + /// which represents the number of 100-nanosecond intervals since + /// January 1, 1601 (UTC). The struct is automatically + /// converted to a `u64` value, as that is the recommended way + /// to use it. + /// + /// For a file, the value specifies the last time that a file was written + /// to. For a directory, the structure specifies when the directory was + /// created. + /// + /// If the underlying filesystem does not support the last write time + /// time, the returned value is 0. + /// + /// # Examples + /// + /// ```ignore + /// use std::io; + /// use std::io::prelude::*; + /// use std::fs::File; + /// use std::os::windows::prelude::*; + /// + /// # fn foo() -> io::Result<()> { + /// let mut file = File::open("foo.txt")?; + /// let last_write_time = file.last_write_time(); + /// # } + /// ``` + /// + /// [`FILETIME`]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms724284.aspx #[stable(feature = "metadata_ext", since = "1.1.0")] fn last_write_time(&self) -> u64; @@ -303,6 +406,20 @@ pub trait MetadataExt { /// metadata. /// /// The returned value does not have meaning for directories. + /// + /// # Examples + /// + /// ```ignore + /// use std::io; + /// use std::io::prelude::*; + /// use std::fs::File; + /// use std::os::windows::prelude::*; + /// + /// # fn foo() -> io::Result<()> { + /// let mut file = File::open("foo.txt")?; + /// let file_size = file.file_size(); + /// # } + /// ``` #[stable(feature = "metadata_ext", since = "1.1.0")] fn file_size(&self) -> u64; } -- cgit 1.4.1-3-g733a5 From c350bc17eedc776eacf194472107ec82756b204a Mon Sep 17 00:00:00 2001 From: David LeGare Date: Sun, 7 May 2017 10:35:45 -0500 Subject: Fix documentation tests in windows::fs --- src/libstd/sys/windows/ext/fs.rs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/sys/windows/ext/fs.rs b/src/libstd/sys/windows/ext/fs.rs index d49c884cb9f..c4ec75d32e4 100644 --- a/src/libstd/sys/windows/ext/fs.rs +++ b/src/libstd/sys/windows/ext/fs.rs @@ -42,7 +42,6 @@ pub trait FileExt { /// /// ``` /// use std::io; - /// use std::io::prelude::*; /// use std::fs::File; /// use std::os::windows::prelude::*; /// @@ -77,7 +76,6 @@ pub trait FileExt { /// # Examples /// /// ``` - /// use std::io::prelude::*; /// use std::fs::File; /// use std::os::windows::prelude::*; /// @@ -86,7 +84,7 @@ pub trait FileExt { /// /// // Write a byte string starting 72 bytes from /// // the start of the file. - /// buffer.write(b"some bytes", offset)?; + /// buffer.seek_write(b"some bytes", 72)?; /// # Ok(()) /// # } /// ``` -- cgit 1.4.1-3-g733a5 From 5135cc854156ae149f6ad50a3b5bc36c7519e3e6 Mon Sep 17 00:00:00 2001 From: David LeGare Date: Tue, 9 May 2017 21:20:56 -0500 Subject: Fix tidy errors --- src/libstd/sys/windows/ext/fs.rs | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/sys/windows/ext/fs.rs b/src/libstd/sys/windows/ext/fs.rs index c4ec75d32e4..8b227573f98 100644 --- a/src/libstd/sys/windows/ext/fs.rs +++ b/src/libstd/sys/windows/ext/fs.rs @@ -241,7 +241,8 @@ pub trait OpenOptionsExt { /// /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx /// [`CreateFile2`]: https://msdn.microsoft.com/en-us/library/windows/desktop/hh449422.aspx - /// [Impersonation Levels]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa379572.aspx + /// [Impersonation Levels]: + /// https://msdn.microsoft.com/en-us/library/windows/desktop/aa379572.aspx #[stable(feature = "open_options_ext", since = "1.10.0")] fn security_qos_flags(&mut self, flags: u32) -> &mut OpenOptions; } @@ -276,7 +277,8 @@ impl OpenOptionsExt for OpenOptions { /// of the [`BY_HANDLE_FILE_INFORMATION`] structure. /// /// [`fs::Metadata`]: ../../../fs/struct.Metadata.html -/// [`BY_HANDLE_FILE_INFORMATION`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363788.aspx +/// [`BY_HANDLE_FILE_INFORMATION`]: +/// https://msdn.microsoft.com/en-us/library/windows/desktop/aa363788.aspx #[stable(feature = "metadata_ext", since = "1.1.0")] pub trait MetadataExt { /// Returns the value of the `dwFileAttributes` field of this metadata. @@ -299,7 +301,8 @@ pub trait MetadataExt { /// # } /// ``` /// - /// [File Attribute Constants]: https://msdn.microsoft.com/en-us/library/windows/desktop/gg258117.aspx + /// [File Attribute Constants]: + /// https://msdn.microsoft.com/en-us/library/windows/desktop/gg258117.aspx #[stable(feature = "metadata_ext", since = "1.1.0")] fn file_attributes(&self) -> u32; -- cgit 1.4.1-3-g733a5 From 1b6a182cf1e400b63ae8692e3183beabe541ea6c Mon Sep 17 00:00:00 2001 From: Sylvestre Ledru Date: Wed, 17 May 2017 15:14:30 +0200 Subject: Improve the error management when /proc is not mounted This PR does two things: * Triggers an error on GNU/Linux & Android when /proc/self/exe doesn't exist * Handle the error properly --- src/librustc/session/filesearch.rs | 11 ++++++++--- src/libstd/sys/unix/os.rs | 7 ++++++- 2 files changed, 14 insertions(+), 4 deletions(-) (limited to 'src/libstd') diff --git a/src/librustc/session/filesearch.rs b/src/librustc/session/filesearch.rs index 82c2425aead..47b988a21b4 100644 --- a/src/librustc/session/filesearch.rs +++ b/src/librustc/session/filesearch.rs @@ -159,9 +159,14 @@ pub fn get_or_default_sysroot() -> PathBuf { }) } - match canonicalize(env::current_exe().ok()) { - Some(mut p) => { p.pop(); p.pop(); p } - None => bug!("can't determine value for sysroot") + match env::current_exe() { + Ok(exe) => { + match canonicalize(Some(exe)) { + Some(mut p) => { p.pop(); p.pop(); return p; }, + None => bug!("can't determine value for sysroot") + } + } + Err(ref e) => panic!(format!("failed to get current_exe: {}", e)) } } diff --git a/src/libstd/sys/unix/os.rs b/src/libstd/sys/unix/os.rs index 36928696c40..8e41fd009be 100644 --- a/src/libstd/sys/unix/os.rs +++ b/src/libstd/sys/unix/os.rs @@ -253,7 +253,12 @@ pub fn current_exe() -> io::Result { #[cfg(any(target_os = "linux", target_os = "android", target_os = "emscripten"))] pub fn current_exe() -> io::Result { - ::fs::read_link("/proc/self/exe") + let selfexe = PathBuf::from("/proc/self/exe"); + if selfexe.exists() { + ::fs::read_link(selfexe) + } else { + Err(io::Error::new(io::ErrorKind::Other, "no /proc/self/exe available. Is /proc mounted?")) + } } #[cfg(any(target_os = "macos", target_os = "ios"))] -- cgit 1.4.1-3-g733a5 From b9552963d1269ac6008dceda3c2cca65a2d746dc Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 17 May 2017 23:36:24 +0200 Subject: misc doc improvements for std::env --- src/libstd/env.rs | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/env.rs b/src/libstd/env.rs index 64eb52e28bc..96c10c5d10d 100644 --- a/src/libstd/env.rs +++ b/src/libstd/env.rs @@ -43,16 +43,19 @@ use sys::os as os_imp; /// use std::env; /// /// // We assume that we are in a valid directory. -/// let p = env::current_dir().unwrap(); -/// println!("The current directory is {}", p.display()); +/// let path = env::current_dir().unwrap(); +/// println!("The current directory is {}", path.display()); /// ``` #[stable(feature = "env", since = "1.0.0")] pub fn current_dir() -> io::Result { os_imp::getcwd() } -/// Changes the current working directory to the specified path, returning -/// whether the change was completed successfully or not. +/// Changes the current working directory to the specified path. +/// +/// Returns an [`Err`] if the operation fails. +/// +/// [`Err`]: ../../std/result/enum.Result.html#method.err /// /// # Examples /// @@ -65,8 +68,8 @@ pub fn current_dir() -> io::Result { /// println!("Successfully changed working directory to {}!", root.display()); /// ``` #[stable(feature = "env", since = "1.0.0")] -pub fn set_current_dir>(p: P) -> io::Result<()> { - os_imp::chdir(p.as_ref()) +pub fn set_current_dir>(path: P) -> io::Result<()> { + os_imp::chdir(path.as_ref()) } /// An iterator over a snapshot of the environment variables of this process. @@ -175,10 +178,10 @@ impl fmt::Debug for VarsOs { /// /// The returned result is [`Ok(s)`] if the environment variable is present and is /// valid unicode. If the environment variable is not present, or it is not -/// valid unicode, then [`Err`] will be returned. +/// valid unicode, then [`VarError`] will be returned. /// /// [`Ok(s)`]: ../result/enum.Result.html#variant.Ok -/// [`Err`]: ../result/enum.Result.html#variant.Err +/// [`VarError`]: enum.VarError.html /// /// # Examples /// @@ -199,7 +202,7 @@ pub fn var>(key: K) -> Result { fn _var(key: &OsStr) -> Result { match var_os(key) { Some(s) => s.into_string().map_err(VarError::NotUnicode), - None => Err(VarError::NotPresent) + None => Err(VarError::NotPresent), } } -- cgit 1.4.1-3-g733a5 From f4e33a011ecbd4744c0a2c594ad69fd1a52bd9c5 Mon Sep 17 00:00:00 2001 From: Denis Andrejew Date: Thu, 18 May 2017 08:45:18 +0200 Subject: fix typo in libstd/sync/mpsc/mod.rs docs --- src/libstd/sync/mpsc/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs index 2cb649ce67b..284a5fbd9d5 100644 --- a/src/libstd/sync/mpsc/mod.rs +++ b/src/libstd/sync/mpsc/mod.rs @@ -1067,7 +1067,7 @@ impl Receiver { Receiver { inner: UnsafeCell::new(inner) } } - /// Attempts to return a pending value on this receiver without blocking + /// Attempts to return a pending value on this receiver without blocking. /// /// This method will never block the caller in order to wait for data to /// become available. Instead, this will always return immediately with a -- cgit 1.4.1-3-g733a5 From b2fc7b1cbeae1e6cb1a5b4797d221733592ae6a4 Mon Sep 17 00:00:00 2001 From: Michael Kohl Date: Thu, 11 May 2017 22:49:16 +0700 Subject: Add documentation for `ExitStatus` As requested in #29370. --- src/libstd/process.rs | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 3896fc20a2d..d0e7defbbbb 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -754,6 +754,13 @@ impl fmt::Debug for Stdio { } /// Describes the result of a process after it has terminated. +/// +/// This `struct` is used to represent the exit status of a child process. +/// Child processes are created via the [`Command`] struct and their exit +/// status is exposed through the [`status`] method. +/// +/// [`Command`]: struct.Command.html +/// [`status`]: struct.Command.html#method.status #[derive(PartialEq, Eq, Clone, Copy, Debug)] #[stable(feature = "process", since = "1.0.0")] pub struct ExitStatus(imp::ExitStatus); @@ -788,6 +795,22 @@ impl ExitStatus { /// On Unix, this will return `None` if the process was terminated /// by a signal; `std::os::unix` provides an extension trait for /// extracting the signal and other details from the `ExitStatus`. + /// + /// # Examples + /// + /// ```no_run + /// use std::process::Command; + /// + /// let status = Command::new("mkdir") + /// .arg("projects") + /// .status() + /// .expect("failed to execute mkdir"); + /// + /// match status.code() { + /// Some(code) => println!("Exited with status code: {}", code), + /// None => println!("Process terminated by signal") + /// } + /// ``` #[stable(feature = "process", since = "1.0.0")] pub fn code(&self) -> Option { self.0.code() -- cgit 1.4.1-3-g733a5 From 4cd838b274db73be8c974e5335b28f1b6f6b75a0 Mon Sep 17 00:00:00 2001 From: David LeGare Date: Thu, 18 May 2017 21:10:15 -0500 Subject: Normalize docs in windows::ffi and windows::fs - Remove `()` parens when referencing functions in docs. - Change some examples to be no_run instead of ignore. - Normalize style in examples for `OpenOptionsExt`. - Fix typo in windows mod docs. --- src/libstd/sys/windows/ext/ffi.rs | 10 ++-- src/libstd/sys/windows/ext/fs.rs | 109 ++++++++++++++++++++------------------ src/libstd/sys/windows/ext/mod.rs | 2 +- 3 files changed, 64 insertions(+), 57 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/sys/windows/ext/ffi.rs b/src/libstd/sys/windows/ext/ffi.rs index cb13595fcd6..3f6c2827a3f 100644 --- a/src/libstd/sys/windows/ext/ffi.rs +++ b/src/libstd/sys/windows/ext/ffi.rs @@ -26,7 +26,7 @@ pub trait OsStringExt { /// Creates an `OsString` from a potentially ill-formed UTF-16 slice of /// 16-bit code units. /// - /// This is lossless: calling [`encode_wide()`] on the resulting string + /// This is lossless: calling [`encode_wide`] on the resulting string /// will always return the original code units. /// /// # Examples @@ -41,7 +41,7 @@ pub trait OsStringExt { /// let string = OsString::from_wide(&source[..]); /// ``` /// - /// [`encode_wide()`]: ./trait.OsStrExt.html#tymethod.encode_wide + /// [`encode_wide`]: ./trait.OsStrExt.html#tymethod.encode_wide #[stable(feature = "rust1", since = "1.0.0")] fn from_wide(wide: &[u16]) -> Self; } @@ -59,8 +59,8 @@ pub trait OsStrExt { /// Re-encodes an `OsStr` as a wide character sequence, i.e. potentially /// ill-formed UTF-16. /// - /// This is lossless: calling [`OsString::from_wide()`] and then - /// `encode_wide()` on the result will yield the original code units. + /// This is lossless: calling [`OsString::from_wide`] and then + /// `encode_wide` on the result will yield the original code units. /// Note that the encoding does not add a final null terminator. /// /// # Examples @@ -78,7 +78,7 @@ pub trait OsStrExt { /// assert_eq!(&source[..], &result[..]); /// ``` /// - /// [`OsString::from_wide()`]: ./trait.OsStringExt.html#tymethod.from_wide + /// [`OsString::from_wide`]: ./trait.OsStringExt.html#tymethod.from_wide #[stable(feature = "rust1", since = "1.0.0")] fn encode_wide(&self) -> EncodeWide; } diff --git a/src/libstd/sys/windows/ext/fs.rs b/src/libstd/sys/windows/ext/fs.rs index 8b227573f98..34f3a0196ce 100644 --- a/src/libstd/sys/windows/ext/fs.rs +++ b/src/libstd/sys/windows/ext/fs.rs @@ -40,7 +40,7 @@ pub trait FileExt { /// /// # Examples /// - /// ``` + /// ```no_run /// use std::io; /// use std::fs::File; /// use std::os::windows::prelude::*; @@ -75,7 +75,7 @@ pub trait FileExt { /// /// # Examples /// - /// ``` + /// ```no_run /// use std::fs::File; /// use std::os::windows::prelude::*; /// @@ -120,10 +120,10 @@ pub trait OpenOptionsExt { /// /// ```no_run /// use std::fs::OpenOptions; - /// use std::os::windows::fs::OpenOptionsExt; + /// use std::os::windows::prelude::*; /// /// // Open without read and write permission, for example if you only need - /// // to call `stat()` on the file + /// // to call `stat` on the file /// let file = OpenOptions::new().access_mode(0).open("foo.txt"); /// ``` /// @@ -145,13 +145,14 @@ pub trait OpenOptionsExt { /// /// ```no_run /// use std::fs::OpenOptions; - /// use std::os::windows::fs::OpenOptionsExt; + /// use std::os::windows::prelude::*; /// /// // Do not allow others to read or modify this file while we have it open /// // for writing. - /// let file = OpenOptions::new().write(true) - /// .share_mode(0) - /// .open("foo.txt"); + /// let file = OpenOptions::new() + /// .write(true) + /// .share_mode(0) + /// .open("foo.txt"); /// ``` /// /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx @@ -170,13 +171,15 @@ pub trait OpenOptionsExt { /// /// ```ignore /// extern crate winapi; + /// /// use std::fs::OpenOptions; - /// use std::os::windows::fs::OpenOptionsExt; + /// use std::os::windows::prelude::*; /// - /// let mut options = OpenOptions::new(); - /// options.create(true).write(true); - /// options.custom_flags(winapi::FILE_FLAG_DELETE_ON_CLOSE); - /// let file = options.open("foo.txt"); + /// let file = OpenOptions::new() + /// .create(true) + /// .write(true) + /// .custom_flags(winapi::FILE_FLAG_DELETE_ON_CLOSE) + /// .open("foo.txt"); /// ``` /// /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx @@ -203,12 +206,15 @@ pub trait OpenOptionsExt { /// /// ```ignore /// extern crate winapi; + /// /// use std::fs::OpenOptions; - /// use std::os::windows::fs::OpenOptionsExt; + /// use std::os::windows::prelude::*; /// - /// let file = OpenOptions::new().write(true).create(true) - /// .attributes(winapi::FILE_ATTRIBUTE_HIDDEN) - /// .open("foo.txt"); + /// let file = OpenOptions::new() + /// .write(true) + /// .create(true) + /// .attributes(winapi::FILE_ATTRIBUTE_HIDDEN) + /// .open("foo.txt"); /// ``` /// /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx @@ -226,17 +232,18 @@ pub trait OpenOptionsExt { /// /// # Examples /// - /// ```ignore + /// ```no_run /// use std::fs::OpenOptions; - /// use std::os::windows::fs::OpenOptionsExt; + /// use std::os::windows::prelude::*; /// - /// let options = OpenOptions::new(); - /// options.write(true).create(true); + /// let file = OpenOptions::new() + /// .write(true) + /// .create(true) /// - /// // Sets the flag value to `SecurityIdentification`. - /// options.security_qos_flags(1); + /// // Sets the flag value to `SecurityIdentification`. + /// options.security_qos_flags(1) /// - /// let file = options.open("foo.txt"); + /// .open("foo.txt"); /// ``` /// /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx @@ -289,15 +296,15 @@ pub trait MetadataExt { /// /// # Examples /// - /// ```ignore + /// ```no_run /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; + /// use std::fs; /// use std::os::windows::prelude::*; /// /// # fn foo() -> io::Result<()> { - /// let mut file = File::open("foo.txt")?; - /// let attributes = file.file_attributes(); + /// let metadata = fs::metadata("foo.txt")?; + /// let attributes = metadata.file_attributes(); + /// # Ok(()) /// # } /// ``` /// @@ -319,15 +326,15 @@ pub trait MetadataExt { /// /// # Examples /// - /// ```ignore + /// ```no_run /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; + /// use std::fs; /// use std::os::windows::prelude::*; /// /// # fn foo() -> io::Result<()> { - /// let mut file = File::open("foo.txt")?; - /// let creation_time = file.creation_time(); + /// let metadata = fs::metadata("foo.txt")?; + /// let creation_time = metadata.creation_time(); + /// # Ok(()) /// # } /// ``` /// @@ -354,15 +361,15 @@ pub trait MetadataExt { /// /// # Examples /// - /// ```ignore + /// ```no_run /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; + /// use std::fs; /// use std::os::windows::prelude::*; /// /// # fn foo() -> io::Result<()> { - /// let mut file = File::open("foo.txt")?; - /// let last_access_time = file.last_access_time(); + /// let metadata = fs::metadata("foo.txt")?; + /// let last_access_time = metadata.last_access_time(); + /// # Ok(()) /// # } /// ``` /// @@ -387,15 +394,15 @@ pub trait MetadataExt { /// /// # Examples /// - /// ```ignore + /// ```no_run /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; + /// use std::fs; /// use std::os::windows::prelude::*; /// /// # fn foo() -> io::Result<()> { - /// let mut file = File::open("foo.txt")?; - /// let last_write_time = file.last_write_time(); + /// let metadata = fs::metadata("foo.txt")?; + /// let last_write_time = metadata.last_write_time(); + /// # Ok(()) /// # } /// ``` /// @@ -410,15 +417,15 @@ pub trait MetadataExt { /// /// # Examples /// - /// ```ignore + /// ```no_run /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; + /// use std::fs; /// use std::os::windows::prelude::*; /// /// # fn foo() -> io::Result<()> { - /// let mut file = File::open("foo.txt")?; - /// let file_size = file.file_size(); + /// let metadata = fs::metadata("foo.txt")?; + /// let file_size = metadata.file_size(); + /// # Ok(()) /// # } /// ``` #[stable(feature = "metadata_ext", since = "1.1.0")] @@ -441,7 +448,7 @@ impl MetadataExt for Metadata { /// /// # Examples /// -/// ```ignore +/// ```no_run /// use std::os::windows::fs; /// /// # fn foo() -> std::io::Result<()> { @@ -462,7 +469,7 @@ pub fn symlink_file, Q: AsRef>(src: P, dst: Q) /// /// # Examples /// -/// ```ignore +/// ```no_run /// use std::os::windows::fs; /// /// # fn foo() -> std::io::Result<()> { diff --git a/src/libstd/sys/windows/ext/mod.rs b/src/libstd/sys/windows/ext/mod.rs index e07acad5e46..11b1337a8ae 100644 --- a/src/libstd/sys/windows/ext/mod.rs +++ b/src/libstd/sys/windows/ext/mod.rs @@ -13,7 +13,7 @@ //! Provides access to platform-level information for Windows, and exposes //! Windows-specific idioms that would otherwise be inappropriate as part //! the core `std` library. These extensions allow developers to use -//! `std` types and idioms with Windows in a way that the noraml +//! `std` types and idioms with Windows in a way that the normal //! platform-agnostic idioms would not normally support. #![stable(feature = "rust1", since = "1.0.0")] -- cgit 1.4.1-3-g733a5 From a89292514b6d4c4e9be7d6d527ad72e08e27173c Mon Sep 17 00:00:00 2001 From: David LeGare Date: Fri, 19 May 2017 07:29:52 -0500 Subject: Fix doc test failure for OpenOptionsExt --- src/libstd/sys/windows/ext/fs.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/sys/windows/ext/fs.rs b/src/libstd/sys/windows/ext/fs.rs index 34f3a0196ce..2d00cb38ec4 100644 --- a/src/libstd/sys/windows/ext/fs.rs +++ b/src/libstd/sys/windows/ext/fs.rs @@ -241,7 +241,7 @@ pub trait OpenOptionsExt { /// .create(true) /// /// // Sets the flag value to `SecurityIdentification`. - /// options.security_qos_flags(1) + /// .security_qos_flags(1) /// /// .open("foo.txt"); /// ``` -- cgit 1.4.1-3-g733a5