How does `tempfile::TempPath::persist` handle file persistence errors compared to `persist_noclobber`?

persist atomically renames a temporary file to its target destination, potentially overwriting an existing file, while persist_noclobber refuses to overwrite an existing file and returns an error if the destination already exists. Both methods convert a temporary path into a permanent one, but they differ in how they handle the case where the destination file already exists—persist replaces it, while persist_noclobber fails with an AlreadyExists error.

The TempPath Type

use tempfile::NamedTempFile;
use std::path::Path;
 
fn temppath_overview() {
    // TempPath represents a temporary file path that will be
    // deleted when dropped (unless persisted)
    
    let temp_file = NamedTempFile::new().unwrap();
    let temp_path = temp_file.into_temp_path();
    
    // At this point:
    // - The file exists at a temporary location
    // - Dropping temp_path would delete the file
    
    // persist() moves the file to a permanent location
    let permanent_path = temp_path.persist("/path/to/permanent").unwrap();
}

TempPath is the result of converting a NamedTempFile into just its path, allowing persistence control.

The persist Method

use tempfile::NamedTempFile;
use std::io::Write;
 
fn persist_example() -> std::io::Result<()> {
    // Create a temporary file
    let mut temp_file = NamedTempFile::new()?;
    
    // Write data to it
    writeln!(temp_file, "Important data")?;
    
    // Convert to TempPath
    let temp_path = temp_file.into_temp_path();
    
    // Persist to a permanent location
    // This will OVERWRITE any existing file at the destination
    let result = temp_path.persist("data.txt");
    
    match result {
        Ok(permanent_path) => {
            println!("File persisted to {:?}", permanent_path);
            // File now exists at data.txt
            // temp_path is consumed and won't delete the file
        }
        Err((e, temp_path)) => {
            // Persistence failed
            // temp_path is returned back, so file still exists
            // The temporary file is NOT deleted
            eprintln!("Failed to persist: {}", e);
        }
    }
    
    Ok(())
}

persist attempts to rename the temporary file to the target path, potentially overwriting existing files.

The persist_noclobber Method

use tempfile::NamedTempFile;
use std::io::Write;
 
fn persist_noclobber_example() -> std::io::Result<()> {
    let mut temp_file = NamedTempFile::new()?;
    writeln!(temp_file, "Important data")?;
    
    let temp_path = temp_file.into_temp_path();
    
    // persist_noclobber REFUSES to overwrite existing files
    let result = temp_path.persist_noclobber("data.txt");
    
    match result {
        Ok(permanent_path) => {
            println!("File persisted to {:?}", permanent_path);
        }
        Err((e, temp_path)) => {
            // Could fail because:
            // 1. Destination file already exists (AlreadyExists error)
            // 2. Other I/O error
            
            if e.kind() == std::io::ErrorKind::AlreadyExists {
                println!("File already exists, refusing to overwrite");
                // temp_path still owns the temporary file
            } else {
                println!("Other error: {}", e);
            }
        }
    }
    
    Ok(())
}

persist_noclobber fails if the destination already exists, protecting existing data.

Key Difference: Overwrite Behavior

use tempfile::NamedTempFile;
use std::io::Write;
use std::fs;
 
fn overwrite_comparison() -> std::io::Result<()> {
    // Create an existing file
    fs::write("existing.txt", "Original content")?;
    
    // Create a temp file
    let mut temp = NamedTempFile::new()?;
    writeln!(temp, "New content")?;
    let temp_path = temp.into_temp_path();
    
    // persist() WILL overwrite existing.txt
    // temp_path.persist("existing.txt").unwrap();
    // Result: existing.txt now contains "New content"
    
    // persist_noclobber() WILL NOT overwrite
    let result = temp_path.persist_noclobber("existing.txt");
    match result {
        Ok(_) => println!("File persisted"),
        Err((e, temp_path)) => {
            if e.kind() == std::io::ErrorKind::AlreadyExists {
                println!("Refusing to overwrite existing file");
                // temp_path still owns the temp file
                // We can try a different path or handle the error
            }
        }
    }
    
    Ok(())
}

The fundamental difference is whether existing files at the destination are protected.

Error Handling Pattern

use tempfile::NamedTempFile;
use std::path::PathBuf;
 
fn error_handling() -> std::io::Result<()> {
    let temp_file = NamedTempFile::new()?;
    let temp_path = temp_file.into_temp_path();
    
    // Both methods return Result<PathBuf, (io::Error, TempPath)>
    // On success: PathBuf (the permanent path)
    // On error: (io::Error, TempPath) - error AND the temp path back
    
    // This error pattern is important:
    // - The TempPath is returned on error
    // - You still own the temporary file
    // - You can try again, try a different path, or let it drop
    
    let result = temp_path.persist_noclobber("/important/data.txt");
    
    match result {
        Ok(path) => {
            println!("Persisted to {:?}", path);
            // File is now permanent
        }
        Err((error, temp_path)) => {
            // Error occurred, but we still have the temp file
            println!("Error: {}", error);
            
            // Try a different location
            let result2 = temp_path.persist_noclobber("/backup/data.txt");
            
            match result2 {
                Ok(path) => println!("Saved to backup: {:?}", path),
                Err((e, temp_path)) => {
                    // Give up, let temp_path drop and delete the file
                    println!("Backup also failed: {}", e);
                    // temp_path dropped here, temp file deleted
                }
            }
        }
    }
    
    Ok(())
}

Both methods return ownership of TempPath on error, allowing recovery attempts.

When to Use persist

use tempfile::NamedTempFile;
use std::io::Write;
 
fn persist_use_cases() -> std::io::Result<()> {
    // Use persist when:
    // 1. You want to atomically update a file
    // 2. Overwriting is acceptable or desired
    // 3. Implementing "save" semantics
    
    // Example: Updating a configuration file
    let mut temp = NamedTempFile::new()?;
    writeln!(temp, "new_config=true")?;
    
    let temp_path = temp.into_temp_path();
    
    // Atomically replace existing config
    // If this succeeds, the old config is gone
    // If this fails, the old config is preserved
    temp_path.persist("config.txt")?;
    
    // Example: Writing to a log file
    // (Not typical for logs, but shows overwrite semantics)
    let temp_path = NamedTempFile::new()?.into_temp_path();
    temp_path.persist("latest_output.txt")?;
    
    // The destination file is atomically replaced
    
    Ok(())
}

Use persist for atomic file updates where overwriting is intentional.

When to Use persist_noclobber

use tempfile::NamedTempFile;
use std::io::Write;
 
fn persist_noclobber_use_cases() -> std::io::Result<()> {
    // Use persist_noclobber when:
    // 1. Data preservation is critical
    // 2. You must not overwrite existing files
    // 3. Implementing "create new" semantics
    
    // Example: Creating unique output files
    let temp = NamedTempFile::new()?;
    let temp_path = temp.into_temp_path();
    
    // Try to persist to a specific name
    match temp_path.persist_noclobber("output_001.txt") {
        Ok(_) => println!("Created new file"),
        Err((e, temp_path)) if e.kind() == std::io::ErrorKind::AlreadyExists => {
            // File exists, try with a different name
            temp_path.persist_noclobber("output_002.txt")?;
        }
        Err((e, temp_path)) => {
            // Other error
            return Err(e);
        }
    }
    
    // Example: Protecting user data
    let temp_path = NamedTempFile::new()?.into_temp_path();
    
    // Refuse to overwrite user's important file
    match temp_path.persist_noclobber("user_data.txt") {
        Ok(_) => println!("Created new user data file"),
        Err((e, _)) if e.kind() == std::io::ErrorKind::AlreadyExists => {
            println!("user_data.txt already exists, not overwriting");
        }
        Err((e, _)) => return Err(e),
    }
    
    Ok(())
}

Use persist_noclobber when you must not overwrite existing data.

Atomicity and Error Recovery

use tempfile::NamedTempFile;
use std::io::Write;
use std::path::Path;
 
fn atomicity() -> std::io::Result<()> {
    // Both persist() and persist_noclobber() use atomic rename where possible
    
    // On Unix: rename() syscall is atomic
    // On Windows: MoveFileEx with MOVEFILE_REPLACE_EXISTING for persist()
    //             MoveFileEx without REPLACE_EXISTING for persist_noclobber()
    
    // Atomic means:
    // - Either the file is at the old location, OR at the new location
    // - Never in both places simultaneously
    // - Never lost in transit
    // - Observers see the complete file, not partial writes
    
    let mut temp = NamedTempFile::new()?;
    writeln!(temp, "Critical data")?;
    
    let temp_path = temp.into_temp_path();
    
    // If persist fails:
    // - The temp file is still at the temp location
    // - No data is lost
    // - The original destination (if it existed) is unchanged
    
    match temp_path.persist("important.txt") {
        Ok(path) => println!("Atomically moved to {:?}", path),
        Err((e, temp_path)) => {
            // The temp file is still safe
            println!("Failed to move: {}", e);
            // Can retry or handle the error
        }
    }
    
    Ok(())
}

Both methods use atomic operations; errors leave both source and destination intact.

Cross-Filesystem Limitations

use tempfile::NamedTempFile;
use std::path::Path;
 
fn cross_filesystem() {
    // Note: Atomic rename only works within the same filesystem
    // If temp and destination are on different filesystems:
    
    // 1. persist() and persist_noclobber() will fall back to copy + delete
    // 2. This is NOT atomic
    // 3. May fail partway through
    
    // Example: Temp on /tmp, destination on /home
    // /tmp might be tmpfs, /home might be a separate partition
    
    // In this case:
    // - persist() copies the file, then deletes the temp
    // - If copy fails, temp is preserved
    // - If copy succeeds but delete fails, you have two copies
    
    // Best practice: Create temp files in the same directory as destination
    // NamedTempFile::new_in(destination_dir)
}

Both methods may fall back to non-atomic copy when crossing filesystems.

Practical Pattern: Save to Unique Files

use tempfile::NamedTempFile;
use std::io::Write;
use std::path::PathBuf;
 
fn save_unique(base_path: &str) -> std::io::Result<PathBuf> {
    // Pattern: Create a temp file, persist to unique path
    let mut temp = NamedTempFile::new()?;
    writeln!(temp, "Generated content")?;
    
    let temp_path = temp.into_temp_path();
    
    // Use persist_noclobber to ensure uniqueness
    let mut counter = 0;
    let mut result;
    
    loop {
        let path = if counter == 0 {
            base_path.to_string()
        } else {
            format!("{}.{}", base_path, counter)
        };
        
        result = temp_path.persist_noclobber(&path);
        
        match result {
            Ok(permanent_path) => return Ok(permanent_path),
            Err((e, returned_temp)) => {
                if e.kind() == std::io::ErrorKind::AlreadyExists {
                    // Try next number
                    counter += 1;
                    temp_path = returned_temp;
                    continue;
                } else {
                    // Other error
                    return Err(e);
                }
            }
        }
    }
}

persist_noclobber enables safe unique file creation by retrying on conflicts.

Practical Pattern: Atomic Config Update

use tempfile::NamedTempFile;
use std::io::Write;
use std::path::Path;
 
fn update_config_atomic(config_path: &Path, content: &str) -> std::io::Result<()> {
    // Create temp file in same directory as config (same filesystem)
    let parent = config_path.parent().unwrap_or(Path::new("."));
    let mut temp = NamedTempFile::new_in(parent)?;
    
    write!(temp, "{}", content)?;
    
    let temp_path = temp.into_temp_path();
    
    // Atomically replace the config
    // Old config is preserved until rename succeeds
    // New config appears atomically if rename succeeds
    temp_path.persist(config_path)?;
    
    // If persist fails:
    // - Old config is unchanged
    // - Temp file is preserved for retry
    
    Ok(())
}

Use persist for atomic configuration or data file updates.

Return Types Comparison

use tempfile::NamedTempFile;
use std::path::PathBuf;
 
fn return_types() {
    // Both methods return the same type:
    // Result<PathBuf, (io::Error, TempPath)>
    
    let temp_path = NamedTempFile::new().unwrap().into_temp_path();
    
    // On success: PathBuf
    let result: Result<PathBuf, (std::io::Error, tempfile::TempPath)> = 
        temp_path.persist("destination.txt");
    
    // The PathBuf is the canonical path where the file now resides
    
    // On error: (io::Error, TempPath)
    // - The error describes what went wrong
    // - The TempPath is returned so you still own the temp file
}

Both methods share the same return type pattern for consistent error handling.

Error Types

use tempfile::NamedTempFile;
use std::io;
 
fn error_types() {
    let temp_path = NamedTempFile::new().unwrap().into_temp_path();
    
    // Common errors for both:
    // - PermissionDenied: No write permission to destination
    // - NotFound: Parent directory doesn't exist
    // - InvalidInput: Invalid path
    
    // Errors specific to persist_noclobber:
    // - AlreadyExists: Destination file exists (this is the key difference)
    
    match temp_path.persist_noclobber("existing.txt") {
        Ok(_) => println!("Success"),
        Err((e, _)) => {
            match e.kind() {
                io::ErrorKind::AlreadyExists => {
                    // Only persist_noclobber returns this
                    println!("File exists, won't overwrite");
                }
                io::ErrorKind::PermissionDenied => {
                    println!("Permission denied");
                }
                _ => {
                    println!("Other error: {}", e);
                }
            }
        }
    }
}

persist_noclobber specifically returns AlreadyExists when the destination file exists.

Dropping Behavior After Error

use tempfile::NamedTempFile;
 
fn dropping_after_error() {
    let temp_path = NamedTempFile::new().unwrap().into_temp_path();
    
    let result = temp_path.persist_noclobber("/protected/path.txt");
    
    match result {
        Ok(_) => {
            // File persisted successfully
            // TempPath is consumed, file is permanent
        }
        Err((e, temp_path)) => {
            // Persistence failed
            // temp_path is returned back
            
            // Choice: What to do with temp_path?
            
            // Option 1: Try again
            // temp_path.persist_noclobber("/other/path.txt")
            
            // Option 2: Let it drop (file is deleted)
            drop(temp_path);  // Explicit or implicit
            // Temporary file is now deleted
        }
    }
}

On error, you retain ownership of the temporary file and decide its fate.

Synthesis

Comparison table:

Aspect	`persist`	`persist_noclobber`
Overwrite behavior	Replaces existing file	Fails if file exists
Return on error	`(Error, TempPath)`	`(Error, TempPath)`
Atomic	Yes (same filesystem)	Yes (same filesystem)
Common error	Permission, NotFound	Permission, NotFound, AlreadyExists
Use case	Updates, replacements	New files, unique creation

When to use persist:

// Atomic config update
let temp_path = temp.into_temp_path();
temp_path.persist("config.yaml")?;
 
// Replace latest version
let temp_path = temp.into_temp_path();
temp_path.persist("latest_output.txt")?;
 
// Update a database file
let temp_path = temp.into_temp_path();
temp_path.persist("data.db")?;

When to use persist_noclobber:

// Create unique output
let temp_path = temp.into_temp_path();
temp_path.persist_noclobber("output_001.txt")?;
 
// Protect user data
let temp_path = temp.into_temp_path();
temp_path.persist_noclobber("user_save.txt")?;  // Won't overwrite
 
// Create if not exists
match temp_path.persist_noclobber(path) {
    Ok(_) => println!("Created"),
    Err((e, _)) if e.kind() == std::io::ErrorKind::AlreadyExists => {
        println!("Already exists");
    }
    Err((e, _)) => return Err(e),
}

Key insight: Both persist and persist_noclobber atomically convert a temporary file into a permanent one, returning ownership on error so you can retry or clean up. The difference is solely in how they handle existing files at the destination: persist atomically replaces the existing file (safe for updates), while persist_noclobber refuses to overwrite and returns an AlreadyExists error (safe for creating new files without data loss). Use persist for "save" semantics where you want to update a file, and persist_noclobber for "create" semantics where you must not clobber existing data. Both preserve the temporary file on error, giving you full control over recovery or cleanup.

How does tempfile::TempPath::persist handle file persistence errors compared to persist_noclobber?