Struct camino_tempfile::Builder
source · 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>
impl<'a, 'b> Builder<'a, 'b>
sourcepub fn new() -> Self
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")?;
sourcepub fn prefix<S: AsRef<str> + ?Sized>(&mut self, prefix: &'a S) -> &mut Self
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()?;
sourcepub fn suffix<S: AsRef<str> + ?Sized>(&mut self, suffix: &'b S) -> &mut Self
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()?;
sourcepub fn rand_bytes(&mut self, rand: usize) -> &mut Self
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()?;
sourcepub fn append(&mut self, append: bool) -> &mut Self
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()?;
sourcepub fn tempfile(&self) -> Result<NamedUtf8TempFile>
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()?;
sourcepub fn tempfile_in<P: AsRef<Utf8Path>>(
&self,
dir: P
) -> Result<NamedUtf8TempFile>
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("./")?;
sourcepub fn tempdir(&self) -> Result<Utf8TempDir>
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()?;
sourcepub fn tempdir_in<P: AsRef<Utf8Path>>(&self, dir: P) -> Result<Utf8TempDir>
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("./")?;
sourcepub fn make<F, R>(&self, f: F) -> Result<NamedUtf8TempFile<R>>where
F: FnMut(&Utf8Path) -> Result<R>,
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))?;
sourcepub fn make_in<F, R, P>(&self, dir: P, f: F) -> Result<NamedUtf8TempFile<R>>where
F: FnMut(&Utf8Path) -> Result<R>,
P: AsRef<Utf8Path>,
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))?;