416 lines
13 KiB
Rust
416 lines
13 KiB
Rust
// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
|
|
// file at the top-level directory of this distribution and at
|
|
// http://rust-lang.org/COPYRIGHT.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
|
|
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
|
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
|
// option. This file may not be copied, modified, or distributed
|
|
// except according to those terms.
|
|
|
|
use remove_dir_all::remove_dir_all;
|
|
use std::mem;
|
|
use std::path::{self, Path, PathBuf};
|
|
use std::{fmt, fs, io};
|
|
|
|
use crate::error::IoResultExt;
|
|
use crate::Builder;
|
|
|
|
/// Create a new temporary directory.
|
|
///
|
|
/// The `tempdir` function creates a directory in the file system
|
|
/// and returns a [`TempDir`].
|
|
/// The directory will be automatically deleted when the `TempDir`s
|
|
/// destructor is run.
|
|
///
|
|
/// # Resource Leaking
|
|
///
|
|
/// See [the resource leaking][resource-leaking] docs on `TempDir`.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// If the directory can not be created, `Err` is returned.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use tempfile::tempdir;
|
|
/// use std::fs::File;
|
|
/// use std::io::{self, Write};
|
|
///
|
|
/// # fn main() {
|
|
/// # if let Err(_) = run() {
|
|
/// # ::std::process::exit(1);
|
|
/// # }
|
|
/// # }
|
|
/// # fn run() -> Result<(), io::Error> {
|
|
/// // Create a directory inside of `std::env::temp_dir()`
|
|
/// let dir = tempdir()?;
|
|
///
|
|
/// let file_path = dir.path().join("my-temporary-note.txt");
|
|
/// let mut file = File::create(file_path)?;
|
|
/// writeln!(file, "Brian was here. Briefly.")?;
|
|
///
|
|
/// // `tmp_dir` goes out of scope, the directory as well as
|
|
/// // `tmp_file` will be deleted here.
|
|
/// drop(file);
|
|
/// dir.close()?;
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
///
|
|
/// [`TempDir`]: struct.TempDir.html
|
|
/// [resource-leaking]: struct.TempDir.html#resource-leaking
|
|
pub fn tempdir() -> io::Result<TempDir> {
|
|
TempDir::new()
|
|
}
|
|
|
|
/// Create a new temporary directory.
|
|
///
|
|
/// The `tempdir` function creates a directory in the file system
|
|
/// and returns a [`TempDir`].
|
|
/// The directory will be automatically deleted when the `TempDir`s
|
|
/// destructor is run.
|
|
///
|
|
/// # Resource Leaking
|
|
///
|
|
/// See [the resource leaking][resource-leaking] docs on `TempDir`.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// If the directory can not be created, `Err` is returned.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use tempfile::tempdir;
|
|
/// use std::fs::File;
|
|
/// use std::io::{self, Write};
|
|
///
|
|
/// # fn main() {
|
|
/// # if let Err(_) = run() {
|
|
/// # ::std::process::exit(1);
|
|
/// # }
|
|
/// # }
|
|
/// # fn run() -> Result<(), io::Error> {
|
|
/// // Create a directory inside of `std::env::temp_dir()`,
|
|
/// let dir = tempdir()?;
|
|
///
|
|
/// let file_path = dir.path().join("my-temporary-note.txt");
|
|
/// let mut file = File::create(file_path)?;
|
|
/// writeln!(file, "Brian was here. Briefly.")?;
|
|
///
|
|
/// // `tmp_dir` goes out of scope, the directory as well as
|
|
/// // `tmp_file` will be deleted here.
|
|
/// drop(file);
|
|
/// dir.close()?;
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
///
|
|
/// [`TempDir`]: struct.TempDir.html
|
|
/// [resource-leaking]: struct.TempDir.html#resource-leaking
|
|
pub fn tempdir_in<P: AsRef<Path>>(dir: P) -> io::Result<TempDir> {
|
|
TempDir::new_in(dir)
|
|
}
|
|
|
|
/// A directory in the filesystem that is automatically deleted when
|
|
/// it goes out of scope.
|
|
///
|
|
/// The [`TempDir`] type creates a directory on the file system that
|
|
/// is deleted once it goes out of scope. At construction, the
|
|
/// `TempDir` creates a new directory with a randomly generated name.
|
|
///
|
|
/// The default constructor, [`TempDir::new()`], creates directories in
|
|
/// the location returned by [`std::env::temp_dir()`], but `TempDir`
|
|
/// can be configured to manage a temporary directory in any location
|
|
/// by constructing with a [`Builder`].
|
|
///
|
|
/// After creating a `TempDir`, work with the file system by doing
|
|
/// standard [`std::fs`] file system operations on its [`Path`],
|
|
/// which can be retrieved with [`TempDir::path()`]. Once the `TempDir`
|
|
/// value is dropped, the directory at the path will be deleted, along
|
|
/// with any files and directories it contains. It is your responsibility
|
|
/// to ensure that no further file system operations are attempted
|
|
/// inside the temporary directory once it has been deleted.
|
|
///
|
|
/// # Resource Leaking
|
|
///
|
|
/// Various platform-specific conditions may cause `TempDir` to fail
|
|
/// to delete the underlying directory. It's important to ensure that
|
|
/// handles (like [`File`] and [`ReadDir`]) to files inside the
|
|
/// directory are dropped before the `TempDir` goes out of scope. The
|
|
/// `TempDir` destructor will silently ignore any errors in deleting
|
|
/// the directory; to instead handle errors call [`TempDir::close()`].
|
|
///
|
|
/// Note that if the program exits before the `TempDir` destructor is
|
|
/// run, such as via [`std::process::exit()`], by segfaulting, or by
|
|
/// receiving a signal like `SIGINT`, then the temporary directory
|
|
/// will not be deleted.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// Create a temporary directory with a generated name:
|
|
///
|
|
/// ```
|
|
/// use std::fs::File;
|
|
/// use std::io::Write;
|
|
/// use tempfile::TempDir;
|
|
///
|
|
/// # use std::io;
|
|
/// # fn run() -> Result<(), io::Error> {
|
|
/// // Create a directory inside of `std::env::temp_dir()`
|
|
/// let tmp_dir = TempDir::new()?;
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
///
|
|
/// Create a temporary directory with a prefix in its name:
|
|
///
|
|
/// ```
|
|
/// use std::fs::File;
|
|
/// use std::io::Write;
|
|
/// use tempfile::Builder;
|
|
///
|
|
/// # use std::io;
|
|
/// # fn run() -> Result<(), io::Error> {
|
|
/// // Create a directory inside of `std::env::temp_dir()`,
|
|
/// // whose name will begin with 'example'.
|
|
/// let tmp_dir = Builder::new().prefix("example").tempdir()?;
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
///
|
|
/// [`File`]: http://doc.rust-lang.org/std/fs/struct.File.html
|
|
/// [`Path`]: http://doc.rust-lang.org/std/path/struct.Path.html
|
|
/// [`ReadDir`]: http://doc.rust-lang.org/std/fs/struct.ReadDir.html
|
|
/// [`Builder`]: struct.Builder.html
|
|
/// [`TempDir::close()`]: struct.TempDir.html#method.close
|
|
/// [`TempDir::new()`]: struct.TempDir.html#method.new
|
|
/// [`TempDir::path()`]: struct.TempDir.html#method.path
|
|
/// [`TempDir`]: struct.TempDir.html
|
|
/// [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html
|
|
/// [`std::fs`]: http://doc.rust-lang.org/std/fs/index.html
|
|
/// [`std::process::exit()`]: http://doc.rust-lang.org/std/process/fn.exit.html
|
|
pub struct TempDir {
|
|
path: Box<Path>,
|
|
}
|
|
|
|
impl TempDir {
|
|
/// Attempts to make a temporary directory inside of `env::temp_dir()`.
|
|
///
|
|
/// See [`Builder`] for more configuration.
|
|
///
|
|
/// The directory and everything inside it will be automatically deleted
|
|
/// once the returned `TempDir` is destroyed.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// If the directory can not be created, `Err` is returned.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::fs::File;
|
|
/// use std::io::Write;
|
|
/// use tempfile::TempDir;
|
|
///
|
|
/// # use std::io;
|
|
/// # fn run() -> Result<(), io::Error> {
|
|
/// // Create a directory inside of `std::env::temp_dir()`
|
|
/// let tmp_dir = TempDir::new()?;
|
|
///
|
|
/// let file_path = tmp_dir.path().join("my-temporary-note.txt");
|
|
/// let mut tmp_file = File::create(file_path)?;
|
|
/// writeln!(tmp_file, "Brian was here. Briefly.")?;
|
|
///
|
|
/// // `tmp_dir` goes out of scope, the directory as well as
|
|
/// // `tmp_file` will be deleted here.
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
///
|
|
/// [`Builder`]: struct.Builder.html
|
|
pub fn new() -> io::Result<TempDir> {
|
|
Builder::new().tempdir()
|
|
}
|
|
|
|
/// Attempts to make a temporary directory inside of `dir`.
|
|
/// The directory and everything inside it will be automatically
|
|
/// deleted once the returned `TempDir` is destroyed.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// If the directory can not be created, `Err` is returned.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::fs::{self, File};
|
|
/// use std::io::Write;
|
|
/// use tempfile::TempDir;
|
|
///
|
|
/// # use std::io;
|
|
/// # fn run() -> Result<(), io::Error> {
|
|
/// // Create a directory inside of the current directory
|
|
/// let tmp_dir = TempDir::new_in(".")?;
|
|
/// let file_path = tmp_dir.path().join("my-temporary-note.txt");
|
|
/// let mut tmp_file = File::create(file_path)?;
|
|
/// writeln!(tmp_file, "Brian was here. Briefly.")?;
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
pub fn new_in<P: AsRef<Path>>(dir: P) -> io::Result<TempDir> {
|
|
Builder::new().tempdir_in(dir)
|
|
}
|
|
|
|
/// Accesses the [`Path`] to the temporary directory.
|
|
///
|
|
/// [`Path`]: http://doc.rust-lang.org/std/path/struct.Path.html
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use tempfile::TempDir;
|
|
///
|
|
/// # use std::io;
|
|
/// # fn run() -> Result<(), io::Error> {
|
|
/// let tmp_path;
|
|
///
|
|
/// {
|
|
/// let tmp_dir = TempDir::new()?;
|
|
/// tmp_path = tmp_dir.path().to_owned();
|
|
///
|
|
/// // Check that the temp directory actually exists.
|
|
/// assert!(tmp_path.exists());
|
|
///
|
|
/// // End of `tmp_dir` scope, directory will be deleted
|
|
/// }
|
|
///
|
|
/// // Temp directory should be deleted by now
|
|
/// assert_eq!(tmp_path.exists(), false);
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
pub fn path(&self) -> &path::Path {
|
|
self.path.as_ref()
|
|
}
|
|
|
|
/// Persist the temporary directory to disk, returning the [`PathBuf`] where it is located.
|
|
///
|
|
/// This consumes the [`TempDir`] without deleting directory on the filesystem, meaning that
|
|
/// the directory will no longer be automatically deleted.
|
|
///
|
|
/// [`TempDir`]: struct.TempDir.html
|
|
/// [`PathBuf`]: http://doc.rust-lang.org/std/path/struct.PathBuf.html
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::fs;
|
|
/// use tempfile::TempDir;
|
|
///
|
|
/// # use std::io;
|
|
/// # fn run() -> Result<(), io::Error> {
|
|
/// let tmp_dir = TempDir::new()?;
|
|
///
|
|
/// // Persist the temporary directory to disk,
|
|
/// // getting the path where it is.
|
|
/// let tmp_path = tmp_dir.into_path();
|
|
///
|
|
/// // Delete the temporary directory ourselves.
|
|
/// fs::remove_dir_all(tmp_path)?;
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
pub fn into_path(self) -> PathBuf {
|
|
// Prevent the Drop impl from being called.
|
|
let mut this = mem::ManuallyDrop::new(self);
|
|
|
|
// replace this.path with an empty Box, since an empty Box does not
|
|
// allocate any heap memory.
|
|
mem::replace(&mut this.path, PathBuf::new().into_boxed_path()).into()
|
|
}
|
|
|
|
/// Closes and removes the temporary directory, returning a `Result`.
|
|
///
|
|
/// Although `TempDir` removes the directory on drop, in the destructor
|
|
/// any errors are ignored. To detect errors cleaning up the temporary
|
|
/// directory, call `close` instead.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// This function may return a variety of [`std::io::Error`]s that result from deleting
|
|
/// the files and directories contained with the temporary directory,
|
|
/// as well as from deleting the temporary directory itself. These errors
|
|
/// may be platform specific.
|
|
///
|
|
/// [`std::io::Error`]: http://doc.rust-lang.org/std/io/struct.Error.html
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::fs::File;
|
|
/// use std::io::Write;
|
|
/// use tempfile::TempDir;
|
|
///
|
|
/// # use std::io;
|
|
/// # fn run() -> Result<(), io::Error> {
|
|
/// // Create a directory inside of `std::env::temp_dir()`.
|
|
/// let tmp_dir = TempDir::new()?;
|
|
/// let file_path = tmp_dir.path().join("my-temporary-note.txt");
|
|
/// let mut tmp_file = File::create(file_path)?;
|
|
/// writeln!(tmp_file, "Brian was here. Briefly.")?;
|
|
///
|
|
/// // By closing the `TempDir` explicitly we can check that it has
|
|
/// // been deleted successfully. If we don't close it explicitly,
|
|
/// // the directory will still be deleted when `tmp_dir` goes out
|
|
/// // of scope, but we won't know whether deleting the directory
|
|
/// // succeeded.
|
|
/// drop(tmp_file);
|
|
/// tmp_dir.close()?;
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
pub fn close(mut self) -> io::Result<()> {
|
|
let result = remove_dir_all(self.path()).with_err_path(|| self.path());
|
|
|
|
// Set self.path to empty Box to release the memory, since an empty
|
|
// Box does not allocate any heap memory.
|
|
self.path = PathBuf::new().into_boxed_path();
|
|
|
|
// Prevent the Drop impl from being called.
|
|
mem::forget(self);
|
|
|
|
result
|
|
}
|
|
}
|
|
|
|
impl AsRef<Path> for TempDir {
|
|
fn as_ref(&self) -> &Path {
|
|
self.path()
|
|
}
|
|
}
|
|
|
|
impl fmt::Debug for TempDir {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
f.debug_struct("TempDir")
|
|
.field("path", &self.path())
|
|
.finish()
|
|
}
|
|
}
|
|
|
|
impl Drop for TempDir {
|
|
fn drop(&mut self) {
|
|
let _ = remove_dir_all(self.path());
|
|
}
|
|
}
|
|
|
|
pub(crate) fn create(path: PathBuf) -> io::Result<TempDir> {
|
|
fs::create_dir(&path)
|
|
.with_err_path(|| &path)
|
|
.map(|_| TempDir {
|
|
path: path.into_boxed_path(),
|
|
})
|
|
}
|