From 980e1ff40f51b6b4b86ee70809d0a0055e6f9cc6 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 24 Sep 2020 14:49:59 +0200 Subject: [PATCH 1/2] Add missing examples for Fd traits --- library/std/src/sys/unix/ext/io.rs | 43 ++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/library/std/src/sys/unix/ext/io.rs b/library/std/src/sys/unix/ext/io.rs index ec7a32b675c..ef780fa8cca 100644 --- a/library/std/src/sys/unix/ext/io.rs +++ b/library/std/src/sys/unix/ext/io.rs @@ -25,6 +25,20 @@ pub trait AsRawFd { /// This method does **not** pass ownership of the raw file descriptor /// to the caller. The descriptor is only guaranteed to be valid while /// the original object has not yet been destroyed. + /// + /// # Example + /// + /// ```no_run + /// use std::fs::File; + /// use std::os::unix::io::{AsRawFd, RawFd}; + /// + /// fn main() -> std::io::Result<()> { + /// let mut f = File::open("foo.txt")?; + /// // Note that `raw_fd` is only valid as long as `f` exists. + /// let raw_fd: RawFd = f.as_raw_fd(); + /// Ok(()) + /// } + /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn as_raw_fd(&self) -> RawFd; } @@ -45,6 +59,22 @@ pub trait FromRawFd { /// descriptor they are wrapping. Usage of this function could /// accidentally allow violating this contract which can cause memory /// unsafety in code that relies on it being true. + /// + /// # Example + /// + /// ```no_run + /// use std::fs::File; + /// use std::os::unix::io::{FromRawFd, IntoRawFd, RawFd}; + /// + /// fn main() -> std::io::Result<()> { + /// let f = File::open("foo.txt")?; + /// let raw_fd: RawFd = f.into_raw_fd(); + /// // SAFETY: no other functions should call `from_raw_fd`, so there + /// // is only one owner for the file descriptor. + /// let f = unsafe { File::from_raw_fd(raw_fd) }; + /// Ok(()) + /// } + /// ``` #[stable(feature = "from_raw_os", since = "1.1.0")] unsafe fn from_raw_fd(fd: RawFd) -> Self; } @@ -58,6 +88,19 @@ pub trait IntoRawFd { /// This function **transfers ownership** of the underlying file descriptor /// to the caller. Callers are then the unique owners of the file descriptor /// and must close the descriptor once it's no longer needed. + /// + /// # Example + /// + /// ```no_run + /// use std::fs::File; + /// use std::os::unix::io::{IntoRawFd, RawFd}; + /// + /// fn main() -> std::io::Result<()> { + /// let f = File::open("foo.txt")?; + /// let raw_fd: RawFd = f.into_raw_fd(); + /// Ok(()) + /// } + /// ``` #[stable(feature = "into_raw_os", since = "1.4.0")] fn into_raw_fd(self) -> RawFd; } From d6b838b93a7e0acd51e0cc9bbb3415a517b7b3cd Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Fri, 2 Oct 2020 16:38:15 +0200 Subject: [PATCH 2/2] Simplify fd examples --- library/std/src/sys/unix/ext/io.rs | 35 ++++++++++++++---------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/library/std/src/sys/unix/ext/io.rs b/library/std/src/sys/unix/ext/io.rs index ef780fa8cca..d929c8bbd68 100644 --- a/library/std/src/sys/unix/ext/io.rs +++ b/library/std/src/sys/unix/ext/io.rs @@ -30,14 +30,13 @@ pub trait AsRawFd { /// /// ```no_run /// use std::fs::File; + /// # use std::io; /// use std::os::unix::io::{AsRawFd, RawFd}; /// - /// fn main() -> std::io::Result<()> { - /// let mut f = File::open("foo.txt")?; - /// // Note that `raw_fd` is only valid as long as `f` exists. - /// let raw_fd: RawFd = f.as_raw_fd(); - /// Ok(()) - /// } + /// let mut f = File::open("foo.txt")?; + /// // Note that `raw_fd` is only valid as long as `f` exists. + /// let raw_fd: RawFd = f.as_raw_fd(); + /// # Ok::<(), io::Error>(()) /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn as_raw_fd(&self) -> RawFd; @@ -64,16 +63,15 @@ pub trait FromRawFd { /// /// ```no_run /// use std::fs::File; + /// # use std::io; /// use std::os::unix::io::{FromRawFd, IntoRawFd, RawFd}; /// - /// fn main() -> std::io::Result<()> { - /// let f = File::open("foo.txt")?; - /// let raw_fd: RawFd = f.into_raw_fd(); - /// // SAFETY: no other functions should call `from_raw_fd`, so there - /// // is only one owner for the file descriptor. - /// let f = unsafe { File::from_raw_fd(raw_fd) }; - /// Ok(()) - /// } + /// let f = File::open("foo.txt")?; + /// let raw_fd: RawFd = f.into_raw_fd(); + /// // SAFETY: no other functions should call `from_raw_fd`, so there + /// // is only one owner for the file descriptor. + /// let f = unsafe { File::from_raw_fd(raw_fd) }; + /// # Ok::<(), io::Error>(()) /// ``` #[stable(feature = "from_raw_os", since = "1.1.0")] unsafe fn from_raw_fd(fd: RawFd) -> Self; @@ -93,13 +91,12 @@ pub trait IntoRawFd { /// /// ```no_run /// use std::fs::File; + /// # use std::io; /// use std::os::unix::io::{IntoRawFd, RawFd}; /// - /// fn main() -> std::io::Result<()> { - /// let f = File::open("foo.txt")?; - /// let raw_fd: RawFd = f.into_raw_fd(); - /// Ok(()) - /// } + /// let f = File::open("foo.txt")?; + /// let raw_fd: RawFd = f.into_raw_fd(); + /// # Ok::<(), io::Error>(()) /// ``` #[stable(feature = "into_raw_os", since = "1.4.0")] fn into_raw_fd(self) -> RawFd;