pub struct Builder<'a, 'b> { /* private fields */ }
Expand description

Create a new temporary file or directory with custom parameters.

Implementations§

source§

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

source

pub fn new() -> Self

Create a new Builder.

Examples

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

use camino_tempfile::Builder;

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

let name = named_tempfile.path().file_name();

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);
}

Create a temporary directory and add a file to it:

use camino_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 `Utf8TempDir` 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()?;

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

let dir = Builder::new()
    .prefix("my-temporary-dir")
    .tempdir_in("folder-with-tempdirs")?;
source

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

Set a custom filename prefix.

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

Examples
let named_tempfile = Builder::new()
    .prefix("my-temporary-note")
    .tempfile()?;
source

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

Set a custom filename suffix.

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

Examples
let named_tempfile = Builder::new()
    .suffix(".txt")
    .tempfile()?;
source

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

Set the number of random bytes.

Default: 6.

Examples
let named_tempfile = Builder::new()
    .rand_bytes(5)
    .tempfile()?;
source

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

Set the file to be opened in append mode.

Default: false.

Examples
let named_tempfile = Builder::new()
    .append(true)
    .tempfile()?;
source

pub fn tempfile(&self) -> Result<NamedUtf8TempFile>

Create the named temporary file.

Security

See the security docs on NamedUtf8TempFile.

Resource leaking

See the resource leaking docs on NamedUtf8TempFile.

Errors

If the file cannot be created, Err is returned.

Examples
let tempfile = Builder::new().tempfile()?;
source

pub fn tempfile_in<P: AsRef<Utf8Path>>( &self, dir: P ) -> Result<NamedUtf8TempFile>

Create the named temporary file in the specified directory.

Security

See the security docs on NamedUtf8TempFile.

Resource leaking

See the resource leaking docs on NamedUtf8TempFile.

Errors

If the file cannot be created, Err is returned.

Examples
let tempfile = Builder::new().tempfile_in("./")?;
source

pub fn tempdir(&self) -> Result<Utf8TempDir>

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

Resource leaking

See the resource leaking docs on TempDir.

Errors

If the directory can not be created, or if std::env::temp_dir() is non-UTF-8, Err is returned.

Examples
use std::fs::File;
use std::io::Write;
use camino_tempfile::Builder;

let tmp_dir = Builder::new().tempdir()?;
source

pub fn tempdir_in<P: AsRef<Utf8Path>>(&self, dir: P) -> Result<Utf8TempDir>

Attempts to make a temporary directory inside of dir. The directory and everything inside it will be automatically deleted once the returned Utf8TempDir is destroyed.

Resource leaking

See the resource leaking docs on Utf8TempDir.

Errors

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

Examples
use std::fs::{self, File};
use std::io::Write;
use camino_tempfile::Builder;

let tmp_dir = Builder::new().tempdir_in("./")?;
source

pub fn make<F, R>(&self, f: F) -> Result<NamedUtf8TempFile<R>>where F: FnMut(&Utf8Path) -> 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 std::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 NamedUtf8TempFile, 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:

// This is NOT secure!
let tempfile = Builder::new().make(|path| {
    if path.is_file() {
        return Err(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)
})?;

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

// This could overwrite an existing file!
let tempfile = Builder::new().make(|path| File::create(path))?;

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 NamedUtf8TempFile.

Errors

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

Examples
use std::os::unix::net::UnixListener;
let tempsock = Builder::new().make(|path| UnixListener::bind(path))?;
source

pub fn make_in<F, R, P>(&self, dir: P, f: F) -> Result<NamedUtf8TempFile<R>>where F: FnMut(&Utf8Path) -> Result<R>, P: AsRef<Utf8Path>,

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
use std::os::unix::net::UnixListener;
let tempsock = Builder::new().make_in("./", |path| UnixListener::bind(path))?;

Trait Implementations§

source§

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

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

fn default() -> Builder<'a, 'b>

Returns the “default value” for a type. Read more
source§

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

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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

source§

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

source§

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

Auto Trait Implementations§

§

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

§

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

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.