Struct NamedTempFile 

pub struct NamedTempFile { /* private fields */ }

A temporary file that auto-deletes when dropped.

Companion to crate::TempDir. Where TempDir manages a directory, NamedTempFile manages a single zero-byte file at a fresh path under the OS temp location. The caller reopens the path with std::fs::OpenOptions (or any other API) when ready to write or read.

The default basename is .tmpfile-{pid}-{name12}, intentionally distinct from TempDir’s .tmp-{pid}-{name12} so an operator inspecting the OS temp location can tell the two apart at a glance. The 12 trailing characters use the same Crockford base32 generator as TempDir, so the optional mod-rand feature controls both types in lockstep. The embedded PID lets cleanup_orphans identify files left behind by crashed processes.

Example

use mod_tempdir::NamedTempFile;
use std::io::Write;

let f = NamedTempFile::new().unwrap();
let mut handle = std::fs::OpenOptions::new()
    .write(true)
    .open(f.path())
    .unwrap();
handle.write_all(b"hello").unwrap();
drop(handle);
// `f` is deleted automatically when it goes out of scope.

Cleanup semantics

Drop calls std::fs::remove_file best-effort. A failure (file already gone, permission denied, or a still-open handle on Windows) is intentionally swallowed: a Drop impl must not panic. Use NamedTempFile::persist to keep the file alive past drop.

Windows handle-lock caveat

On Windows, std::fs::remove_file returns ERROR_SHARING_VIOLATION (surfaced in Rust as std::io::ErrorKind::PermissionDenied) if any process still holds an open handle to the file at the moment of Drop. The library does not retry. Drop must not block, and retries cannot force-close a caller-owned handle. The file is left on disk in that case. Close any handles you open against NamedTempFile::path before the NamedTempFile drops to guarantee cleanup.

Implementations

impl NamedTempFile

pub fn new() -> Result<Self>

Create a new temporary file in the system’s temp location (/tmp on Linux/macOS, %TEMP% on Windows).

The basename is .tmpfile-{pid}-{name12} where {pid} is the current process ID (used by cleanup_orphans to identify entries left behind by crashed processes) and {name12} is a 12-character Crockford base32 string from the shared name generator. The file is materialized via std::fs::File::create; the returned File handle is closed before this function returns, so the caller starts from a clean slate.

With the mod-rand feature enabled, the name fragment comes from mod_rand::tier2::unique_name. Without it, from the same internal process-unique mixer as TempDir::new.

Errors

Returns the underlying io::Error from std::fs::File::create if the file cannot be created.

Example

use mod_tempdir::NamedTempFile;

let f = NamedTempFile::new().unwrap();
assert!(f.path().is_file());

pub fn with_prefix(prefix: &str) -> Result<Self>

Create a new temporary file with the given prefix.

The final basename is {prefix}-{12-char-name}. The prefix is joined verbatim and is the caller’s responsibility to sanitize.

Errors

Returns the underlying io::Error from std::fs::File::create if the file cannot be created.

Example

use mod_tempdir::NamedTempFile;

let f = NamedTempFile::with_prefix("my-fixture").unwrap();
assert!(f
    .path()
    .file_name()
    .unwrap()
    .to_string_lossy()
    .starts_with("my-fixture-"));

pub fn path(&self) -> &Path

Return the path of this temporary file.

pub fn persist(self) -> PathBuf

Consume this NamedTempFile and return the path, disabling cleanup on drop. The file will persist.

Use this when you want to inspect contents after a test fails.

pub fn cleanup_on_drop(&self) -> bool

Return true if the file will be deleted on drop.

Trait Implementations

impl Debug for NamedTempFile

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

Formats the value using the given formatter.

impl Drop for NamedTempFile

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.