Struct Builder

struct Builder<'a, 'b> { ... }

Create a new temporary file or directory with custom options.

Implementations

impl<'a, 'b> Builder<'a, 'b>

fn new() -> Self

Create a new Builder.

Examples

Create a named temporary file and write some data into it:

use std::ffi::OsStr;
use tempfile::Builder;

let named_tempfile = Builder::new()
    .prefix("my-temporary-note")
    .suffix(".txt")
    .rand_bytes(5)
    .tempfile()?;

let name = named_tempfile
    .path()
    .file_name().and_then(OsStr::to_str);

if let Some(name) = name {
    assert!(name.starts_with("my-temporary-note"));
    assert!(name.ends_with(".txt"));
    assert_eq!(name.len(), "my-temporary-note.txt".len() + 5);
}
# Ok::<(), std::io::Error>(())

Create a temporary directory and add a file to it:

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

let dir = Builder::new()
    .prefix("my-temporary-dir")
    .rand_bytes(5)
    .tempdir()?;

let file_path = dir.path().join("my-temporary-note.txt");
let mut file = File::create(file_path)?;
writeln!(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 `dir` goes out
// of scope, but we won't know whether deleting the directory
// succeeded.
drop(file);
dir.close()?;
# Ok::<(), std::io::Error>(())

Create a temporary directory with a chosen prefix under a chosen folder:

use tempfile::Builder;

let dir = Builder::new()
    .prefix("my-temporary-dir")
    .tempdir_in("folder-with-tempdirs")?;
# Ok::<(), std::io::Error>(())

fn prefix<S: AsRef<OsStr> + ?Sized>(self: &mut Self, prefix: &'a S) -> &mut Self

Set a custom filename prefix.

Path separators are legal but not advisable. Default: .tmp.

Examples

use tempfile::Builder;

let named_tempfile = Builder::new()
    .prefix("my-temporary-note")
    .tempfile()?;
# Ok::<(), std::io::Error>(())

fn suffix<S: AsRef<OsStr> + ?Sized>(self: &mut Self, suffix: &'b S) -> &mut Self

Set a custom filename suffix.

Path separators are legal but not advisable. Default: empty.

Examples

use tempfile::Builder;

let named_tempfile = Builder::new()
    .suffix(".txt")
    .tempfile()?;
# Ok::<(), std::io::Error>(())

fn rand_bytes(self: &mut Self, rand: usize) -> &mut Self

Set the number of random bytes.

Default: 6.

Examples

use tempfile::Builder;

let named_tempfile = Builder::new()
    .rand_bytes(5)
    .tempfile()?;
# Ok::<(), std::io::Error>(())

fn append(self: &mut Self, append: bool) -> &mut Self

Set the file to be opened in append mode.

Default: false.

Examples

use tempfile::Builder;

let named_tempfile = Builder::new()
    .append(true)
    .tempfile()?;
# Ok::<(), std::io::Error>(())

fn permissions(self: &mut Self, permissions: std::fs::Permissions) -> &mut Self

The permissions to create the tempfile or tempdir with.

Security

By default, the permissions of tempfiles on Unix are set for it to be readable and writable by the owner only, yielding the greatest amount of security. As this method allows to widen the permissions, security would be reduced in such cases.

Platform Notes

Unix

The actual permission bits set on the tempfile or tempdir will be affected by the umask applied by the underlying syscall. The actual permission bits are calculated via permissions & !umask.

Permissions default to 0o600 for tempfiles and 0o777 for tempdirs. Note, this doesn't include effects of the current umask. For example, combined with the standard umask 0o022, the defaults yield 0o600 for tempfiles and 0o755 for tempdirs.

Windows and others

This setting is unsupported and trying to set a file or directory read-only will return an error.

Examples

Create a named temporary file that is world-readable.

# #[cfg(unix)]
# {
use tempfile::Builder;
use std::os::unix::fs::PermissionsExt;

let all_read_write = std::fs::Permissions::from_mode(0o666);
let tempfile = Builder::new().permissions(all_read_write).tempfile()?;
let actual_permissions = tempfile.path().metadata()?.permissions();
assert_ne!(
    actual_permissions.mode() & !0o170000,
    0o600,
    "we get broader permissions than the default despite umask"
);
# }
# Ok::<(), std::io::Error>(())

Create a named temporary directory that is restricted to the owner.

# #[cfg(unix)]
# {
use tempfile::Builder;
use std::os::unix::fs::PermissionsExt;

let owner_rwx = std::fs::Permissions::from_mode(0o700);
let tempdir = Builder::new().permissions(owner_rwx).tempdir()?;
let actual_permissions = tempdir.path().metadata()?.permissions();
assert_eq!(
    actual_permissions.mode() & !0o170000,
    0o700,
    "we get the narrow permissions we asked for"
);
# }
# Ok::<(), std::io::Error>(())

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

Disable cleanup of the file/folder to even when the NamedTempFile/TempDir goes out of scope. Prefer NamedTempFile::keep and [TempDir::keep](TempDir::keep) where possible, disable_cleanup` is provided for testing & debugging.

By default, the file/folder is automatically cleaned up in the destructor of NamedTempFile/TempDir. When disable_cleanup is set to true, this behavior is suppressed. If you wish to disable cleanup after creating a temporary file/directory, call NamedTempFile::disable_cleanup or TempDir::disable_cleanup.

Warnings

On some platforms (for now, only Windows), temporary files are marked with a special "temporary file" (FILE_ATTRIBUTE_TEMPORARY) attribute. Disabling cleanup will not unset this attribute while calling NamedTempFile::keep will.

Examples

use tempfile::Builder;

let named_tempfile = Builder::new()
    .disable_cleanup(true)
    .tempfile()?;
# Ok::<(), std::io::Error>(())

fn keep(self: &mut Self, keep: bool) -> &mut Self

Deprecated alias for Builder::disable_cleanup.

fn tempfile(self: &Self) -> io::Result<NamedTempFile>

Create the named temporary file.

Security

See the security docs on NamedTempFile.

Resource leaking

See the resource leaking docs on NamedTempFile.

Errors

If the file cannot be created, Err is returned.

Examples

use tempfile::Builder;

let tempfile = Builder::new().tempfile()?;
# Ok::<(), std::io::Error>(())

fn tempfile_in<P: AsRef<Path>>(self: &Self, dir: P) -> io::Result<NamedTempFile>

Create the named temporary file in the specified directory.

Security

See the security docs on NamedTempFile.

Resource leaking

See the resource leaking docs on NamedTempFile.

Errors

If the file cannot be created, Err is returned.

Examples

use tempfile::Builder;

let tempfile = Builder::new().tempfile_in("./")?;
# Ok::<(), std::io::Error>(())

fn tempdir(self: &Self) -> io::Result<TempDir>

Attempts to make a temporary directory inside of [env::temp_dir()] whose name will have the prefix, prefix. The directory and everything inside it will be automatically deleted once the returned TempDir is destroyed.

Resource leaking

See the resource leaking docs on TempDir.

Errors

If the directory can not be created, Err is returned.

Examples

use tempfile::Builder;

let tmp_dir = Builder::new().tempdir()?;
# Ok::<(), std::io::Error>(())

fn tempdir_in<P: AsRef<Path>>(self: &Self, dir: P) -> io::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.

Resource leaking

See the resource leaking docs on TempDir.

Errors

If the directory can not be created, Err is returned.

Examples

use tempfile::Builder;

let tmp_dir = Builder::new().tempdir_in("./")?;
# Ok::<(), std::io::Error>(())

fn make<F, R>(self: &Self, f: F) -> io::Result<NamedTempFile<R>>
where
    F: FnMut(&Path) -> io::Result<R>

Attempts to create a temporary file (or file-like object) using the provided closure. The closure is passed a temporary file path and returns an std::io::Result. The path provided to the closure will be inside of [env::temp_dir()]. Use Builder::make_in to provide a custom temporary directory. If the closure returns one of the following errors, then another randomized file path is tried:

This can be helpful for taking full control over the file creation, but leaving the temporary file path construction up to the library. This also enables creating a temporary UNIX domain socket, since it is not possible to bind to a socket that already exists.

Note that Builder::append is ignored when using Builder::make.

Security

This has the same security implications as NamedTempFile, but with additional caveats. Specifically, it is up to the closure to ensure that the file does not exist and that such a check is atomic. Otherwise, a time-of-check to time-of-use bug could be introduced.

For example, the following is not secure:

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

// This is NOT secure!
let tempfile = Builder::new().make(|path| {
    if path.is_file() {
        return Err(std::io::ErrorKind::AlreadyExists.into());
    }

    // Between the check above and the usage below, an attacker could
    // have replaced `path` with another file, which would get truncated
    // by `File::create`.

    File::create(path)
})?;
# Ok::<(), std::io::Error>(())

Note that simply using std::fs::File::create alone is not correct because it does not fail if the file already exists:

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

// This could overwrite an existing file!
let tempfile = Builder::new().make(|path| File::create(path))?;
# Ok::<(), std::io::Error>(())

For creating regular temporary files, use Builder::tempfile instead to avoid these problems. This function is meant to enable more exotic use-cases.

Resource leaking

See the resource leaking docs on NamedTempFile.

Errors

If the closure returns any error besides std::io::ErrorKind::AlreadyExists or std::io::ErrorKind::AddrInUse, then Err is returned.

Examples

# #[cfg(unix)]
# {
use std::os::unix::net::UnixListener;
use tempfile::Builder;

let tempsock = Builder::new().make(|path| UnixListener::bind(path))?;
# }
# Ok::<(), std::io::Error>(())

fn make_in<F, R, P>(self: &Self, dir: P, f: F) -> io::Result<NamedTempFile<R>>
where
    F: FnMut(&Path) -> io::Result<R>,
    P: AsRef<Path>

This is the same as Builder::make, except dir is used as the base directory for the temporary file path.

See Builder::make for more details and security implications.

Examples

# #[cfg(unix)]
# {
use tempfile::Builder;
use std::os::unix::net::UnixListener;

let tempsock = Builder::new().make_in("./", |path| UnixListener::bind(path))?;
# }
# Ok::<(), std::io::Error>(())

impl Default for Builder<'_, '_>

fn default() -> Self

impl<'a, 'b> Clone for Builder<'a, 'b>

fn clone(self: &Self) -> Builder<'a, 'b>

impl<'a, 'b> Debug for Builder<'a, 'b>

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

impl<'a, 'b> Eq for Builder<'a, 'b>

impl<'a, 'b> Freeze for Builder<'a, 'b>

impl<'a, 'b> PartialEq for Builder<'a, 'b>

fn eq(self: &Self, other: &Builder<'a, 'b>) -> bool

impl<'a, 'b> RefUnwindSafe for Builder<'a, 'b>

impl<'a, 'b> Send for Builder<'a, 'b>

impl<'a, 'b> StructuralPartialEq for Builder<'a, 'b>

impl<'a, 'b> Sync for Builder<'a, 'b>

impl<'a, 'b> Unpin for Builder<'a, 'b>

impl<'a, 'b> UnwindSafe for Builder<'a, 'b>

impl<T> Any for Builder<'a, 'b>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Builder<'a, 'b>

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

impl<T> BorrowMut for Builder<'a, 'b>

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

impl<T> CloneToUninit for Builder<'a, 'b>

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for Builder<'a, 'b>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for Builder<'a, 'b>

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

impl<T, U> Into for Builder<'a, 'b>

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 Builder<'a, 'b>

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

impl<T, U> TryInto for Builder<'a, 'b>

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