From 980e1ff40f51b6b4b86ee70809d0a0055e6f9cc6 Mon Sep 17 00:00:00 2001
From: Guillaume Gomez <guillaume1.gomez@gmail.com>
Date: Thu, 24 Sep 2020 14:49:59 +0200
Subject: [PATCH] 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 ec7a32b675c02..ef780fa8cca29 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;
 }