use std::env; use std::error; use std::ffi::OsStr; use std::fmt; use std::fs::{self, File, OpenOptions}; use std::io::{self, Read, Seek, SeekFrom, Write}; use std::mem; use std::ops::Deref; use std::path::{Path, PathBuf}; use crate::error::IoResultExt; use crate::Builder; mod imp; /// 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 /// /// ``` /// 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 /// /// ``` /// 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()) } /// Error returned when persisting a temporary file path fails. #[derive(Debug)] pub struct PathPersistError { /// The underlying IO error. pub error: io::Error, /// The temporary file path that couldn't be persisted. pub path: TempPath, } impl From for io::Error { #[inline] fn from(error: PathPersistError) -> io::Error { error.error } } impl From for TempPath { #[inline] fn from(error: PathPersistError) -> TempPath { error.path } } impl fmt::Display for PathPersistError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "failed to persist temporary file path: {}", self.error) } } impl error::Error for PathPersistError { fn source(&self) -> Option<&(dyn error::Error + 'static)> { Some(&self.error) } } /// A path to a named temporary file without an open file handle. /// /// This is useful when the temporary file needs to be used by a child process, /// for example. /// /// When dropped, the temporary file is deleted. pub struct TempPath { path: Box, } impl TempPath { /// 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 /// # 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()?; /// /// // Close the file, but keep the path to it around. /// let path = file.into_temp_path(); /// /// // By closing the `TempPath` 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. /// path.close()?; /// # Ok(()) /// # } /// ``` pub fn close(mut self) -> io::Result<()> { let result = fs::remove_file(&self.path).with_err_path(|| &*self.path); self.path = PathBuf::new().into_boxed_path(); mem::forget(self); result } /// 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 /// [`PathPersistError`]. /// /// Note: Temporary files cannot be persisted across filesystems. Also /// neither the file contents nor the containing directory are /// synchronized, so the update may not yet have reached the disk when /// `persist` returns. /// /// # 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}; /// use tempfile::NamedTempFile; /// /// # fn main() { /// # if let Err(_) = run() { /// # ::std::process::exit(1); /// # } /// # } /// # fn run() -> Result<(), io::Error> { /// let mut file = NamedTempFile::new()?; /// writeln!(file, "Brian was here. Briefly.")?; /// /// let path = file.into_temp_path(); /// path.persist("./saved_file.txt")?; /// # Ok(()) /// # } /// ``` /// /// [`PathPersistError`]: struct.PathPersistError.html pub fn persist>(mut self, new_path: P) -> Result<(), PathPersistError> { match imp::persist(&self.path, new_path.as_ref(), true) { Ok(_) => { // Don't drop `self`. We don't want to try deleting the old // temporary file path. (It'll fail, but the failure is never // seen.) self.path = PathBuf::new().into_boxed_path(); mem::forget(self); Ok(()) } Err(e) => Err(PathPersistError { error: e, path: self, }), } } /// Persist the temporary file at the target path if and only if no file exists there. /// /// If a file exists at the target path, fail. If this method fails, it will /// return `self` in the resulting [`PathPersistError`]. /// /// 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}; /// use tempfile::NamedTempFile; /// /// # fn main() { /// # if let Err(_) = run() { /// # ::std::process::exit(1); /// # } /// # } /// # fn run() -> Result<(), io::Error> { /// let mut file = NamedTempFile::new()?; /// writeln!(file, "Brian was here. Briefly.")?; /// /// let path = file.into_temp_path(); /// path.persist_noclobber("./saved_file.txt")?; /// # Ok(()) /// # } /// ``` /// /// [`PathPersistError`]: struct.PathPersistError.html pub fn persist_noclobber>( mut self, new_path: P, ) -> Result<(), PathPersistError> { match imp::persist(&self.path, new_path.as_ref(), false) { Ok(_) => { // Don't drop `self`. We don't want to try deleting the old // temporary file path. (It'll fail, but the failure is never // seen.) self.path = PathBuf::new().into_boxed_path(); mem::forget(self); Ok(()) } Err(e) => Err(PathPersistError { error: e, path: self, }), } } /// Keep the temporary file from being deleted. This function will turn the /// temporary file into a non-temporary file without moving it. /// /// /// # Errors /// /// On some platforms (e.g., Windows), we need to mark the file as /// non-temporary. This operation could fail. /// /// # Examples /// /// ```no_run /// # use std::io::{self, Write}; /// use tempfile::NamedTempFile; /// /// # fn main() { /// # if let Err(_) = run() { /// # ::std::process::exit(1); /// # } /// # } /// # fn run() -> Result<(), io::Error> { /// let mut file = NamedTempFile::new()?; /// writeln!(file, "Brian was here. Briefly.")?; /// /// let path = file.into_temp_path(); /// let path = path.keep()?; /// # Ok(()) /// # } /// ``` /// /// [`PathPersistError`]: struct.PathPersistError.html pub fn keep(mut self) -> Result { match imp::keep(&self.path) { Ok(_) => { // Don't drop `self`. We don't want to try deleting the old // temporary file path. (It'll fail, but the failure is never // seen.) let path = mem::replace(&mut self.path, PathBuf::new().into_boxed_path()); mem::forget(self); Ok(path.into()) } Err(e) => Err(PathPersistError { error: e, path: self, }), } } /// Create a new TempPath from an existing path. This can be done even if no /// file exists at the given path. /// /// This is mostly useful for interacting with libraries and external /// components that provide files to be consumed or expect a path with no /// existing file to be given. pub fn from_path(path: impl Into) -> Self { Self { path: path.into().into_boxed_path(), } } } impl fmt::Debug for TempPath { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { self.path.fmt(f) } } impl Drop for TempPath { fn drop(&mut self) { let _ = fs::remove_file(&self.path); } } impl Deref for TempPath { type Target = Path; fn deref(&self) -> &Path { &self.path } } impl AsRef for TempPath { fn as_ref(&self) -> &Path { &self.path } } impl AsRef for TempPath { fn as_ref(&self) -> &OsStr { self.path.as_os_str() } } /// 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 /// /// Most operating systems employ temporary file cleaners to delete old /// temporary files. Unfortunately these temporary file cleaners don't always /// reliably _detect_ whether the temporary file is still being used. /// /// Specifically, the following sequence of events can happen: /// /// 1. A user creates a temporary file with `NamedTempFile::new()`. /// 2. Time passes. /// 3. The temporary file cleaner deletes (unlinks) the temporary file from the /// filesystem. /// 4. Some other program creates a new file to replace this deleted temporary /// file. /// 5. The user tries to re-open the temporary file (in the same program or in a /// different program) by path. Unfortunately, they'll end up opening the /// file created by the other program, not the original file. /// /// ## Operating System Specific Concerns /// /// The behavior of temporary files and temporary file cleaners differ by /// operating system. /// /// ### Windows /// /// On Windows, open files _can't_ be deleted. This removes most of the concerns /// around temporary file cleaners. /// /// Furthermore, temporary files are, by default, created in per-user temporary /// file directories so only an application running as the same user would be /// able to interfere (which they could do anyways). However, an application /// running as the same user can still _accidentally_ re-create deleted /// temporary files if the number of random bytes in the temporary file name is /// too small. /// /// So, the only real concern on Windows is: /// /// 1. Opening a named temporary file in a world-writable directory. /// 2. Using the `into_temp_path()` and/or `into_parts()` APIs to close the file /// handle without deleting the underlying file. /// 3. Continuing to use the file by path. /// /// ### UNIX /// /// Unlike on Windows, UNIX (and UNIX like) systems allow open files to be /// "unlinked" (deleted). /// /// #### MacOS /// /// Like on Windows, temporary files are created in per-user temporary file /// directories by default so calling `NamedTempFile::new()` should be /// relatively safe. /// /// #### Linux /// /// Unfortunately, most _Linux_ distributions don't create per-user temporary /// file directories. Worse, systemd's tmpfiles daemon (a common temporary file /// cleaner) will happily remove open temporary files if they haven't been /// modified within the last 10 days. /// /// # 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 { path: TempPath, file: File, } impl fmt::Debug for NamedTempFile { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "NamedTempFile({:?})", self.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 source(&self) -> Option<&(dyn error::Error + 'static)> { Some(&self.error) } } impl NamedTempFile { /// Create a new named temporary file. /// /// See [`Builder`] for more configuration. /// /// # Security /// /// This will create a temporary file in the default temporary file /// directory (platform dependent). This has security implications on many /// platforms so please read the security section of this type's /// documentation. /// /// 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}; /// 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(()) /// # } /// ``` /// /// [`Builder`]: struct.Builder.html pub fn new() -> io::Result { Builder::new().tempfile() } /// Create a new named temporary file in the specified directory. /// /// See [`NamedTempFile::new()`] for details. /// /// [`NamedTempFile::new()`]: #method.new pub fn new_in>(dir: P) -> io::Result { Builder::new().tempfile_in(dir) } /// Get the temporary file's path. /// /// # Security /// /// Referring to a temporary file's path may not be secure in all cases. /// Please read the security section on the top level documentation of this /// type for details. /// /// # Examples /// /// ```no_run /// # use std::io::{self, Write}; /// 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.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 /// # 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(self) -> io::Result<()> { let NamedTempFile { path, .. } = self; path.close() } /// 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. Also /// neither the file contents nor the containing directory are /// synchronized, so the update may not yet have reached the disk when /// `persist` returns. /// /// # Security /// /// This method persists the temporary file using its path and may not be /// secure in the in all cases. Please read the security section on the top /// level documentation of this type for details. /// /// # Errors /// /// If the file cannot be moved to the new location, `Err` is returned. /// /// # Examples /// /// ```no_run /// # use std::io::{self, Write}; /// 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>(self, new_path: P) -> Result { let NamedTempFile { path, file } = self; match path.persist(new_path) { Ok(_) => Ok(file), Err(err) => { let PathPersistError { error, path } = err; Err(PersistError { file: NamedTempFile { path, file }, error, }) } } } /// Persist the temporary file at the target path if and only if 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 /// /// This method persists the temporary file using its path and may not be /// secure in the in all cases. Please read the security section on the top /// level documentation of this type for details. /// /// # 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}; /// 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>(self, new_path: P) -> Result { let NamedTempFile { path, file } = self; match path.persist_noclobber(new_path) { Ok(_) => Ok(file), Err(err) => { let PathPersistError { error, path } = err; Err(PersistError { file: NamedTempFile { path, file }, error, }) } } } /// Keep the temporary file from being deleted. This function will turn the /// temporary file into a non-temporary file without moving it. /// /// /// # Errors /// /// On some platforms (e.g., Windows), we need to mark the file as /// non-temporary. This operation could fail. /// /// # Examples /// /// ```no_run /// # use std::io::{self, Write}; /// use tempfile::NamedTempFile; /// /// # fn main() { /// # if let Err(_) = run() { /// # ::std::process::exit(1); /// # } /// # } /// # fn run() -> Result<(), io::Error> { /// let mut file = NamedTempFile::new()?; /// writeln!(file, "Brian was here. Briefly.")?; /// /// let (file, path) = file.keep()?; /// # Ok(()) /// # } /// ``` /// /// [`PathPersistError`]: struct.PathPersistError.html pub fn keep(self) -> Result<(File, PathBuf), PersistError> { let (file, path) = (self.file, self.path); match path.keep() { Ok(path) => Ok((file, path)), Err(PathPersistError { error, path }) => Err(PersistError { file: NamedTempFile { path, file }, error, }), } } /// Securely 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. /// /// # Security /// /// Unlike `File::open(my_temp_file.path())`, `NamedTempFile::reopen()` /// guarantees that the re-opened file is the _same_ file, even in the /// presence of pathological temporary file cleaners. /// /// # Examples /// /// ```no_run /// # 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()?; /// /// let another_handle = file.reopen()?; /// # Ok(()) /// # } /// ``` pub fn reopen(&self) -> io::Result { imp::reopen(self.as_file(), NamedTempFile::path(self)) .with_err_path(|| NamedTempFile::path(self)) } /// Get a reference to the underlying file. pub fn as_file(&self) -> &File { &self.file } /// Get a mutable reference to the underlying file. pub fn as_file_mut(&mut self) -> &mut File { &mut self.file } /// Convert the temporary file into a `std::fs::File`. /// /// The inner file will be deleted. pub fn into_file(self) -> File { self.file } /// Closes the file, leaving only the temporary file path. /// /// This is useful when another process must be able to open the temporary /// file. pub fn into_temp_path(self) -> TempPath { self.path } /// Converts the named temporary file into its constituent parts. /// /// Note: When the path is dropped, the file is deleted but the file handle /// is still usable. pub fn into_parts(self) -> (File, TempPath) { (self.file, self.path) } } impl Read for NamedTempFile { fn read(&mut self, buf: &mut [u8]) -> io::Result { self.as_file_mut().read(buf).with_err_path(|| self.path()) } } impl<'a> Read for &'a NamedTempFile { fn read(&mut self, buf: &mut [u8]) -> io::Result { self.as_file().read(buf).with_err_path(|| self.path()) } } impl Write for NamedTempFile { fn write(&mut self, buf: &[u8]) -> io::Result { self.as_file_mut().write(buf).with_err_path(|| self.path()) } #[inline] fn flush(&mut self) -> io::Result<()> { self.as_file_mut().flush().with_err_path(|| self.path()) } } impl<'a> Write for &'a NamedTempFile { fn write(&mut self, buf: &[u8]) -> io::Result { self.as_file().write(buf).with_err_path(|| self.path()) } #[inline] fn flush(&mut self) -> io::Result<()> { self.as_file().flush().with_err_path(|| self.path()) } } impl Seek for NamedTempFile { fn seek(&mut self, pos: SeekFrom) -> io::Result { self.as_file_mut().seek(pos).with_err_path(|| self.path()) } } impl<'a> Seek for &'a NamedTempFile { fn seek(&mut self, pos: SeekFrom) -> io::Result { self.as_file().seek(pos).with_err_path(|| self.path()) } } #[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() } } pub(crate) fn create_named( mut path: PathBuf, open_options: &mut OpenOptions, ) -> io::Result { // Make the path absolute. Otherwise, changing directories could cause us to // delete the wrong file. if !path.is_absolute() { path = env::current_dir()?.join(path) } imp::create_named(&path, open_options) .with_err_path(|| path.clone()) .map(|file| NamedTempFile { path: TempPath { path: path.into_boxed_path(), }, file, }) }