Rollup merge of #91460 - ChrisDenton:doc-last-os-error, r=joshtriplett

Document how `last_os_error` should be used

It should be made clear that the state of the last OS error could change if another function call is made before the call to `Error::last_os_error()`.

Fixes: #53155

1 files changed, 7 insertions, 1 deletions

diff --git a/library/std/src/io/error.rs b/library/std/src/io/error.rs
index d93c6172cfc..da88c8c9261 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]