Rollup merge of #99307 - JohnTitor:issue-64401, r=compiler-errors

[rust.git] / library / std / src / fs.rs

diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs
index 55bd2c59406df9a3ac8db1fd5bedfe029f933162..d799776548a65b9d3e069c687d8ab143857d7a7c 100644 (file)
--- a/library/std/src/fs.rs
+++ b/library/std/src/fs.rs
@@ -295,6 +295,9 @@ fn inner(path: &Path) -> io::Result<String> {
 /// This function will create a file if it does not exist,
 /// and will entirely replace its contents if it does.
 ///
+/// Depending on the platform, this function may fail if the
+/// full directory path does not exist.
+///
 /// This is a convenience function for using [`File::create`] and [`write_all`]
 /// with fewer imports.
 ///
@@ -349,6 +352,9 @@ pub fn open<P: AsRef<Path>>(path: P) -> io::Result<File> {
     /// This function will create a file if it does not exist,
     /// and will truncate it if it does.
     ///
+    /// Depending on the platform, this function may fail if the
+    /// full directory path does not exist.
+    ///
     /// See the [`OpenOptions::open`] function for more details.
     ///
     /// # Examples
@@ -2317,10 +2323,14 @@ fn as_inner_mut(&mut self) -> &mut fs_imp::DirBuilder {
 /// unrelated to the path not existing. (E.g. it will return `Err(_)` in case of permission
 /// denied on some of the parent directories.)
 ///
+/// Note that while this avoids some pitfalls of the `exists()` method, it still can not
+/// prevent time-of-check to time-of-use (TOCTOU) bugs. You should only use it in scenarios
+/// where those bugs are not an issue.
+///
 /// # Examples
 ///
 /// ```no_run
-/// #![feature(path_try_exists)]
+/// #![feature(fs_try_exists)]
 /// use std::fs;
 ///
 /// assert!(!fs::try_exists("does_not_exist.txt").expect("Can't check existence of file does_not_exist.txt"));
@@ -2330,7 +2340,7 @@ fn as_inner_mut(&mut self) -> &mut fs_imp::DirBuilder {
 /// [`Path::exists`]: crate::path::Path::exists
 // FIXME: stabilization should modify documentation of `exists()` to recommend this method
 // instead.
-#[unstable(feature = "path_try_exists", issue = "83186")]
+#[unstable(feature = "fs_try_exists", issue = "83186")]
 #[inline]
 pub fn try_exists<P: AsRef<Path>>(path: P) -> io::Result<bool> {
     fs_imp::try_exists(path.as_ref())