add note about `AlreadyExists` to `create_new`

1 files changed, 5 insertions, 0 deletions

diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs
index 409ead0e284..911bc8cabe2 100644
--- a/library/std/src/fs.rs
+++ b/library/std/src/fs.rs
@@ -408,6 +408,7 @@ impl File {
     ///
     /// This function will create a file if it does not exist, or return an error if it does. This
     /// way, if the call succeeds, the file returned is guaranteed to be new.
+    /// If a file exists at the target location before, creating file will fail with [`AlreadyExists`].
     ///
     /// This option is useful because it is atomic. Otherwise between checking whether a file
     /// exists and creating a new one, the file may have been created by another process (a TOCTOU
@@ -416,6 +417,8 @@ impl File {
     /// This can also be written using
     /// `File::options().read(true).write(true).create_new(true).open(...)`.
     ///
+    /// [`AlreadyExists`]: crate::io::ErrorKind::AlreadyExists
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -1071,6 +1074,7 @@ impl OpenOptions {
     ///
     /// No file is allowed to exist at the target location, also no (dangling) symlink. In this
     /// way, if the call succeeds, the file returned is guaranteed to be new.
+    /// If a file exists at the target location before, creating file will fail with [`AlreadyExists`].
     ///
     /// This option is useful because it is atomic. Otherwise between checking
     /// whether a file exists and creating a new one, the file may have been
@@ -1084,6 +1088,7 @@ impl OpenOptions {
     ///
     /// [`.create()`]: OpenOptions::create
     /// [`.truncate()`]: OpenOptions::truncate
+    /// [`AlreadyExists`]: io::ErrorKind::AlreadyExists
     ///
     /// # Examples
     ///