Add a File::create_new constructor

We have `File::create` for creating a file or opening an existing file,
but the secure way to guarantee creating a new file requires a longhand
invocation via `OpenOptions`.

Add `File::create_new` to handle this case, to make it easier for people
to do secure file creation.
This commit is contained in:
Josh Triplett 2022-07-01 23:30:47 -07:00
parent 9a6fa4f118
commit e540425a24

View File

@ -366,6 +366,35 @@ impl File {
OpenOptions::new().write(true).create(true).truncate(true).open(path.as_ref())
}
/// Creates a new file in read-write mode; error if the file exists.
///
/// 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.
///
/// 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
/// race condition / attack).
///
/// This can also be written using
/// `File::options().read(true).write(true).create_new(true).open(...)`.
///
/// # Examples
///
/// ```no_run
/// #![feature(file_create_new)]
///
/// use std::fs::File;
///
/// fn main() -> std::io::Result<()> {
/// let mut f = File::create_new("foo.txt")?;
/// Ok(())
/// }
/// ```
#[unstable(feature = "file_create_new", issue = "none")]
pub fn create_new<P: AsRef<Path>>(path: P) -> io::Result<File> {
OpenOptions::new().read(true).write(true).create_new(true).open(path.as_ref())
}
/// Returns a new OpenOptions object.
///
/// This function returns a new OpenOptions object that you can use to