diff --git a/Cargo.toml b/Cargo.toml index 56e700285..19018ee93 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,8 +1,10 @@ [package] name = "tempfile" -version = "2.2.0" -authors = ["Steven Allen "] -description = "Securely create temporary files." +version = "2.1.6" +authors = ["Steven Allen ", "The Rust Project Developers"] +description = """ +A library for managing temporary files and directories. +""" documentation = "https://stebalien.github.io/tempfile/tempfile/" repository = "https://github.com/Stebalien/tempfile" @@ -12,6 +14,7 @@ license = "MIT/Apache-2.0" [dependencies] rand = "0.4" +remove_dir_all = "0.3" [target.'cfg(unix)'.dependencies] libc = "0.2" diff --git a/src/dir.rs b/src/dir.rs new file mode 100644 index 000000000..e97c48c4f --- /dev/null +++ b/src/dir.rs @@ -0,0 +1,357 @@ +// Copyright 2015 The Rust Project Developers. See the COPYRIGHT +// file at the top-level directory of this distribution and at +// http://rust-lang.org/COPYRIGHT. +// +// Licensed under the Apache License, Version 2.0 or the MIT license +// , at your +// option. This file may not be copied, modified, or distributed +// except according to those terms. + +use std::env; +use std::io::{self, Error, ErrorKind}; +use std::fmt; +use std::fs; +use std::path::{self, PathBuf, Path}; +use rand::{thread_rng, Rng}; +use remove_dir_all::remove_dir_all; + +/// Create a new temporary directory. +/// +/// The `tempdir` function creates a directory in the file system +/// and returns a [`TempDir`]. +/// The directory will be automatically deleted when the `TempDir`s +/// desctructor is run. +/// +/// # Resource Leaking +/// +/// See [the resource leaking][resource-leaking] docs on `TempDir`. +/// +/// # Errors +/// +/// If the directory can not be created, `Err` is returned. +/// +/// # Examples +/// +/// ``` +/// # extern crate tempfile; +/// use tempfile::tempdir; +/// use std::fs::File; +/// use std::io::{self, Write}; +/// +/// # fn main() { +/// # if let Err(_) = run() { +/// # ::std::process::exit(1); +/// # } +/// # } +/// # fn run() -> Result<(), io::Error> { +/// // Create a directory inside of `std::env::temp_dir()`, named with +/// // the prefix "example". +/// let dir = tempdir("example")?; +/// +/// let file_path = dir.path().join("my-temporary-note.txt"); +/// let mut file = File::create(file_path)?; +/// writeln!(file, "Brian was here. Briefly.")?; +/// +/// // `tmp_dir` goes out of scope, the directory as well as +/// // `tmp_file` will be deleted here. +/// drop(file); +/// dir.close()?; +/// # Ok(()) +/// # } +/// ``` +/// +/// [`TempDir`]: struct.TempDir.html +/// [resource-leaking]: struct.TempDir.html#resource-leaking +pub fn tempdir(prefix: &str) -> io::Result { + TempDir::new(prefix) +} + +/// A directory in the filesystem that is automatically deleted when +/// it goes out of scope. +/// +/// The [`TempDir`] type creates a directory on the file system that +/// is deleted once it goes out of scope. At construction, the +/// `TempDir` creates a new directory with a randomly generated name, +/// and with a prefix of your choosing. +/// +/// The default constructor, [`TempDir::new`], creates directories in +/// the location returned by [`std::env::temp_dir()`], but `TempDir` +/// can be configured to manage a temporary directory in any location +/// by constructing with [`TempDir::new_in`]. +/// +/// After creating a `TempDir`, work with the file system by doing +/// standard [`std::fs`] file system operations on its [`Path`], +/// which can be retrieved with [`TempDir::path`]. Once the `TempDir` +/// value is dropped, the directory at the path will be deleted, along +/// with any files and directories it contains. It is your responsibility +/// to ensure that no further file system operations are attempted +/// inside the temporary directory once it has been deleted. +/// +/// # Resource Leaking +/// +/// Various platform-specific conditions may cause `TempDir` to fail +/// to delete the underlying directory. It's important to ensure that +/// handles (like [`File`] and [`ReadDir`]) to files inside the +/// directory are dropped before the `TempDir` goes out of scope. The +/// `TempDir` destructor will silently ignore any errors in deleting +/// the directory; to instead handle errors call [`TempDir::close`]. +/// +/// Note that if the program exits before the `TempDir` destructor is +/// run, such as via [`std::process::exit`], by segfaulting, or by +/// receiving a signal like `SIGINT`, then the temporary directory +/// will not be deleted. +/// +/// [`File`]: http://doc.rust-lang.org/std/fs/struct.File.html +/// [`Path`]: http://doc.rust-lang.org/std/path/struct.Path.html +/// [`ReadDir`]: http://doc.rust-lang.org/std/fs/struct.ReadDir.html +/// [`TempDir::close`]: struct.TempDir.html#method.close +/// [`TempDir::new`]: struct.TempDir.html#method.new +/// [`TempDir::new_in`]: struct.TempDir.html#method.new_in +/// [`TempDir::path`]: struct.TempDir.html#method.path +/// [`TempDir`]: struct.TempDir.html +/// [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html +/// [`std::fs`]: http://doc.rust-lang.org/std/fs/index.html +/// [`std::process::exit`]: http://doc.rust-lang.org/std/process/fn.exit.html +pub struct TempDir { + path: Option, +} + +// How many times should we (re)try finding an unused random name? It should be +// enough that an attacker will run out of luck before we run out of patience. +const NUM_RETRIES: u32 = 1 << 31; +// How many characters should we include in a random file name? It needs to +// be enough to dissuade an attacker from trying to preemptively create names +// of that length, but not so huge that we unnecessarily drain the random number +// generator of entropy. +const NUM_RAND_CHARS: usize = 12; + +impl 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. + /// + /// # Errors + /// + /// If the directory can not be created, `Err` is returned. + /// + /// # Examples + /// + /// ``` + /// use std::fs::File; + /// use std::io::Write; + /// use tempfile::TempDir; + /// + /// # use std::io; + /// # fn run() -> Result<(), io::Error> { + /// // Create a directory inside of `std::env::temp_dir()`, named with + /// // the prefix, "example". + /// let tmp_dir = TempDir::new("example")?; + /// let file_path = tmp_dir.path().join("my-temporary-note.txt"); + /// let mut tmp_file = File::create(file_path)?; + /// writeln!(tmp_file, "Brian was here. Briefly.")?; + /// + /// // `tmp_dir` goes out of scope, the directory as well as + /// // `tmp_file` will be deleted here. + /// # Ok(()) + /// # } + /// ``` + pub fn new(prefix: &str) -> io::Result { + TempDir::new_in(&env::temp_dir(), prefix) + } + + /// Attempts to make a temporary directory inside of `tmpdir` + /// whose name will have the prefix `prefix`. The directory and + /// everything inside it will be automatically deleted once the + /// returned `TempDir` is destroyed. + /// + /// # Errors + /// + /// If the directory can not be created, `Err` is returned. + /// + /// # Examples + /// + /// ``` + /// use std::fs::{self, File}; + /// use std::io::Write; + /// use tempfile::TempDir; + /// + /// # use std::io; + /// # fn run() -> Result<(), io::Error> { + /// // Create a directory inside of the current directory, named with + /// // the prefix, "example". + /// let tmp_dir = TempDir::new_in(".", "example")?; + /// let file_path = tmp_dir.path().join("my-temporary-note.txt"); + /// let mut tmp_file = File::create(file_path)?; + /// writeln!(tmp_file, "Brian was here. Briefly.")?; + /// # Ok(()) + /// # } + /// ``` + pub fn new_in>(tmpdir: P, prefix: &str) -> io::Result { + let storage; + let mut tmpdir = tmpdir.as_ref(); + if !tmpdir.is_absolute() { + let cur_dir = env::current_dir()?; + storage = cur_dir.join(tmpdir); + tmpdir = &storage; + // return TempDir::new_in(&cur_dir.join(tmpdir), prefix); + } + + let mut rng = thread_rng(); + for _ in 0..NUM_RETRIES { + let suffix: String = rng.gen_ascii_chars().take(NUM_RAND_CHARS).collect(); + let leaf = if !prefix.is_empty() { + format!("{}.{}", prefix, suffix) + } else { + // If we're given an empty string for a prefix, then creating a + // directory starting with "." would lead to it being + // semi-invisible on some systems. + suffix + }; + let path = tmpdir.join(&leaf); + match fs::create_dir(&path) { + Ok(_) => return Ok(TempDir { path: Some(path) }), + Err(ref e) if e.kind() == ErrorKind::AlreadyExists => {} + Err(e) => return Err(e), + } + } + + Err(Error::new(ErrorKind::AlreadyExists, + "too many temporary directories already exist")) + } + + /// Accesses the [`Path`] to the temporary directory. + /// + /// [`Path`]: http://doc.rust-lang.org/std/path/struct.Path.html + /// + /// # Examples + /// + /// ``` + /// use tempfile::TempDir; + /// + /// # use std::io; + /// # fn run() -> Result<(), io::Error> { + /// let tmp_path; + /// + /// { + /// let tmp_dir = TempDir::new("example")?; + /// tmp_path = tmp_dir.path().to_owned(); + /// + /// // Check that the temp directory actually exists. + /// assert!(tmp_path.exists()); + /// + /// // End of `tmp_dir` scope, directory will be deleted + /// } + /// + /// // Temp directory should be deleted by now + /// assert_eq!(tmp_path.exists(), false); + /// # Ok(()) + /// # } + /// ``` + pub fn path(&self) -> &path::Path { + self.path.as_ref().unwrap() + } + + /// Unwraps the [`Path`] contained in the `TempDir` and + /// returns it. This destroys the `TempDir` without deleting the + /// directory represented by the returned `Path`. + /// + /// [`Path`]: http://doc.rust-lang.org/std/path/struct.Path.html + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use tempfile::TempDir; + /// + /// # use std::io; + /// # fn run() -> Result<(), io::Error> { + /// let tmp_dir = TempDir::new("example")?; + /// + /// // Convert `tmp_dir` into a `Path`, destroying the `TempDir` + /// // without deleting the directory. + /// let tmp_path = tmp_dir.into_path(); + /// + /// // Delete the temporary directory ourselves. + /// fs::remove_dir_all(tmp_path)?; + /// # Ok(()) + /// # } + /// ``` + pub fn into_path(mut self) -> PathBuf { + self.path.take().unwrap() + } + + /// Closes and removes the temporary directory, returing a `Result`. + /// + /// Although `TempDir` removes the directory on drop, in the destructor + /// any errors are ignored. To detect errors cleaning up the temporary + /// directory, call `close` instead. + /// + /// # Errors + /// + /// This function may return a variety of [`std::io::Error`]s that result from deleting + /// the files and directories contained with the temporary directory, + /// as well as from deleting the temporary directory itself. These errors + /// may be platform specific. + /// + /// [`std::io::Error`]: http://doc.rust-lang.org/std/io/struct.Error.html + /// + /// # Examples + /// + /// ``` + /// use std::fs::File; + /// use std::io::Write; + /// use tempfile::TempDir; + /// + /// # use std::io; + /// # fn run() -> Result<(), io::Error> { + /// // Create a directory inside of `std::env::temp_dir()`, named with + /// // the prefix, "example". + /// let tmp_dir = TempDir::new("example")?; + /// let file_path = tmp_dir.path().join("my-temporary-note.txt"); + /// let mut tmp_file = File::create(file_path)?; + /// writeln!(tmp_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 `tmp_dir` goes out + /// // of scope, but we won't know whether deleting the directory + /// // succeeded. + /// drop(tmp_file); + /// tmp_dir.close()?; + /// # Ok(()) + /// # } + /// ``` + pub fn close(mut self) -> io::Result<()> { + let result = remove_dir_all(self.path()); + + // Prevent the Drop impl from removing the dir a second time. + self.path = None; + + result + } +} + +impl AsRef for TempDir { + fn as_ref(&self) -> &Path { + self.path() + } +} + +impl fmt::Debug for TempDir { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.debug_struct("TempDir") + .field("path", &self.path()) + .finish() + } +} + +impl Drop for TempDir { + fn drop(&mut self) { + // Path is `None` if `close()` or `into_path()` has been called. + if let Some(ref p) = self.path { + let _ = remove_dir_all(p); + } + } +} diff --git a/src/directory.rs b/src/directory.rs deleted file mode 100644 index 8aeb73a87..000000000 --- a/src/directory.rs +++ /dev/null @@ -1,63 +0,0 @@ -use super::imp; -use super::util; - -struct TempDir { - path: PathBuf, - inner: TempDirImp -} - -impl TempDir { - pub fn new() -> TempDir { - // TODO - } - pub fn new_in>(dir: P) -> io::Result { - let path = dir.as_ref().join(&util::tmpname()); - path.push(""); // Make it a directory. - // TODO - } - - // TODO: Real Options - /// Securely create a file in this directory. - /// - /// TODO: SECURITY WARNING - pub fn open_file>(&self, path: P, create: bool) -> io::Result { - self.inner.open_file(path.as_ref(), create) - } - - pub fn remove_file>(path: P) -> io::Result<()> { - self.inner.remove_file(path.as_ref()); - } - - /// Remove the specified directory. - /// - /// If recurse is true, this function recursivly deletes all files and directories under the - /// specified directory. When false, this function will refuse to delete non-empty directories. - /// - /// Note: If recurse is true, this function is not atomic. If it failes to delete a - /// subdirectory/file, this function will return an error without proceeding. - pub fn remove_dir>(&self, path: P, recurse: bool) -> io::Result<()> { - self.inner.remove_dir(path.as_ref(), recurse); - } - - pub fn rename, P2: AsRef>(&self, from: P1, to: P2) -> io::Result<()> { - self.inner.rename(from.as_ref(), to.as_ref()); - } - - /// Persist the temporary directory at the target path. - /// - /// If an empty directory exists at the target path, persist will atomically replace it. If - /// this method fails, it will return `self` in the resulting PersistError. - /// - /// Note: Temporary directories cannot be persisted across filesystems. - /// - /// *SECURITY WARNING:* Only use this method if you're positive that a temporary file cleaner - /// won't have deleted your directory. Otherwise, you might end up persisting an attacker - /// controlled directory. - #[inline] - pub fn persist>(mut self, new_path: P) -> Result { - match fs::rename(&self.inner().path, new_path) { - Ok(_) => Ok(self.0.take().unwrap().file), - Err(e) => Err(PersistError { file: self, error: e }), - } - } -} diff --git a/src/imp/mod.rs b/src/file/imp/mod.rs similarity index 100% rename from src/imp/mod.rs rename to src/file/imp/mod.rs diff --git a/src/imp/unix.rs b/src/file/imp/unix.rs similarity index 99% rename from src/imp/unix.rs rename to src/file/imp/unix.rs index 6a0f8039b..5e1244258 100644 --- a/src/imp/unix.rs +++ b/src/file/imp/unix.rs @@ -6,7 +6,7 @@ use std::io; use std::os::unix::io::{RawFd, FromRawFd, AsRawFd}; use std::fs::{self, File, OpenOptions}; use std::path::Path; -use util; +use file::util; #[cfg(all(lfs_support, target_os = "linux"))] use libc::{open64 as open, fstat64 as fstat, stat64 as stat_t}; diff --git a/src/imp/windows.rs b/src/file/imp/windows.rs similarity index 98% rename from src/imp/windows.rs rename to src/file/imp/windows.rs index 89e16bf8a..ec72a01f4 100644 --- a/src/imp/windows.rs +++ b/src/file/imp/windows.rs @@ -14,7 +14,7 @@ use winapi::um::winnt::{FILE_ATTRIBUTE_NORMAL, FILE_ATTRIBUTE_TEMPORARY, FILE_AT use winapi::um::winnt::{FILE_GENERIC_WRITE, FILE_GENERIC_READ, HANDLE}; use winapi::um::winnt::{FILE_SHARE_READ, FILE_SHARE_DELETE, FILE_SHARE_WRITE}; -use util; +use file::util; #[cfg_attr(irustfmt, rustfmt_skip)] const ACCESS: DWORD = FILE_GENERIC_READ @@ -76,7 +76,7 @@ pub fn create(dir: &Path) -> io::Result { "too many temporary directories already exist")) } -pub fn reopen(file: &File, path: &Path) -> io::Result { +pub fn reopen(file: &File, _path: &Path) -> io::Result { let handle = file.as_raw_handle(); unsafe { let handle = ReOpenFile(handle as HANDLE, ACCESS, SHARE_MODE, 0); diff --git a/src/file/mod.rs b/src/file/mod.rs new file mode 100644 index 000000000..950c13cde --- /dev/null +++ b/src/file/mod.rs @@ -0,0 +1,807 @@ +use std::io::{self, Read, Write, Seek, SeekFrom}; +use std::fs::{self, File}; +use std::path::{Path, PathBuf}; +use std::error; +use std::fmt; +use std::env; +use std; + +mod imp; +mod util; + +/// Create a new temporary file. +/// +/// The file will be created in the location returned by [`std::env::temp_dir()`] +/// +/// # Security +/// +/// This variant is secure/reliable in the presence of a pathological temporary file cleaner. +/// +/// # Resource Leaking +/// +/// The temporary file will be automatically removed by the OS when the last handle to it is closed. +/// This doesn't rely on Rust destructors being run, so will (almost) never fail to clean up the temporary file. +/// +/// # Errors +/// +/// If the file can not be created, `Err` is returned. +/// +/// # Examples +/// +/// ``` +/// # extern crate tempfile; +/// use tempfile::tempfile; +/// use std::io::{self, Write}; +/// +/// # fn main() { +/// # if let Err(_) = run() { +/// # ::std::process::exit(1); +/// # } +/// # } +/// # fn run() -> Result<(), io::Error> { +/// // Create a file inside of `std::env::temp_dir()`. +/// let mut file = tempfile()?; +/// +/// writeln!(file, "Brian was here. Briefly.")?; +/// # Ok(()) +/// # } +/// ``` +/// +/// [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html +pub fn tempfile() -> io::Result { + tempfile_in(&env::temp_dir()) +} + +/// Create a new temporary file in the specified directory. +/// +/// # Security +/// +/// This variant is secure/reliable in the presence of a pathological temporary file cleaner. +/// If the temporary file isn't created in [`std::env::temp_dir()`] then temporary file cleaners aren't an issue. +/// +/// # Resource Leaking +/// +/// The temporary file will be automatically removed by the OS when the last handle to it is closed. +/// This doesn't rely on Rust destructors being run, so will (almost) never fail to clean up the temporary file. +/// +/// # Errors +/// +/// If the file can not be created, `Err` is returned. +/// +/// # Examples +/// +/// ``` +/// # extern crate tempfile; +/// use tempfile::tempfile_in; +/// use std::io::{self, Write}; +/// +/// # fn main() { +/// # if let Err(_) = run() { +/// # ::std::process::exit(1); +/// # } +/// # } +/// # fn run() -> Result<(), io::Error> { +/// // Create a file inside of the current working directory +/// let mut file = tempfile_in("./")?; +/// +/// writeln!(file, "Brian was here. Briefly.")?; +/// # Ok(()) +/// # } +/// ``` +/// +/// [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html +pub fn tempfile_in>(dir: P) -> io::Result { + imp::create(dir.as_ref()) +} + +/// A named temporary file. +/// +/// The default constructor, [`NamedTempFile::new`], creates files in +/// the location returned by [`std::env::temp_dir()`], but `NamedTempFile` +/// can be configured to manage a temporary file in any location +/// by constructing with [`NamedTempFile::new_in`]. +/// +/// # Security +/// +/// This variant is *NOT* secure/reliable in the presence of a pathological temporary file cleaner. +/// +/// # Resource Leaking +/// +/// If the program exits before the `NamedTempFile` destructor is +/// run, such as via [`std::process::exit`], by segfaulting, or by +/// receiving a signal like `SIGINT`, then the temporary file +/// will not be deleted. +/// +/// Use the [`tempfile`] function unless you absolutely need a named file. +/// +/// [`tempfile`]: fn.tempfile.html +/// [`NamedTempFile::new`]: #method.new +/// [`NamedTempFile::new_in`]: #method.new_in +/// [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html +/// [`std::process::exit`]: http://doc.rust-lang.org/std/process/fn.exit.html +pub struct NamedTempFile(Option); + +struct NamedTempFileInner { + file: File, + path: PathBuf, +} + +impl fmt::Debug for NamedTempFile { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "NamedTempFile({:?})", self.inner().path) + } +} + +impl AsRef for NamedTempFile { + #[inline] + fn as_ref(&self) -> &Path { + self.path() + } +} + +/// Error returned when persisting a temporary file fails. +#[derive(Debug)] +pub struct PersistError { + /// The underlying IO error. + pub error: io::Error, + /// The temporary file that couldn't be persisted. + pub file: NamedTempFile, +} + +impl From for io::Error { + #[inline] + fn from(error: PersistError) -> io::Error { + error.error + } +} + +impl From for NamedTempFile { + #[inline] + fn from(error: PersistError) -> NamedTempFile { + error.file + } +} + +impl fmt::Display for PersistError { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "failed to persist temporary file: {}", self.error) + } +} + +impl error::Error for PersistError { + fn description(&self) -> &str { + "failed to persist temporary file" + } + fn cause(&self) -> Option<&error::Error> { + Some(&self.error) + } +} + +impl NamedTempFile { + #[inline] + fn inner(&self) -> &NamedTempFileInner { + self.0.as_ref().unwrap() + } + + #[inline] + fn inner_mut(&mut self) -> &mut NamedTempFileInner { + self.0.as_mut().unwrap() + } + + #[inline] + fn take_inner(&mut self) -> NamedTempFileInner { + self.0.take().unwrap() + } + + /// Create a new named temporary file. + /// + /// See [`NamedTempFileBuilder`] for more configuration. + /// + /// # Security + /// + /// This will create a temporary file in the default temporary file + /// directory (platform dependent). These directories are often patrolled by temporary file + /// cleaners so only use this method if you're *positive* that the temporary file cleaner won't + /// delete your file. + /// + /// Reasons to use this method: + /// + /// 1. The file has a short lifetime and your temporary file cleaner is + /// sane (doesn't delete recently accessed files). + /// + /// 2. You trust every user on your system (i.e. you are the only user). + /// + /// 3. You have disabled your system's temporary file cleaner or verified + /// that your system doesn't have a temporary file cleaner. + /// + /// Reasons not to use this method: + /// + /// 1. You'll fix it later. No you won't. + /// + /// 2. You don't care about the security of the temporary file. If none of + /// the "reasons to use this method" apply, referring to a temporary + /// file by name may allow an attacker to create/overwrite your + /// non-temporary files. There are exceptions but if you don't already + /// know them, don't use this method. + /// + /// # Errors + /// + /// If the file can not be created, `Err` is returned. + /// + /// # Examples + /// + /// Create a named temporary file and write some data to it: + /// + /// ```no_run + /// # use std::io::{self, Write}; + /// # extern crate tempfile; + /// use tempfile::NamedTempFile; + /// + /// # fn main() { + /// # if let Err(_) = run() { + /// # ::std::process::exit(1); + /// # } + /// # } + /// # fn run() -> Result<(), ::std::io::Error> { + /// let mut file = NamedTempFile::new()?; + /// + /// writeln!(file, "Brian was here. Briefly.")?; + /// # Ok(()) + /// # } + /// ``` + /// + /// [`NamedTempFileBuilder`]: struct.NamedTempFileBuilder.html + pub fn new() -> io::Result { + NamedTempFileBuilder::new().create() + } + + /// Create a new temporary file in the specified directory. + /// + /// # Errors + /// + /// If the file can not be created, `Err` is returned. + /// + /// # Examples + /// + /// Create a named temporary file in the current location and write some data to it: + /// + /// ```no_run + /// # use std::io::{self, Write}; + /// # extern crate tempfile; + /// use tempfile::NamedTempFile; + /// + /// # fn main() { + /// # if let Err(_) = run() { + /// # ::std::process::exit(1); + /// # } + /// # } + /// # fn run() -> Result<(), ::std::io::Error> { + /// let mut file = NamedTempFile::new_in("./")?; + /// + /// writeln!(file, "Brian was here. Briefly.")?; + /// # Ok(()) + /// # } + /// ``` + /// + /// [`NamedTempFile::new`]: #method.new + pub fn new_in>(dir: P) -> io::Result { + NamedTempFileBuilder::new().create_in(dir) + } + + + /// Get the temporary file's path. + /// + /// # Security + /// + /// Only use this method if you're positive that a + /// temporary file cleaner won't have deleted your file. Otherwise, the path + /// returned by this method may refer to an attacker controlled file. + /// + /// # Examples + /// + /// ```no_run + /// # use std::io::{self, Write}; + /// # extern crate tempfile; + /// use tempfile::NamedTempFile; + /// + /// # fn main() { + /// # if let Err(_) = run() { + /// # ::std::process::exit(1); + /// # } + /// # } + /// # fn run() -> Result<(), ::std::io::Error> { + /// let file = NamedTempFile::new()?; + /// + /// println!("{:?}", file.path()); + /// # Ok(()) + /// # } + /// ``` + #[inline] + pub fn path(&self) -> &Path { + &self.inner().path + } + + /// Close and remove the temporary file. + /// + /// Use this if you want to detect errors in deleting the file. + /// + /// # Errors + /// + /// If the file cannot be deleted, `Err` is returned. + /// + /// # Examples + /// + /// ```no_run + /// # extern crate tempfile; + /// # use std::io; + /// use tempfile::NamedTempFile; + /// + /// # fn main() { + /// # if let Err(_) = run() { + /// # ::std::process::exit(1); + /// # } + /// # } + /// # fn run() -> Result<(), io::Error> { + /// let file = NamedTempFile::new()?; + /// + /// // By closing the `NamedTempFile` explicitly, we can check that it has + /// // been deleted successfully. If we don't close it explicitly, + /// // the file will still be deleted when `file` goes out + /// // of scope, but we won't know whether deleting the file + /// // succeeded. + /// file.close()?; + /// # Ok(()) + /// # } + /// ``` + pub fn close(mut self) -> io::Result<()> { + let NamedTempFileInner { path, file } = self.take_inner(); + drop(file); + fs::remove_file(path) + } + + /// Persist the temporary file at the target path. + /// + /// If a file exists at the target path, persist will atomically replace it. + /// If this method fails, it will return `self` in the resulting + /// [`PersistError`]. + /// + /// Note: Temporary files cannot be persisted across filesystems. + /// + /// # Security + /// + /// Only use this method if you're positive that a + /// temporary file cleaner won't have deleted your file. Otherwise, you + /// might end up persisting an attacker controlled file. + /// + /// # Errors + /// + /// If the file cannot be moved to the new location, `Err` is returned. + /// + /// # Examples + /// + /// ```no_run + /// # use std::io::{self, Write}; + /// # extern crate tempfile; + /// use tempfile::NamedTempFile; + /// + /// # fn main() { + /// # if let Err(_) = run() { + /// # ::std::process::exit(1); + /// # } + /// # } + /// # fn run() -> Result<(), io::Error> { + /// let file = NamedTempFile::new()?; + /// + /// let mut persisted_file = file.persist("./saved_file.txt")?; + /// writeln!(persisted_file, "Brian was here. Briefly.")?; + /// # Ok(()) + /// # } + /// ``` + /// + /// [`PersistError`]: struct.PersistError.html + pub fn persist>(mut self, new_path: P) -> Result { + match imp::persist(&self.inner().path, new_path.as_ref(), true) { + Ok(_) => Ok(self.take_inner().file), + Err(e) => { + Err(PersistError { + file: self, + error: e, + }) + } + } + } + + /// Persist the temporary file at the target path iff no file exists there. + /// + /// If a file exists at the target path, fail. If this method fails, it will + /// return `self` in the resulting PersistError. + /// + /// Note: Temporary files cannot be persisted across filesystems. Also Note: + /// This method is not atomic. It can leave the original link to the + /// temporary file behind. + /// + /// # Security + /// + /// Only use this method if you're positive that a + /// temporary file cleaner won't have deleted your file. Otherwise, you + /// might end up persisting an attacker controlled file. + /// + /// # Errors + /// + /// If the file cannot be moved to the new location or a file already exists there, + /// `Err` is returned. + /// + /// # Examples + /// + /// ```no_run + /// # use std::io::{self, Write}; + /// # extern crate tempfile; + /// use tempfile::NamedTempFile; + /// + /// # fn main() { + /// # if let Err(_) = run() { + /// # ::std::process::exit(1); + /// # } + /// # } + /// # fn run() -> Result<(), io::Error> { + /// let file = NamedTempFile::new()?; + /// + /// let mut persisted_file = file.persist_noclobber("./saved_file.txt")?; + /// writeln!(persisted_file, "Brian was here. Briefly.")?; + /// # Ok(()) + /// # } + /// ``` + pub fn persist_noclobber>(mut self, new_path: P) -> Result { + match imp::persist(&self.inner().path, new_path.as_ref(), false) { + Ok(_) => Ok(self.take_inner().file), + Err(e) => { + Err(PersistError { + file: self, + error: e, + }) + } + } + } + + /// Reopen the temporary file. + /// + /// This function is useful when you need multiple independent handles to + /// the same file. It's perfectly fine to drop the original `NamedTempFile` + /// while holding on to `File`s returned by this function; the `File`s will + /// remain usable. However, they may not be nameable. + /// + /// # Errors + /// + /// If the file cannot be reopened, `Err` is returned. + /// + /// # Examples + /// + /// ```no_run + /// # use std::io; + /// # extern crate tempfile; + /// use tempfile::NamedTempFile; + /// + /// # fn main() { + /// # if let Err(_) = run() { + /// # ::std::process::exit(1); + /// # } + /// # } + /// # fn run() -> Result<(), io::Error> { + /// let file = NamedTempFile::new()?; + /// + /// let another_handle = file.reopen()?; + /// # Ok(()) + /// # } + /// ``` + pub fn reopen(&self) -> io::Result { + imp::reopen(self.as_file(), NamedTempFile::path(self)) + } + + /// Get a reference to the underlying file. + pub fn as_file(&self) -> &File { + &self.inner().file + } + + /// Get a mutable reference to the underlying file. + pub fn as_file_mut(&mut self) -> &mut File { + &mut self.inner_mut().file + } + + /// Convert the temporary file into a `std::fs::File`. + pub fn into_file(mut self) -> File { + let NamedTempFileInner { path, file } = self.take_inner(); + let _ = fs::remove_file(path); + file + } +} + +impl Drop for NamedTempFile { + fn drop(&mut self) { + if let Some(NamedTempFileInner { file, path }) = self.0.take() { + drop(file); + let _ = fs::remove_file(path); + } + } +} + +impl Read for NamedTempFile { + fn read(&mut self, buf: &mut [u8]) -> io::Result { + self.as_file_mut().read(buf) + } +} + +impl<'a> Read for &'a NamedTempFile { + fn read(&mut self, buf: &mut [u8]) -> io::Result { + self.as_file().read(buf) + } +} + +impl Write for NamedTempFile { + fn write(&mut self, buf: &[u8]) -> io::Result { + self.as_file_mut().write(buf) + } + #[inline] + fn flush(&mut self) -> io::Result<()> { + self.as_file_mut().flush() + } +} + +impl<'a> Write for &'a NamedTempFile { + fn write(&mut self, buf: &[u8]) -> io::Result { + self.as_file().write(buf) + } + #[inline] + fn flush(&mut self) -> io::Result<()> { + self.as_file().flush() + } +} + +impl Seek for NamedTempFile { + fn seek(&mut self, pos: SeekFrom) -> io::Result { + self.as_file_mut().seek(pos) + } +} + +impl<'a> Seek for &'a NamedTempFile { + fn seek(&mut self, pos: SeekFrom) -> io::Result { + self.as_file().seek(pos) + } +} + +#[cfg(unix)] +impl std::os::unix::io::AsRawFd for NamedTempFile { + #[inline] + fn as_raw_fd(&self) -> std::os::unix::io::RawFd { + self.as_file().as_raw_fd() + } +} + +#[cfg(windows)] +impl std::os::windows::io::AsRawHandle for NamedTempFile { + #[inline] + fn as_raw_handle(&self) -> std::os::windows::io::RawHandle { + self.as_file().as_raw_handle() + } +} + + +/// Create a new temporary file with custom parameters. +/// +/// # Security +/// +/// This variant is *NOT* secure/reliable in the presence of a pathological temporary file cleaner. +/// +/// # Resource Leaking +/// +/// `NamedTempFile`s are deleted on drop. As rust doesn't guarantee that a struct will ever be +/// dropped, these temporary files will not be deleted on abort, resource leak, early exit, etc. +#[derive(Debug, Clone, Eq, PartialEq)] +pub struct NamedTempFileBuilder<'a, 'b> { + random_len: usize, + prefix: &'a str, + suffix: &'b str, +} + +impl<'a, 'b> NamedTempFileBuilder<'a, 'b> { + /// Create a new `NamedTempFileBuilder`. + /// + /// # Examples + /// + /// ``` + /// # extern crate tempfile; + /// # use std::io; + /// # use std::ffi::OsStr; + /// # fn main() { + /// # if let Err(_) = run() { + /// # ::std::process::exit(1); + /// # } + /// # } + /// # fn run() -> Result<(), io::Error> { + /// use tempfile::NamedTempFileBuilder; + /// + /// let named_temp_file = NamedTempFileBuilder::new() + /// .prefix("my-temporary-note") + /// .suffix(".txt") + /// .rand_bytes(5) + /// .create()?; + /// + /// let name = named_temp_file + /// .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(()) + /// # } + /// ``` + pub fn new() -> Self { + NamedTempFileBuilder { + random_len: ::NUM_RAND_CHARS, + prefix: ".tmp", + suffix: "", + } + } + + /// Set a custom filename prefix. + /// + /// Path separators are legal but not advisable. + /// Default: `.tmp`. + /// + /// # Examples + /// + /// ``` + /// # extern crate tempfile; + /// # use std::io; + /// # fn main() { + /// # if let Err(_) = run() { + /// # ::std::process::exit(1); + /// # } + /// # } + /// # fn run() -> Result<(), io::Error> { + /// # use tempfile::NamedTempFileBuilder; + /// let named_temp_file = NamedTempFileBuilder::new() + /// .prefix("my-temporary-note") + /// .create()?; + /// # Ok(()) + /// # } + /// ``` + pub fn prefix(&mut self, prefix: &'a str) -> &mut Self { + self.prefix = prefix; + self + } + + /// Set a custom filename suffix. + /// + /// Path separators are legal but not advisable. + /// Default: empty. + /// + /// # Examples + /// + /// ``` + /// # extern crate tempfile; + /// # use std::io; + /// # fn main() { + /// # if let Err(_) = run() { + /// # ::std::process::exit(1); + /// # } + /// # } + /// # fn run() -> Result<(), io::Error> { + /// # use tempfile::NamedTempFileBuilder; + /// let named_temp_file = NamedTempFileBuilder::new() + /// .suffix(".txt") + /// .create()?; + /// # Ok(()) + /// # } + /// ``` + pub fn suffix(&mut self, suffix: &'b str) -> &mut Self { + self.suffix = suffix; + self + } + + /// Set the number of random bytes. + /// + /// Default: `6`. + /// + /// # Examples + /// + /// ``` + /// # extern crate tempfile; + /// # use std::io; + /// # fn main() { + /// # if let Err(_) = run() { + /// # ::std::process::exit(1); + /// # } + /// # } + /// # fn run() -> Result<(), io::Error> { + /// # use tempfile::NamedTempFileBuilder; + /// let named_temp_file = NamedTempFileBuilder::new() + /// .rand_bytes(5) + /// .create()?; + /// # Ok(()) + /// # } + /// ``` + pub fn rand_bytes(&mut self, rand: usize) -> &mut Self { + self.random_len = rand; + self + } + + /// Create the named temporary file. + /// + /// # Security + /// + /// See: [`NamedTempFile::new`] + /// + /// # Errors + /// + /// If the file cannot be created, `Err` is returned. + /// + /// # Examples + /// + /// ``` + /// # extern crate tempfile; + /// # use std::io; + /// # fn main() { + /// # if let Err(_) = run() { + /// # ::std::process::exit(1); + /// # } + /// # } + /// # fn run() -> Result<(), io::Error> { + /// # use tempfile::NamedTempFileBuilder; + /// let named_temp_file = NamedTempFileBuilder::new() + /// .create()?; + /// # Ok(()) + /// # } + /// ``` + /// + /// [`NamedTempFile::new`]: struct.NamedTempFile.html#method.new + pub fn create(&self) -> io::Result { + self.create_in(&env::temp_dir()) + } + + /// Create the named temporary file in the specified directory. + /// + /// # Errors + /// + /// If the file cannot be created, `Err` is returned. + /// + /// # Examples + /// + /// ``` + /// # extern crate tempfile; + /// # use std::io; + /// # fn main() { + /// # if let Err(_) = run() { + /// # ::std::process::exit(1); + /// # } + /// # } + /// # fn run() -> Result<(), io::Error> { + /// # use tempfile::NamedTempFileBuilder; + /// let named_temp_file = NamedTempFileBuilder::new() + /// .create_in("./")?; + /// # Ok(()) + /// # } + /// ``` + /// + /// [`NamedTempFile::new`]: struct.NamedTempFile.html#method.new + pub fn create_in>(&self, dir: P) -> io::Result { + for _ in 0..::NUM_RETRIES { + let path = dir.as_ref().join(util::tmpname(self.prefix, self.suffix, self.random_len)); + return match imp::create_named(&path) { + Ok(file) => { + Ok(NamedTempFile(Some(NamedTempFileInner { + path: path, + file: file, + }))) + } + Err(ref e) if e.kind() == io::ErrorKind::AlreadyExists => continue, + Err(e) => Err(e), + }; + } + Err(io::Error::new(io::ErrorKind::AlreadyExists, + "too many temporary files exist")) + + } +} diff --git a/src/util.rs b/src/file/util.rs similarity index 100% rename from src/util.rs rename to src/file/util.rs diff --git a/src/lib.rs b/src/lib.rs index b12b54d4e..123edf09e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,36 +1,99 @@ -//! Securely create and manage temporary files. Temporary files created by this create are -//! automatically deleted. +//! Temporary files and directories. //! -//! This crate provides two temporary file variants: a `tempfile()` function that returns standard -//! `File` objects and `NamedTempFile`. When choosing between the variants, prefer `tempfile()` -//! unless you either need to know the file's path or to be able to persist it. -//! -//! # Example +//! - Use the [`tempfile`] function for temporary files +//! - Use the [`tempdir`][fn.tempdir] function for temporary directories. //! -//! ``` -//! use tempfile::tempfile; -//! use std::fs::File; +//! # Design //! -//! let mut file: File = tempfile().expect("failed to create temporary file"); -//! ``` +//! This crate provides several approaches to creating temporary files and directories. +//! [`tempfile`] relies on the OS to remove the temporary file once the last handle is closed. +//! [`TempDir`][struct.TempDir] and [`NamedTempFile`] both rely on Rust destructors for cleanup. //! -//! # Differences +//! When choosing between the temporary file variants, prefer `tempfile` +//! unless you either need to know the file's path or to be able to persist it. //! //! ## Resource Leaking //! -//! `tempfile()` will (almost) never fail to cleanup temporary files but `NamedTempFile` will if -//! its destructor doesn't run. This is because `tempfile()` relies on the OS to cleanup the -//! underlying file so the file while `NamedTempFile` relies on its destructor to do so. +//! `tempfile` will (almost) never fail to cleanup temporary resources but `TempDir` and `NamedTempFile` will if +//! their destructor doesn't run. This is because `tempfile` relies on the OS to cleanup the +//! underlying file so the file while `TempDir` and `NamedTempFile` rely on their destructor to do so. //! //! ## Security //! //! In the presence of pathological temporary file cleaner, relying on file paths is unsafe because //! a temporary file cleaner could delete the temporary file which an attacker could then replace. //! -//! `tempfile()` doesn't rely on file paths so this isn't an issue. However, `NamedTempFile` does +//! `tempfile` doesn't rely on file paths so this isn't an issue. However, `NamedTempFile` does //! rely on file paths. //! +//! ## Examples +//! +//! Create a temporary file and write some data into it: +//! +//! ``` +//! # extern crate tempfile; +//! use tempfile::tempfile; +//! use std::io::{self, Write}; +//! +//! # fn main() { +//! # if let Err(_) = run() { +//! # ::std::process::exit(1); +//! # } +//! # } +//! # fn run() -> Result<(), io::Error> { +//! // Create a file inside of `std::env::temp_dir()`. +//! let mut file = tempfile()?; +//! +//! writeln!(file, "Brian was here. Briefly.")?; +//! # Ok(()) +//! # } +//! ``` +//! +//! Create a temporary directory and add a file to it: +//! +//! ``` +//! # extern crate tempfile; +//! use tempfile::tempdir; +//! use std::fs::File; +//! use std::io::{self, Write}; +//! +//! # fn main() { +//! # if let Err(_) = run() { +//! # ::std::process::exit(1); +//! # } +//! # } +//! # fn run() -> Result<(), io::Error> { +//! // Create a directory inside of `std::env::temp_dir()`, named with +//! // the prefix "example". +//! let dir = tempdir("example")?; +//! +//! 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(()) +//! # } +//! ``` +//! +//! [fn.tempdir]: fn.tempdir.html +//! [`tempfile`]: fn.tempfile.html +//! [struct.TempDir]: struct.TempDir.html +//! [`NamedTempFile`]: struct.NamedTempFile.html +//! [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html + +#![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png", + html_favicon_url = "https://www.rust-lang.org/favicon.ico", + html_root_url = "https://docs.rs/tempdir/0.3.5")] +#![cfg_attr(test, deny(warnings))] +extern crate remove_dir_all; extern crate rand; #[cfg(unix)] @@ -45,10 +108,8 @@ extern crate syscall; const NUM_RETRIES: u32 = 1 << 31; const NUM_RAND_CHARS: usize = 6; -mod util; -mod imp; -mod named; -mod unnamed; +mod dir; +mod file; -pub use named::{NamedTempFile, NamedTempFileOptions, PersistError}; -pub use unnamed::{tempfile, tempfile_in}; +pub use file::{tempfile, tempfile_in, NamedTempFile, NamedTempFileBuilder, PersistError}; +pub use dir::{tempdir, TempDir}; diff --git a/src/named.rs b/src/named.rs deleted file mode 100644 index f83db775a..000000000 --- a/src/named.rs +++ /dev/null @@ -1,393 +0,0 @@ -use std::io::{self, Read, Write, Seek, SeekFrom}; -use std::fs::{self, File}; -use std::path::{Path, PathBuf}; -use std::ops::{Deref, DerefMut}; -use std::error; -use std::fmt; -use std::env; -use std; -use util; - -use super::imp; - -/// A named temporary file. -/// -/// This variant is *NOT* secure/reliable in the presence of a pathological temporary file cleaner. -/// -/// `NamedTempFiles` are deleted on drop. As rust doesn't guarantee that a struct will ever be -/// dropped, these temporary files will not be deleted on abort, resource leak, early exit, etc. -/// -/// Please use `TempFile` unless you absolutely need a named file. -/// -/// Note: To convert a `NamedTempFile` into a normal temporary file, use the -/// provided conversion: `let my_file: File = my_temp_file.into();`. The file -/// will be automatically deleted on close. However, if you do this, the file's -/// path will no longer be valid. -pub struct NamedTempFile(Option); - -impl AsRef for NamedTempFile { - fn as_ref(&self) -> &File { - self - } -} - -impl AsMut for NamedTempFile { - fn as_mut(&mut self) -> &mut File { - self - } -} - -struct NamedTempFileInner { - file: File, - path: PathBuf, -} - -impl fmt::Debug for NamedTempFile { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - write!(f, "NamedTempFile({:?})", self.0.as_ref().unwrap().path) - } -} - -impl Deref for NamedTempFile { - type Target = File; - #[inline] - fn deref(&self) -> &File { - &self.inner().file - } -} - -impl DerefMut for NamedTempFile { - #[inline] - fn deref_mut(&mut self) -> &mut File { - &mut self.inner_mut().file - } -} - -/// Error returned when persisting a temporary file fails -#[derive(Debug)] -pub struct PersistError { - /// The underlying IO error. - pub error: io::Error, - /// The temporary file that couldn't be persisted. - pub file: NamedTempFile, -} - -impl From for io::Error { - #[inline] - fn from(error: PersistError) -> io::Error { - error.error - } -} - -impl From for NamedTempFile { - #[inline] - fn from(error: PersistError) -> NamedTempFile { - error.file - } -} - -impl fmt::Display for PersistError { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - write!(f, "failed to persist temporary file: {}", self.error) - } -} - -impl error::Error for PersistError { - fn description(&self) -> &str { - "failed to persist temporary file" - } - fn cause(&self) -> Option<&error::Error> { - Some(&self.error) - } -} - -impl NamedTempFile { - #[inline] - fn inner(&self) -> &NamedTempFileInner { - self.0.as_ref().unwrap() - } - - #[inline] - fn inner_mut(&mut self) -> &mut NamedTempFileInner { - self.0.as_mut().unwrap() - } - - /// Create a new temporary file. - /// - /// *SECURITY WARNING:* This will create a temporary file in the default temporary file - /// directory (platform dependent). These directories are often patrolled by temporary file - /// cleaners so only use this method if you're *positive* that the temporary file cleaner won't - /// delete your file. - /// - /// Reasons to use this method: - /// - /// 1. The file has a short lifetime and your temporary file cleaner is - /// sane (doesn't delete recently accessed files). - /// - /// 2. You trust every user on your system (i.e. you are the only user). - /// - /// 3. You have disabled your system's temporary file cleaner or verified - /// that your system doesn't have a temporary file cleaner. - /// - /// Reasons not to use this method: - /// - /// 1. You'll fix it later. No you won't. - /// - /// 2. You don't care about the security of the temporary file. If none of - /// the "reasons to use this method" apply, referring to a temporary - /// file by name may allow an attacker to create/overwrite your - /// non-temporary files. There are exceptions but if you don't already - /// know them, don't use this method. - pub fn new() -> io::Result { - NamedTempFileOptions::new().create() - } - - /// Create a new temporary file in the specified directory. - pub fn new_in>(dir: P) -> io::Result { - NamedTempFileOptions::new().create_in(dir) - } - - - /// Get the temporary file's path. - /// - /// *SECURITY WARNING:* Only use this method if you're positive that a - /// temporary file cleaner won't have deleted your file. Otherwise, the path - /// returned by this method may refer to an attacker controlled file. - #[inline] - pub fn path(&self) -> &Path { - &self.inner().path - } - - /// Close and remove the temporary file. - /// - /// Use this if you want to detect errors in deleting the file. - pub fn close(mut self) -> io::Result<()> { - let NamedTempFileInner { path, file } = self.0.take().unwrap(); - drop(file); - fs::remove_file(path) - } - - /// Persist the temporary file at the target path. - /// - /// If a file exists at the target path, persist will atomically replace it. - /// If this method fails, it will return `self` in the resulting - /// PersistError. - /// - /// Note: Temporary files cannot be persisted across filesystems. - /// - /// *SECURITY WARNING:* Only use this method if you're positive that a - /// temporary file cleaner won't have deleted your file. Otherwise, you - /// might end up persisting an attacker controlled file. - pub fn persist>(mut self, new_path: P) -> Result { - match imp::persist(&self.inner().path, new_path.as_ref(), true) { - Ok(_) => Ok(self.0.take().unwrap().file), - Err(e) => { - Err(PersistError { - file: self, - error: e, - }) - } - } - } - - /// Persist the temporary file at the target path iff no file exists there. - /// - /// If a file exists at the target path, fail. If this method fails, it will - /// return `self` in the resulting PersistError. - /// - /// Note: Temporary files cannot be persisted across filesystems. Also Note: - /// This method is not atomic. It can leave the original link to the - /// temporary file behind. - /// - /// *SECURITY WARNING:* Only use this method if you're positive that a - /// temporary file cleaner won't have deleted your file. Otherwise, you - /// might end up persisting an attacker controlled file. - pub fn persist_noclobber>(mut self, new_path: P) -> Result { - match imp::persist(&self.inner().path, new_path.as_ref(), false) { - Ok(_) => Ok(self.0.take().unwrap().file), - Err(e) => { - Err(PersistError { - file: self, - error: e, - }) - } - } - } - - /// Reopen the temporary file. - /// - /// This function is useful when you need multiple independent handles to - /// the same file. It's perfectly fine to drop the original `NamedTempFile` - /// while holding on to `File`s returned by this function; the `File`s will - /// remain usable. However, they may not be nameable. - pub fn reopen(&self) -> io::Result { - imp::reopen(self, self.path()) - } -} - -impl From for File { - fn from(mut f: NamedTempFile) -> File { - let NamedTempFileInner { path, file } = f.0.take().unwrap(); - let _ = fs::remove_file(path); - file - } -} - -impl Drop for NamedTempFile { - fn drop(&mut self) { - if let Some(NamedTempFileInner { file, path }) = self.0.take() { - drop(file); - let _ = fs::remove_file(path); - } - } -} - -impl Read for NamedTempFile { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - (**self).read(buf) - } -} - -impl<'a> Read for &'a NamedTempFile { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - (&***self).read(buf) - } -} - -impl Write for NamedTempFile { - fn write(&mut self, buf: &[u8]) -> io::Result { - (**self).write(buf) - } - #[inline] - fn flush(&mut self) -> io::Result<()> { - (**self).flush() - } -} - -impl<'a> Write for &'a NamedTempFile { - fn write(&mut self, buf: &[u8]) -> io::Result { - (&***self).write(buf) - } - #[inline] - fn flush(&mut self) -> io::Result<()> { - (&***self).flush() - } -} - -impl Seek for NamedTempFile { - fn seek(&mut self, pos: SeekFrom) -> io::Result { - (**self).seek(pos) - } -} - -impl<'a> Seek for &'a NamedTempFile { - fn seek(&mut self, pos: SeekFrom) -> io::Result { - (&***self).seek(pos) - } -} - -#[cfg(unix)] -impl std::os::unix::io::AsRawFd for NamedTempFile { - #[inline] - fn as_raw_fd(&self) -> std::os::unix::io::RawFd { - (**self).as_raw_fd() - } -} - -#[cfg(windows)] -impl std::os::windows::io::AsRawHandle for NamedTempFile { - #[inline] - fn as_raw_handle(&self) -> std::os::windows::io::RawHandle { - (**self).as_raw_handle() - } -} - - -/// Create a new temporary file with custom parameters. -/// -/// # Example -/// ``` -/// use tempfile::NamedTempFileOptions; -/// -/// let named_temp_file = NamedTempFileOptions::new() -/// .prefix("hogehoge") -/// .suffix(".rs") -/// .rand_bytes(5) -/// .create() -/// .unwrap(); -/// let name = named_temp_file.path() -/// .file_name().unwrap() -/// .to_str().unwrap(); -/// -/// assert!(name.starts_with("hogehoge")); -/// assert!(name.ends_with(".rs")); -/// assert_eq!(name.len(), "hogehoge.rs".len() + 5); -/// ``` -#[derive(Debug, Clone, Eq, PartialEq)] -pub struct NamedTempFileOptions<'a, 'b> { - random_len: usize, - prefix: &'a str, - suffix: &'b str, -} - -impl<'a, 'b> NamedTempFileOptions<'a, 'b> { - /// Create a new NamedTempFileOptions - pub fn new() -> Self { - NamedTempFileOptions { - random_len: ::NUM_RAND_CHARS, - prefix: ".tmp", - suffix: "", - } - } - - /// Set a custom filename prefix. - /// - /// Path separators are legal but not advisable. - /// Default: ".tmp" - pub fn prefix(&mut self, prefix: &'a str) -> &mut Self { - self.prefix = prefix; - self - } - - /// Set a custom filename suffix. - /// - /// Path separators are legal but not advisable. - /// Default: "" - pub fn suffix(&mut self, suffix: &'b str) -> &mut Self { - self.suffix = suffix; - self - } - - /// Set the number of random bytes. - /// - /// Default: 6 - pub fn rand_bytes(&mut self, rand: usize) -> &mut Self { - self.random_len = rand; - self - } - - /// Create the named temporary file. - pub fn create(&self) -> io::Result { - self.create_in(&env::temp_dir()) - } - - /// Create the named temporary file in the specified directory. - pub fn create_in>(&self, dir: P) -> io::Result { - for _ in 0..::NUM_RETRIES { - let path = dir.as_ref().join(util::tmpname(self.prefix, self.suffix, self.random_len)); - return match imp::create_named(&path) { - Ok(file) => { - Ok(NamedTempFile(Some(NamedTempFileInner { - path: path, - file: file, - }))) - } - Err(ref e) if e.kind() == io::ErrorKind::AlreadyExists => continue, - Err(e) => Err(e), - }; - } - Err(io::Error::new(io::ErrorKind::AlreadyExists, - "too many temporary files exist")) - - } -} diff --git a/src/options.rs b/src/options.rs deleted file mode 100644 index e69de29bb..000000000 diff --git a/src/unnamed.rs b/src/unnamed.rs deleted file mode 100644 index 211f7dc70..000000000 --- a/src/unnamed.rs +++ /dev/null @@ -1,37 +0,0 @@ -use std::fs::File; -use std::env; -use std::path::Path; -use std::io; - -use super::imp; - -/// Create an unnamed temporary file. -/// -/// This method is secure/reliable in the presence of a pathological temporary file cleaner. -/// -/// # Deletion: -/// -/// ## Linux >= 3.11** -/// -/// The temporary file is never linked into the filesystem so it can't be leaked. -/// -/// ## Other *nix -/// -/// The temporary file is immediately unlinked on create. The OS will delete it -/// when the last open copy of it is closed. -/// -/// ## Windows -/// -/// The temporary file is marked `DeleteOnClose` and, again, will be deleted -/// when the last open copy of it is closed. Unlike *nix operating systems, the -/// file is not immediately unlinked from the filesystem. -pub fn tempfile() -> io::Result { - tempfile_in(&env::temp_dir()) -} - -/// Create an unnamed temporary file in the specified directory. -/// -/// See `tempfile()` for more information. -pub fn tempfile_in>(dir: P) -> io::Result { - imp::create(dir.as_ref()) -} diff --git a/tests/namedtempfile.rs b/tests/namedtempfile.rs index a1ef35f8d..392a13aef 100644 --- a/tests/namedtempfile.rs +++ b/tests/namedtempfile.rs @@ -1,5 +1,5 @@ extern crate tempfile; -use tempfile::{NamedTempFile, NamedTempFileOptions}; +use tempfile::{NamedTempFile, NamedTempFileBuilder}; use std::env; use std::io::{Write, Read, Seek, SeekFrom}; use std::fs::File; @@ -84,7 +84,7 @@ fn test_persist_noclobber() { #[test] fn test_customnamed() { - let tmpfile = NamedTempFileOptions::new() + let tmpfile = NamedTempFileBuilder::new() .prefix("tmp") .suffix(&".rs".to_string()) .rand_bytes(12) @@ -111,13 +111,13 @@ fn test_reopen() { } #[test] -fn test_to_file() { +fn test_into_file() { let mut file = NamedTempFile::new().unwrap(); let path = file.path().to_owned(); write!(file, "abcde").expect("write failed"); assert!(path.exists()); - let mut file: File = file.into(); + let mut file = file.into_file(); assert!(!path.exists()); file.seek(SeekFrom::Start(0)).unwrap(); diff --git a/tests/tempdir.rs b/tests/tempdir.rs new file mode 100644 index 000000000..e2f3a4a36 --- /dev/null +++ b/tests/tempdir.rs @@ -0,0 +1,229 @@ +// Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT +// file at the top-level directory of this distribution and at +// http://rust-lang.org/COPYRIGHT. +// +// Licensed under the Apache License, Version 2.0 or the MIT license +// , at your +// option. This file may not be copied, modified, or distributed +// except according to those terms. + +extern crate tempfile; + +use std::env; +use std::fs; +use std::path::Path; +use std::sync::mpsc::channel; +use std::thread; + +use tempfile::TempDir; + +macro_rules! t { + ($e:expr) => (match $e { Ok(n) => n, Err(e) => panic!("error: {}", e) }) +} + +trait PathExt { + fn exists(&self) -> bool; + fn is_dir(&self) -> bool; +} + +impl PathExt for Path { + fn exists(&self) -> bool { fs::metadata(self).is_ok() } + fn is_dir(&self) -> bool { + fs::metadata(self).map(|m| m.is_dir()).unwrap_or(false) + } +} + +fn test_tempdir() { + let path = { + let p = t!(TempDir::new_in(&Path::new("."), "foobar")); + let p = p.path(); + assert!(p.to_str().unwrap().contains("foobar")); + p.to_path_buf() + }; + assert!(!path.exists()); +} + +fn test_rm_tempdir() { + let (tx, rx) = channel(); + let f = move|| -> () { + let tmp = t!(TempDir::new("test_rm_tempdir")); + tx.send(tmp.path().to_path_buf()).unwrap(); + panic!("panic to unwind past `tmp`"); + }; + let _ = thread::spawn(f).join(); + let path = rx.recv().unwrap(); + assert!(!path.exists()); + + let tmp = t!(TempDir::new("test_rm_tempdir")); + let path = tmp.path().to_path_buf(); + let f = move|| -> () { + let _tmp = tmp; + panic!("panic to unwind past `tmp`"); + }; + let _ = thread::spawn(f).join(); + assert!(!path.exists()); + + let path; + { + let f = move || { + t!(TempDir::new("test_rm_tempdir")) + }; + + let tmp = thread::spawn(f).join().unwrap(); + path = tmp.path().to_path_buf(); + assert!(path.exists()); + } + assert!(!path.exists()); + + let path; + { + let tmp = t!(TempDir::new("test_rm_tempdir")); + path = tmp.into_path(); + } + assert!(path.exists()); + t!(fs::remove_dir_all(&path)); + assert!(!path.exists()); +} + +fn test_rm_tempdir_close() { + let (tx, rx) = channel(); + let f = move|| -> () { + let tmp = t!(TempDir::new("test_rm_tempdir")); + tx.send(tmp.path().to_path_buf()).unwrap(); + t!(tmp.close()); + panic!("panic when unwinding past `tmp`"); + }; + let _ = thread::spawn(f).join(); + let path = rx.recv().unwrap(); + assert!(!path.exists()); + + let tmp = t!(TempDir::new("test_rm_tempdir")); + let path = tmp.path().to_path_buf(); + let f = move|| -> () { + let tmp = tmp; + t!(tmp.close()); + panic!("panic when unwinding past `tmp`"); + }; + let _ = thread::spawn(f).join(); + assert!(!path.exists()); + + let path; + { + let f = move || { + t!(TempDir::new("test_rm_tempdir")) + }; + + let tmp = thread::spawn(f).join().unwrap(); + path = tmp.path().to_path_buf(); + assert!(path.exists()); + t!(tmp.close()); + } + assert!(!path.exists()); + + let path; + { + let tmp = t!(TempDir::new("test_rm_tempdir")); + path = tmp.into_path(); + } + assert!(path.exists()); + t!(fs::remove_dir_all(&path)); + assert!(!path.exists()); +} + +// Ideally these would be in std::os but then core would need +// to depend on std +fn recursive_mkdir_rel() { + let path = Path::new("frob"); + let cwd = env::current_dir().unwrap(); + println!("recursive_mkdir_rel: Making: {} in cwd {} [{}]", path.display(), + cwd.display(), path.exists()); + t!(fs::create_dir(&path)); + assert!(path.is_dir()); + t!(fs::create_dir_all(&path)); + assert!(path.is_dir()); +} + +fn recursive_mkdir_dot() { + let dot = Path::new("."); + t!(fs::create_dir_all(&dot)); + let dotdot = Path::new(".."); + t!(fs::create_dir_all(&dotdot)); +} + +fn recursive_mkdir_rel_2() { + let path = Path::new("./frob/baz"); + let cwd = env::current_dir().unwrap(); + println!("recursive_mkdir_rel_2: Making: {} in cwd {} [{}]", path.display(), + cwd.display(), path.exists()); + t!(fs::create_dir_all(&path)); + assert!(path.is_dir()); + assert!(path.parent().unwrap().is_dir()); + let path2 = Path::new("quux/blat"); + println!("recursive_mkdir_rel_2: Making: {} in cwd {}", path2.display(), + cwd.display()); + t!(fs::create_dir("quux")); + t!(fs::create_dir_all(&path2)); + assert!(path2.is_dir()); + assert!(path2.parent().unwrap().is_dir()); +} + +// Ideally this would be in core, but needs TempFile +pub fn test_remove_dir_all_ok() { + let tmpdir = t!(TempDir::new("test")); + let tmpdir = tmpdir.path(); + let root = tmpdir.join("foo"); + + println!("making {}", root.display()); + t!(fs::create_dir(&root)); + t!(fs::create_dir(&root.join("foo"))); + t!(fs::create_dir(&root.join("foo").join("bar"))); + t!(fs::create_dir(&root.join("foo").join("bar").join("blat"))); + t!(fs::remove_dir_all(&root)); + assert!(!root.exists()); + assert!(!root.join("bar").exists()); + assert!(!root.join("bar").join("blat").exists()); +} + +pub fn dont_double_panic() { + let r: Result<(), _> = thread::spawn(move|| { + let tmpdir = TempDir::new("test").unwrap(); + // Remove the temporary directory so that TempDir sees + // an error on drop + t!(fs::remove_dir(tmpdir.path())); + // Panic. If TempDir panics *again* due to the rmdir + // error then the process will abort. + panic!(); + }).join(); + assert!(r.is_err()); +} + +fn in_tmpdir(f: F) where F: FnOnce() { + let tmpdir = t!(TempDir::new("test")); + assert!(env::set_current_dir(tmpdir.path()).is_ok()); + + f(); +} + +pub fn pass_as_asref_path() { + let tempdir = t!(TempDir::new("test")); + takes_asref_path(&tempdir); + + fn takes_asref_path>(path: T) { + let path = path.as_ref(); + assert!(path.exists()); + } +} + +#[test] +fn main() { + in_tmpdir(test_tempdir); + in_tmpdir(test_rm_tempdir); + in_tmpdir(test_rm_tempdir_close); + in_tmpdir(recursive_mkdir_rel); + in_tmpdir(recursive_mkdir_dot); + in_tmpdir(recursive_mkdir_rel_2); + in_tmpdir(test_remove_dir_all_ok); + in_tmpdir(dont_double_panic); + in_tmpdir(pass_as_asref_path); +}