From f48a5dcf8f2427d15b8e8df51b610dbc3448816e Mon Sep 17 00:00:00 2001 From: Chris Gregory Date: Wed, 27 Mar 2019 16:37:50 -0400 Subject: [PATCH 1/4] Document std::fs::File close behavior ignoring errors --- src/libstd/fs.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index dfff44b88ea78..06d8ee99b64d1 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -21,7 +21,10 @@ use crate::time::SystemTime; /// it was opened with. Files also implement [`Seek`] to alter the logical cursor /// that the file contains internally. /// -/// Files are automatically closed when they go out of scope. +/// Files are automatically closed when they go out of scope. All errors are +/// ignored due to complications with correctly handling them. For instance, an +/// error in closing a file could mean that closing failed, or that the file had +/// an error before closing that was only unearthed by closing the file. /// /// # Examples /// From b6ebe1bd9e4f6692c390326bca0ef06c24255719 Mon Sep 17 00:00:00 2001 From: Chris Gregory Date: Mon, 1 Apr 2019 22:34:57 -0400 Subject: [PATCH 2/4] Document using `sync_all` --- src/libstd/fs.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 06d8ee99b64d1..99dd0d8eeeb0e 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -21,10 +21,9 @@ use crate::time::SystemTime; /// it was opened with. Files also implement [`Seek`] to alter the logical cursor /// that the file contains internally. /// -/// Files are automatically closed when they go out of scope. All errors are -/// ignored due to complications with correctly handling them. For instance, an -/// error in closing a file could mean that closing failed, or that the file had -/// an error before closing that was only unearthed by closing the file. +/// Files are automatically closed when they go out of scope. Errors detected +/// on closing are ignored by the implementation of `Drop`. Use the method +/// `sync_all` if these errors must be manually handled. /// /// # Examples /// From 76e82d6f52431b4877bbdc6413480680d9956967 Mon Sep 17 00:00:00 2001 From: Chris Gregory Date: Tue, 2 Apr 2019 22:26:11 -0400 Subject: [PATCH 3/4] Link to sync_all --- src/libstd/fs.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 99dd0d8eeeb0e..034564250c3a5 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -23,7 +23,7 @@ use crate::time::SystemTime; /// /// Files are automatically closed when they go out of scope. Errors detected /// on closing are ignored by the implementation of `Drop`. Use the method -/// `sync_all` if these errors must be manually handled. +/// [`sync_all`] if these errors must be manually handled. /// /// # Examples /// @@ -86,6 +86,7 @@ use crate::time::SystemTime; /// [`Read`]: ../io/trait.Read.html /// [`Write`]: ../io/trait.Write.html /// [`BufReader`]: ../io/struct.BufReader.html +/// [`sync_all`]: struct.File.html#method.sync_all #[stable(feature = "rust1", since = "1.0.0")] pub struct File { inner: fs_imp::File, From a969d409874f91e197a1cd336a368f02d8a3ce47 Mon Sep 17 00:00:00 2001 From: Chris Gregory Date: Wed, 3 Apr 2019 23:21:10 -0400 Subject: [PATCH 4/4] File: Add documentation about dropping to sync_all --- src/libstd/fs.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 034564250c3a5..c0d4dfc892794 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -394,9 +394,13 @@ impl File { /// Attempts to sync all OS-internal metadata to disk. /// - /// This function will attempt to ensure that all in-core data reaches the + /// This function will attempt to ensure that all in-memory data reaches the /// filesystem before returning. /// + /// This can be used to handle errors that would otherwise only be caught + /// when the `File` is closed. Dropping a file will ignore errors in + /// synchronizing this in-memory data. + /// /// # Examples /// /// ```no_run