Struct `TempDir`

struct TempDir { ... }

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 [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;

// Create a directory inside of `env::temp_dir()`
let tmp_dir = TempDir::new()?;
# Ok::<(), std::io::Error>(())

Create a temporary directory with a prefix in its name:

use std::fs::File;
use std::io::Write;
use tempfile::Builder;

// Create a directory inside of `env::temp_dir()`,
// whose name will begin with 'example'.
let tmp_dir = Builder::new().prefix("example").tempdir()?;
# Ok::<(), std::io::Error>(())

Implementations

`impl TempDir`

fn new() -> Result<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;

// Create a directory inside of `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::<(), std::io::Error>(())

fn new_in<P: AsRef<Path>>(dir: P) -> Result<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;

// 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::<(), std::io::Error>(())

fn with_prefix<S: AsRef<OsStr>>(prefix: S) -> Result<TempDir>

Attempts to make a temporary directory with the specified prefix inside of env::temp_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;

// Create a directory inside of the current directory
let tmp_dir = TempDir::with_prefix("foo-")?;
let tmp_name = tmp_dir.path().file_name().unwrap().to_str().unwrap();
assert!(tmp_name.starts_with("foo-"));
# Ok::<(), std::io::Error>(())

fn with_suffix<S: AsRef<OsStr>>(suffix: S) -> Result<TempDir>

Attempts to make a temporary directory with the specified suffix inside of env::temp_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;

// Create a directory inside of the current directory
let tmp_dir = TempDir::with_suffix("-foo")?;
let tmp_name = tmp_dir.path().file_name().unwrap().to_str().unwrap();
assert!(tmp_name.ends_with("-foo"));
# Ok::<(), std::io::Error>(())

fn with_suffix_in<S: AsRef<OsStr>, P: AsRef<Path>>(suffix: S, dir: P) -> Result<TempDir>

Attempts to make a temporary directory with the specified prefix inside the specified directory. 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;

// Create a directory inside of the current directory
let tmp_dir = TempDir::with_suffix_in("-foo", ".")?;
let tmp_name = tmp_dir.path().file_name().unwrap().to_str().unwrap();
assert!(tmp_name.ends_with("-foo"));
# Ok::<(), std::io::Error>(())

fn with_prefix_in<S: AsRef<OsStr>, P: AsRef<Path>>(prefix: S, dir: P) -> Result<TempDir>

Attempts to make a temporary directory with the specified prefix inside the specified directory. 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;

// Create a directory inside of the current directory
let tmp_dir = TempDir::with_prefix_in("foo-", ".")?;
let tmp_name = tmp_dir.path().file_name().unwrap().to_str().unwrap();
assert!(tmp_name.starts_with("foo-"));
# Ok::<(), std::io::Error>(())

fn path(self: &Self) -> &Path

Accesses the Path to the temporary directory.

Examples

use tempfile::TempDir;

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::<(), std::io::Error>(())

fn into_path(self: Self) -> PathBuf

Deprecated alias for TempDir::keep.

fn keep(self: Self) -> PathBuf

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.

If you want to disable automatic cleanup of the temporary directory in-place, keeping the TempDir as-is, use TempDir::disable_cleanup instead.

Examples

use std::fs;
use tempfile::TempDir;

let tmp_dir = TempDir::new()?;

// Persist the temporary directory to disk,
// getting the path where it is.
let tmp_path = tmp_dir.keep();

// Delete the temporary directory ourselves.
fs::remove_dir_all(tmp_path)?;
# Ok::<(), std::io::Error>(())

fn disable_cleanup(self: &mut Self, disable_cleanup: bool)

Disable cleanup of the temporary directory. If disable_cleanup is true, the temporary directory will not be deleted when this TempDir is dropped. This method is equivalent to calling Builder::disable_cleanup when creating the TempDir.

NOTE: this method is primarily useful for testing/debugging. If you want to simply turn a temporary directory into a non-temporary directory, prefer TempDir::keep.

fn close(self: Self) -> Result<()>

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::Errors 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.

Examples

use std::fs::File;
use std::io::Write;
use tempfile::TempDir;

// Create a directory inside of `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::<(), std::io::Error>(())

`impl AsRef for TempDir`

fn as_ref(self: &Self) -> &Path

`impl Debug for TempDir`

fn fmt(self: &Self, f: &mut Formatter<'_>) -> Result

`impl Drop for TempDir`

fn drop(self: &mut Self)

`impl Freeze for TempDir`

`impl RefUnwindSafe for TempDir`

`impl Send for TempDir`

`impl Sync for TempDir`

`impl Unpin for TempDir`

`impl UnsafeUnpin for TempDir`

`impl UnwindSafe for TempDir`

`impl<T> Any for TempDir`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for TempDir`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for TempDir`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> From for TempDir`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T, U> Into for TempDir`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for TempDir`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for TempDir`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>