From 6df44a389cfab95807027a420903ee0b8cc08f0e Mon Sep 17 00:00:00 2001
From: Chris Denton <christophersdenton@gmail.com>
Date: Thu, 2 Dec 2021 17:51:44 +0000
Subject: [PATCH] Document how `last_os_error` should be used

---
 library/std/src/io/error.rs | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/library/std/src/io/error.rs b/library/std/src/io/error.rs
index d93c6172cfcf6..da88c8c9261b4 100644
--- a/library/std/src/io/error.rs
+++ b/library/std/src/io/error.rs
@@ -440,12 +440,18 @@ impl Error {
     /// `GetLastError` on Windows) and will return a corresponding instance of
     /// [`Error`] for the error code.
     ///
+    /// This should be called immediately after a call to a platform function,
+    /// otherwise the state of the error value is indeterminate. In particular,
+    /// other standard library functions may call platform functions that may
+    /// (or may not) reset the error value even if they succeed.
+    ///
     /// # Examples
     ///
     /// ```
     /// use std::io::Error;
     ///
-    /// println!("last OS error: {:?}", Error::last_os_error());
+    /// let os_error = Error::last_os_error();
+    /// println!("last OS error: {:?}", os_error);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[must_use]