Rollup merge of #124782 - anatawa12:docs-create-new-already-exists, r=workingjubilee

add note about `AlreadyExists` to `create_new`

Fixes #119244

library/std/src/fs.rs

@@ -408,6 +408,9 @@ pub fn create<P: AsRef<Path>>(path: P) -> io::Result<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, creating a new file will fail with [`AlreadyExists`]
+    /// or another error based on the situation. See [`OpenOptions::open`] for a
+    /// non-exhaustive list of likely errors.
     ///
     /// 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 +419,8 @@ pub fn create<P: AsRef<Path>>(path: P) -> io::Result<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 +1076,9 @@ pub fn create(&mut self, create: bool) -> &mut Self {
     ///
     /// 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, creating a new file will fail with [`AlreadyExists`]
+    /// or another error based on the situation. See [`OpenOptions::open`] for a
+    /// non-exhaustive list of likely errors.
     ///
     /// 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 +1092,7 @@ pub fn create(&mut self, create: bool) -> &mut Self {
     ///
     /// [`.create()`]: OpenOptions::create
     /// [`.truncate()`]: OpenOptions::truncate
+    /// [`AlreadyExists`]: io::ErrorKind::AlreadyExists
     ///
     /// # Examples
     ///