diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs index a59faf551e8..77e94365b08 100644 --- a/library/std/src/fs.rs +++ b/library/std/src/fs.rs @@ -408,6 +408,9 @@ pub fn create>(path: P) -> io::Result { /// /// 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>(path: P) -> io::Result { /// 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 ///