vendor/tempfile/src/file/mod.rs

   1 use std::env;
   2 use std::error;
   3 use std::ffi::OsStr;
   4 use std::fmt;
   5 use std::fs::{self, File, OpenOptions};
   6 use std::io::{self, Read, Seek, SeekFrom, Write};
   7 use std::mem;
   8 use std::ops::Deref;
   9 use std::path::{Path, PathBuf};
  10
  11 use crate::error::IoResultExt;
  12 use crate::Builder;
  13
  14 mod imp;
  15
  16 /// Create a new temporary file.
  17 ///
  18 /// The file will be created in the location returned by [`std::env::temp_dir()`].
  19 ///
  20 /// # Security
  21 ///
  22 /// This variant is secure/reliable in the presence of a pathological temporary file cleaner.
  23 ///
  24 /// # Resource Leaking
  25 ///
  26 /// The temporary file will be automatically removed by the OS when the last handle to it is closed.
  27 /// This doesn't rely on Rust destructors being run, so will (almost) never fail to clean up the temporary file.
  28 ///
  29 /// # Errors
  30 ///
  31 /// If the file can not be created, `Err` is returned.
  32 ///
  33 /// # Examples
  34 ///
  35 /// ```
  36 /// use tempfile::tempfile;
  37 /// use std::io::{self, Write};
  38 ///
  39 /// # fn main() {
  40 /// #     if let Err(_) = run() {
  41 /// #         ::std::process::exit(1);
  42 /// #     }
  43 /// # }
  44 /// # fn run() -> Result<(), io::Error> {
  45 /// // Create a file inside of `std::env::temp_dir()`.
  46 /// let mut file = tempfile()?;
  47 ///
  48 /// writeln!(file, "Brian was here. Briefly.")?;
  49 /// # Ok(())
  50 /// # }
  51 /// ```
  52 ///
  53 /// [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html
  54 pub fn tempfile() -> io::Result<File> {
  55     tempfile_in(&env::temp_dir())
  56 }
  57
  58 /// Create a new temporary file in the specified directory.
  59 ///
  60 /// # Security
  61 ///
  62 /// This variant is secure/reliable in the presence of a pathological temporary file cleaner.
  63 /// If the temporary file isn't created in [`std::env::temp_dir()`] then temporary file cleaners aren't an issue.
  64 ///
  65 /// # Resource Leaking
  66 ///
  67 /// The temporary file will be automatically removed by the OS when the last handle to it is closed.
  68 /// This doesn't rely on Rust destructors being run, so will (almost) never fail to clean up the temporary file.
  69 ///
  70 /// # Errors
  71 ///
  72 /// If the file can not be created, `Err` is returned.
  73 ///
  74 /// # Examples
  75 ///
  76 /// ```
  77 /// use tempfile::tempfile_in;
  78 /// use std::io::{self, Write};
  79 ///
  80 /// # fn main() {
  81 /// #     if let Err(_) = run() {
  82 /// #         ::std::process::exit(1);
  83 /// #     }
  84 /// # }
  85 /// # fn run() -> Result<(), io::Error> {
  86 /// // Create a file inside of the current working directory
  87 /// let mut file = tempfile_in("./")?;
  88 ///
  89 /// writeln!(file, "Brian was here. Briefly.")?;
  90 /// # Ok(())
  91 /// # }
  92 /// ```
  93 ///
  94 /// [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html
  95 pub fn tempfile_in<P: AsRef<Path>>(dir: P) -> io::Result<File> {
  96     imp::create(dir.as_ref())
  97 }
  98
  99 /// Error returned when persisting a temporary file path fails.
 100 #[derive(Debug)]
 101 pub struct PathPersistError {
 102     /// The underlying IO error.
 103     pub error: io::Error,
 104     /// The temporary file path that couldn't be persisted.
 105     pub path: TempPath,
 106 }
 107
 108 impl From<PathPersistError> for io::Error {
 109     #[inline]
 110     fn from(error: PathPersistError) -> io::Error {
 111         error.error
 112     }
 113 }
 114
 115 impl From<PathPersistError> for TempPath {
 116     #[inline]
 117     fn from(error: PathPersistError) -> TempPath {
 118         error.path
 119     }
 120 }
 121
 122 impl fmt::Display for PathPersistError {
 123     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 124         write!(f, "failed to persist temporary file path: {}", self.error)
 125     }
 126 }
 127
 128 impl error::Error for PathPersistError {
 129     fn source(&self) -> Option<&(dyn error::Error + 'static)> {
 130         Some(&self.error)
 131     }
 132 }
 133
 134 /// A path to a named temporary file without an open file handle.
 135 ///
 136 /// This is useful when the temporary file needs to be used by a child process,
 137 /// for example.
 138 ///
 139 /// When dropped, the temporary file is deleted.
 140 pub struct TempPath {
 141     path: PathBuf,
 142 }
 143
 144 impl TempPath {
 145     /// Close and remove the temporary file.
 146     ///
 147     /// Use this if you want to detect errors in deleting the file.
 148     ///
 149     /// # Errors
 150     ///
 151     /// If the file cannot be deleted, `Err` is returned.
 152     ///
 153     /// # Examples
 154     ///
 155     /// ```no_run
 156     /// # use std::io;
 157     /// use tempfile::NamedTempFile;
 158     ///
 159     /// # fn main() {
 160     /// #     if let Err(_) = run() {
 161     /// #         ::std::process::exit(1);
 162     /// #     }
 163     /// # }
 164     /// # fn run() -> Result<(), io::Error> {
 165     /// let file = NamedTempFile::new()?;
 166     ///
 167     /// // Close the file, but keep the path to it around.
 168     /// let path = file.into_temp_path();
 169     ///
 170     /// // By closing the `TempPath` explicitly, we can check that it has
 171     /// // been deleted successfully. If we don't close it explicitly, the
 172     /// // file will still be deleted when `file` goes out of scope, but we
 173     /// // won't know whether deleting the file succeeded.
 174     /// path.close()?;
 175     /// # Ok(())
 176     /// # }
 177     /// ```
 178     pub fn close(mut self) -> io::Result<()> {
 179         let result = fs::remove_file(&self.path).with_err_path(|| &self.path);
 180         self.path = PathBuf::new();
 181         mem::forget(self);
 182         result
 183     }
 184
 185     /// Persist the temporary file at the target path.
 186     ///
 187     /// If a file exists at the target path, persist will atomically replace it.
 188     /// If this method fails, it will return `self` in the resulting
 189     /// [`PathPersistError`].
 190     ///
 191     /// Note: Temporary files cannot be persisted across filesystems. Also
 192     /// neither the file contents nor the containing directory are
 193     /// synchronized, so the update may not yet have reached the disk when
 194     /// `persist` returns.
 195     ///
 196     /// # Security
 197     ///
 198     /// Only use this method if you're positive that a temporary file cleaner
 199     /// won't have deleted your file. Otherwise, you might end up persisting an
 200     /// attacker controlled file.
 201     ///
 202     /// # Errors
 203     ///
 204     /// If the file cannot be moved to the new location, `Err` is returned.
 205     ///
 206     /// # Examples
 207     ///
 208     /// ```no_run
 209     /// # use std::io::{self, Write};
 210     /// use tempfile::NamedTempFile;
 211     ///
 212     /// # fn main() {
 213     /// #     if let Err(_) = run() {
 214     /// #         ::std::process::exit(1);
 215     /// #     }
 216     /// # }
 217     /// # fn run() -> Result<(), io::Error> {
 218     /// let mut file = NamedTempFile::new()?;
 219     /// writeln!(file, "Brian was here. Briefly.")?;
 220     ///
 221     /// let path = file.into_temp_path();
 222     /// path.persist("./saved_file.txt")?;
 223     /// # Ok(())
 224     /// # }
 225     /// ```
 226     ///
 227     /// [`PathPersistError`]: struct.PathPersistError.html
 228     pub fn persist<P: AsRef<Path>>(mut self, new_path: P) -> Result<(), PathPersistError> {
 229         match imp::persist(&self.path, new_path.as_ref(), true) {
 230             Ok(_) => {
 231                 // Don't drop `self`. We don't want to try deleting the old
 232                 // temporary file path. (It'll fail, but the failure is never
 233                 // seen.)
 234                 self.path = PathBuf::new();
 235                 mem::forget(self);
 236                 Ok(())
 237             }
 238             Err(e) => Err(PathPersistError {
 239                 error: e,
 240                 path: self,
 241             }),
 242         }
 243     }
 244
 245     /// Persist the temporary file at the target path if and only if no file exists there.
 246     ///
 247     /// If a file exists at the target path, fail. If this method fails, it will
 248     /// return `self` in the resulting [`PathPersistError`].
 249     ///
 250     /// Note: Temporary files cannot be persisted across filesystems. Also Note:
 251     /// This method is not atomic. It can leave the original link to the
 252     /// temporary file behind.
 253     ///
 254     /// # Security
 255     ///
 256     /// Only use this method if you're positive that a temporary file cleaner
 257     /// won't have deleted your file. Otherwise, you might end up persisting an
 258     /// attacker controlled file.
 259     ///
 260     /// # Errors
 261     ///
 262     /// If the file cannot be moved to the new location or a file already exists
 263     /// there, `Err` is returned.
 264     ///
 265     /// # Examples
 266     ///
 267     /// ```no_run
 268     /// # use std::io::{self, Write};
 269     /// use tempfile::NamedTempFile;
 270     ///
 271     /// # fn main() {
 272     /// #     if let Err(_) = run() {
 273     /// #         ::std::process::exit(1);
 274     /// #     }
 275     /// # }
 276     /// # fn run() -> Result<(), io::Error> {
 277     /// let mut file = NamedTempFile::new()?;
 278     /// writeln!(file, "Brian was here. Briefly.")?;
 279     ///
 280     /// let path = file.into_temp_path();
 281     /// path.persist_noclobber("./saved_file.txt")?;
 282     /// # Ok(())
 283     /// # }
 284     /// ```
 285     ///
 286     /// [`PathPersistError`]: struct.PathPersistError.html
 287     pub fn persist_noclobber<P: AsRef<Path>>(
 288         mut self,
 289         new_path: P,
 290     ) -> Result<(), PathPersistError> {
 291         match imp::persist(&self.path, new_path.as_ref(), false) {
 292             Ok(_) => {
 293                 // Don't drop `self`. We don't want to try deleting the old
 294                 // temporary file path. (It'll fail, but the failure is never
 295                 // seen.)
 296                 self.path = PathBuf::new();
 297                 mem::forget(self);
 298                 Ok(())
 299             }
 300             Err(e) => Err(PathPersistError {
 301                 error: e,
 302                 path: self,
 303             }),
 304         }
 305     }
 306
 307     /// Keep the temporary file from being deleted. This function will turn the
 308     /// temporary file into a non-temporary file without moving it.
 309     ///
 310     ///
 311     /// # Errors
 312     ///
 313     /// On some platforms (e.g., Windows), we need to mark the file as
 314     /// non-temporary. This operation could fail.
 315     ///
 316     /// # Examples
 317     ///
 318     /// ```no_run
 319     /// # use std::io::{self, Write};
 320     /// use tempfile::NamedTempFile;
 321     ///
 322     /// # fn main() {
 323     /// #     if let Err(_) = run() {
 324     /// #         ::std::process::exit(1);
 325     /// #     }
 326     /// # }
 327     /// # fn run() -> Result<(), io::Error> {
 328     /// let mut file = NamedTempFile::new()?;
 329     /// writeln!(file, "Brian was here. Briefly.")?;
 330     ///
 331     /// let path = file.into_temp_path();
 332     /// let path = path.keep()?;
 333     /// # Ok(())
 334     /// # }
 335     /// ```
 336     ///
 337     /// [`PathPersistError`]: struct.PathPersistError.html
 338     pub fn keep(mut self) -> Result<PathBuf, PathPersistError> {
 339         match imp::keep(&self.path) {
 340             Ok(_) => {
 341                 // Don't drop `self`. We don't want to try deleting the old
 342                 // temporary file path. (It'll fail, but the failure is never
 343                 // seen.)
 344                 let path = mem::replace(&mut self.path, PathBuf::new());
 345                 mem::forget(self);
 346                 Ok(path)
 347             }
 348             Err(e) => Err(PathPersistError {
 349                 error: e,
 350                 path: self,
 351             }),
 352         }
 353     }
 354 }
 355
 356 impl fmt::Debug for TempPath {
 357     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 358         self.path.fmt(f)
 359     }
 360 }
 361
 362 impl Drop for TempPath {
 363     fn drop(&mut self) {
 364         let _ = fs::remove_file(&self.path);
 365     }
 366 }
 367
 368 impl Deref for TempPath {
 369     type Target = Path;
 370
 371     fn deref(&self) -> &Path {
 372         &self.path
 373     }
 374 }
 375
 376 impl AsRef<Path> for TempPath {
 377     fn as_ref(&self) -> &Path {
 378         &self.path
 379     }
 380 }
 381
 382 impl AsRef<OsStr> for TempPath {
 383     fn as_ref(&self) -> &OsStr {
 384         self.path.as_os_str()
 385     }
 386 }
 387
 388 /// A named temporary file.
 389 ///
 390 /// The default constructor, [`NamedTempFile::new()`], creates files in
 391 /// the location returned by [`std::env::temp_dir()`], but `NamedTempFile`
 392 /// can be configured to manage a temporary file in any location
 393 /// by constructing with [`NamedTempFile::new_in()`].
 394 ///
 395 /// # Security
 396 ///
 397 /// Most operating systems employ temporary file cleaners to delete old
 398 /// temporary files. Unfortunately these temporary file cleaners don't always
 399 /// reliably _detect_ whether the temporary file is still being used.
 400 ///
 401 /// Specifically, the following sequence of events can happen:
 402 ///
 403 /// 1. A user creates a temporary file with `NamedTempFile::new()`.
 404 /// 2. Time passes.
 405 /// 3. The temporary file cleaner deletes (unlinks) the temporary file from the
 406 ///    filesystem.
 407 /// 4. Some other program creates a new file to replace this deleted temporary
 408 ///    file.
 409 /// 5. The user tries to re-open the temporary file (in the same program or in a
 410 ///    different program) by path. Unfortunately, they'll end up opening the
 411 ///    file created by the other program, not the original file.
 412 ///
 413 /// ## Operating System Specific Concerns
 414 ///
 415 /// The behavior of temporary files and temporary file cleaners differ by
 416 /// operating system.
 417 ///
 418 /// ### Windows
 419 ///
 420 /// On Windows, open files _can't_ be deleted. This removes most of the concerns
 421 /// around temporary file cleaners.
 422 ///
 423 /// Furthermore, temporary files are, by default, created in per-user temporary
 424 /// file directories so only an application running as the same user would be
 425 /// able to interfere (which they could do anyways). However, an application
 426 /// running as the same user can still _accidentally_ re-create deleted
 427 /// temporary files if the number of random bytes in the temporary file name is
 428 /// too small.
 429 ///
 430 /// So, the only real concern on Windows is:
 431 ///
 432 /// 1. Opening a named temporary file in a world-writable directory.
 433 /// 2. Using the `into_temp_path()` and/or `into_parts()` APIs to close the file
 434 ///    handle without deleting the underlying file.
 435 /// 3. Continuing to use the file by path.
 436 ///
 437 /// ### UNIX
 438 ///
 439 /// Unlike on Windows, UNIX (and UNIX like) systems allow open files to be
 440 /// "unlinked" (deleted).
 441 ///
 442 /// #### MacOS
 443 ///
 444 /// Like on Windows, temporary files are created in per-user temporary file
 445 /// directories by default so calling `NamedTempFile::new()` should be
 446 /// relatively safe.
 447 ///
 448 /// #### Linux
 449 ///
 450 /// Unfortunately, most _Linux_ distributions don't create per-user temporary
 451 /// file directories. Worse, systemd's tmpfiles daemon (a common temporary file
 452 /// cleaner) will happily remove open temporary files if they haven't been
 453 /// modified within the last 10 days.
 454 ///
 455 /// # Resource Leaking
 456 ///
 457 /// If the program exits before the `NamedTempFile` destructor is
 458 /// run, such as via [`std::process::exit()`], by segfaulting, or by
 459 /// receiving a signal like `SIGINT`, then the temporary file
 460 /// will not be deleted.
 461 ///
 462 /// Use the [`tempfile()`] function unless you absolutely need a named file.
 463 ///
 464 /// [`tempfile()`]: fn.tempfile.html
 465 /// [`NamedTempFile::new()`]: #method.new
 466 /// [`NamedTempFile::new_in()`]: #method.new_in
 467 /// [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html
 468 /// [`std::process::exit()`]: http://doc.rust-lang.org/std/process/fn.exit.html
 469 pub struct NamedTempFile {
 470     path: TempPath,
 471     file: File,
 472 }
 473
 474 impl fmt::Debug for NamedTempFile {
 475     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 476         write!(f, "NamedTempFile({:?})", self.path)
 477     }
 478 }
 479
 480 impl AsRef<Path> for NamedTempFile {
 481     #[inline]
 482     fn as_ref(&self) -> &Path {
 483         self.path()
 484     }
 485 }
 486
 487 /// Error returned when persisting a temporary file fails.
 488 #[derive(Debug)]
 489 pub struct PersistError {
 490     /// The underlying IO error.
 491     pub error: io::Error,
 492     /// The temporary file that couldn't be persisted.
 493     pub file: NamedTempFile,
 494 }
 495
 496 impl From<PersistError> for io::Error {
 497     #[inline]
 498     fn from(error: PersistError) -> io::Error {
 499         error.error
 500     }
 501 }
 502
 503 impl From<PersistError> for NamedTempFile {
 504     #[inline]
 505     fn from(error: PersistError) -> NamedTempFile {
 506         error.file
 507     }
 508 }
 509
 510 impl fmt::Display for PersistError {
 511     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 512         write!(f, "failed to persist temporary file: {}", self.error)
 513     }
 514 }
 515
 516 impl error::Error for PersistError {
 517     fn source(&self) -> Option<&(dyn error::Error + 'static)> {
 518         Some(&self.error)
 519     }
 520 }
 521
 522 impl NamedTempFile {
 523     /// Create a new named temporary file.
 524     ///
 525     /// See [`Builder`] for more configuration.
 526     ///
 527     /// # Security
 528     ///
 529     /// This will create a temporary file in the default temporary file
 530     /// directory (platform dependent). This has security implications on many
 531     /// platforms so please read the security section of this type's
 532     /// documentation.
 533     ///
 534     /// Reasons to use this method:
 535     ///
 536     ///   1. The file has a short lifetime and your temporary file cleaner is
 537     ///      sane (doesn't delete recently accessed files).
 538     ///
 539     ///   2. You trust every user on your system (i.e. you are the only user).
 540     ///
 541     ///   3. You have disabled your system's temporary file cleaner or verified
 542     ///      that your system doesn't have a temporary file cleaner.
 543     ///
 544     /// Reasons not to use this method:
 545     ///
 546     ///   1. You'll fix it later. No you won't.
 547     ///
 548     ///   2. You don't care about the security of the temporary file. If none of
 549     ///      the "reasons to use this method" apply, referring to a temporary
 550     ///      file by name may allow an attacker to create/overwrite your
 551     ///      non-temporary files. There are exceptions but if you don't already
 552     ///      know them, don't use this method.
 553     ///
 554     /// # Errors
 555     ///
 556     /// If the file can not be created, `Err` is returned.
 557     ///
 558     /// # Examples
 559     ///
 560     /// Create a named temporary file and write some data to it:
 561     ///
 562     /// ```no_run
 563     /// # use std::io::{self, Write};
 564     /// use tempfile::NamedTempFile;
 565     ///
 566     /// # fn main() {
 567     /// #     if let Err(_) = run() {
 568     /// #         ::std::process::exit(1);
 569     /// #     }
 570     /// # }
 571     /// # fn run() -> Result<(), ::std::io::Error> {
 572     /// let mut file = NamedTempFile::new()?;
 573     ///
 574     /// writeln!(file, "Brian was here. Briefly.")?;
 575     /// # Ok(())
 576     /// # }
 577     /// ```
 578     ///
 579     /// [`Builder`]: struct.Builder.html
 580     pub fn new() -> io::Result<NamedTempFile> {
 581         Builder::new().tempfile()
 582     }
 583
 584     /// Create a new named temporary file in the specified directory.
 585     ///
 586     /// See [`NamedTempFile::new()`] for details.
 587     ///
 588     /// [`NamedTempFile::new()`]: #method.new
 589     pub fn new_in<P: AsRef<Path>>(dir: P) -> io::Result<NamedTempFile> {
 590         Builder::new().tempfile_in(dir)
 591     }
 592
 593     /// Get the temporary file's path.
 594     ///
 595     /// # Security
 596     ///
 597     /// Referring to a temporary file's path may not be secure in all cases.
 598     /// Please read the security section on the top level documentation of this
 599     /// type for details.
 600     ///
 601     /// # Examples
 602     ///
 603     /// ```no_run
 604     /// # use std::io::{self, Write};
 605     /// use tempfile::NamedTempFile;
 606     ///
 607     /// # fn main() {
 608     /// #     if let Err(_) = run() {
 609     /// #         ::std::process::exit(1);
 610     /// #     }
 611     /// # }
 612     /// # fn run() -> Result<(), ::std::io::Error> {
 613     /// let file = NamedTempFile::new()?;
 614     ///
 615     /// println!("{:?}", file.path());
 616     /// # Ok(())
 617     /// # }
 618     /// ```
 619     #[inline]
 620     pub fn path(&self) -> &Path {
 621         &self.path
 622     }
 623
 624     /// Close and remove the temporary file.
 625     ///
 626     /// Use this if you want to detect errors in deleting the file.
 627     ///
 628     /// # Errors
 629     ///
 630     /// If the file cannot be deleted, `Err` is returned.
 631     ///
 632     /// # Examples
 633     ///
 634     /// ```no_run
 635     /// # use std::io;
 636     /// use tempfile::NamedTempFile;
 637     ///
 638     /// # fn main() {
 639     /// #     if let Err(_) = run() {
 640     /// #         ::std::process::exit(1);
 641     /// #     }
 642     /// # }
 643     /// # fn run() -> Result<(), io::Error> {
 644     /// let file = NamedTempFile::new()?;
 645     ///
 646     /// // By closing the `NamedTempFile` explicitly, we can check that it has
 647     /// // been deleted successfully. If we don't close it explicitly,
 648     /// // the file will still be deleted when `file` goes out
 649     /// // of scope, but we won't know whether deleting the file
 650     /// // succeeded.
 651     /// file.close()?;
 652     /// # Ok(())
 653     /// # }
 654     /// ```
 655     pub fn close(self) -> io::Result<()> {
 656         let NamedTempFile { path, .. } = self;
 657         path.close()
 658     }
 659
 660     /// Persist the temporary file at the target path.
 661     ///
 662     /// If a file exists at the target path, persist will atomically replace it.
 663     /// If this method fails, it will return `self` in the resulting
 664     /// [`PersistError`].
 665     ///
 666     /// Note: Temporary files cannot be persisted across filesystems. Also
 667     /// neither the file contents nor the containing directory are
 668     /// synchronized, so the update may not yet have reached the disk when
 669     /// `persist` returns.
 670     ///
 671     /// # Security
 672     ///
 673     /// This method persists the temporary file using its path and may not be
 674     /// secure in the in all cases. Please read the security section on the top
 675     /// level documentation of this type for details.
 676     ///
 677     /// # Errors
 678     ///
 679     /// If the file cannot be moved to the new location, `Err` is returned.
 680     ///
 681     /// # Examples
 682     ///
 683     /// ```no_run
 684     /// # use std::io::{self, Write};
 685     /// use tempfile::NamedTempFile;
 686     ///
 687     /// # fn main() {
 688     /// #     if let Err(_) = run() {
 689     /// #         ::std::process::exit(1);
 690     /// #     }
 691     /// # }
 692     /// # fn run() -> Result<(), io::Error> {
 693     /// let file = NamedTempFile::new()?;
 694     ///
 695     /// let mut persisted_file = file.persist("./saved_file.txt")?;
 696     /// writeln!(persisted_file, "Brian was here. Briefly.")?;
 697     /// # Ok(())
 698     /// # }
 699     /// ```
 700     ///
 701     /// [`PersistError`]: struct.PersistError.html
 702     pub fn persist<P: AsRef<Path>>(self, new_path: P) -> Result<File, PersistError> {
 703         let NamedTempFile { path, file } = self;
 704         match path.persist(new_path) {
 705             Ok(_) => Ok(file),
 706             Err(err) => {
 707                 let PathPersistError { error, path } = err;
 708                 Err(PersistError {
 709                     file: NamedTempFile { path, file },
 710                     error,
 711                 })
 712             }
 713         }
 714     }
 715
 716     /// Persist the temporary file at the target path if and only if no file exists there.
 717     ///
 718     /// If a file exists at the target path, fail. If this method fails, it will
 719     /// return `self` in the resulting PersistError.
 720     ///
 721     /// Note: Temporary files cannot be persisted across filesystems. Also Note:
 722     /// This method is not atomic. It can leave the original link to the
 723     /// temporary file behind.
 724     ///
 725     /// # Security
 726     ///
 727     /// This method persists the temporary file using its path and may not be
 728     /// secure in the in all cases. Please read the security section on the top
 729     /// level documentation of this type for details.
 730     ///
 731     /// # Errors
 732     ///
 733     /// If the file cannot be moved to the new location or a file already exists there,
 734     /// `Err` is returned.
 735     ///
 736     /// # Examples
 737     ///
 738     /// ```no_run
 739     /// # use std::io::{self, Write};
 740     /// use tempfile::NamedTempFile;
 741     ///
 742     /// # fn main() {
 743     /// #     if let Err(_) = run() {
 744     /// #         ::std::process::exit(1);
 745     /// #     }
 746     /// # }
 747     /// # fn run() -> Result<(), io::Error> {
 748     /// let file = NamedTempFile::new()?;
 749     ///
 750     /// let mut persisted_file = file.persist_noclobber("./saved_file.txt")?;
 751     /// writeln!(persisted_file, "Brian was here. Briefly.")?;
 752     /// # Ok(())
 753     /// # }
 754     /// ```
 755     pub fn persist_noclobber<P: AsRef<Path>>(self, new_path: P) -> Result<File, PersistError> {
 756         let NamedTempFile { path, file } = self;
 757         match path.persist_noclobber(new_path) {
 758             Ok(_) => Ok(file),
 759             Err(err) => {
 760                 let PathPersistError { error, path } = err;
 761                 Err(PersistError {
 762                     file: NamedTempFile { path, file },
 763                     error,
 764                 })
 765             }
 766         }
 767     }
 768
 769     /// Keep the temporary file from being deleted. This function will turn the
 770     /// temporary file into a non-temporary file without moving it.
 771     ///
 772     ///
 773     /// # Errors
 774     ///
 775     /// On some platforms (e.g., Windows), we need to mark the file as
 776     /// non-temporary. This operation could fail.
 777     ///
 778     /// # Examples
 779     ///
 780     /// ```no_run
 781     /// # use std::io::{self, Write};
 782     /// use tempfile::NamedTempFile;
 783     ///
 784     /// # fn main() {
 785     /// #     if let Err(_) = run() {
 786     /// #         ::std::process::exit(1);
 787     /// #     }
 788     /// # }
 789     /// # fn run() -> Result<(), io::Error> {
 790     /// let mut file = NamedTempFile::new()?;
 791     /// writeln!(file, "Brian was here. Briefly.")?;
 792     ///
 793     /// let (file, path) = file.keep()?;
 794     /// # Ok(())
 795     /// # }
 796     /// ```
 797     ///
 798     /// [`PathPersistError`]: struct.PathPersistError.html
 799     pub fn keep(self) -> Result<(File, PathBuf), PersistError> {
 800         let (file, path) = (self.file, self.path);
 801         match path.keep() {
 802             Ok(path) => Ok((file, path)),
 803             Err(PathPersistError { error, path }) => Err(PersistError {
 804                 file: NamedTempFile { path, file },
 805                 error,
 806             }),
 807         }
 808     }
 809
 810     /// Securely reopen the temporary file.
 811     ///
 812     /// This function is useful when you need multiple independent handles to
 813     /// the same file. It's perfectly fine to drop the original `NamedTempFile`
 814     /// while holding on to `File`s returned by this function; the `File`s will
 815     /// remain usable. However, they may not be nameable.
 816     ///
 817     /// # Errors
 818     ///
 819     /// If the file cannot be reopened, `Err` is returned.
 820     ///
 821     /// # Security
 822     ///
 823     /// Unlike `File::open(my_temp_file.path())`, `NamedTempFile::reopen()`
 824     /// guarantees that the re-opened file is the _same_ file, even in the
 825     /// presence of pathological temporary file cleaners.
 826     ///
 827     /// # Examples
 828     ///
 829     /// ```no_run
 830     /// # use std::io;
 831     /// use tempfile::NamedTempFile;
 832     ///
 833     /// # fn main() {
 834     /// #     if let Err(_) = run() {
 835     /// #         ::std::process::exit(1);
 836     /// #     }
 837     /// # }
 838     /// # fn run() -> Result<(), io::Error> {
 839     /// let file = NamedTempFile::new()?;
 840     ///
 841     /// let another_handle = file.reopen()?;
 842     /// # Ok(())
 843     /// # }
 844     /// ```
 845     pub fn reopen(&self) -> io::Result<File> {
 846         imp::reopen(self.as_file(), NamedTempFile::path(self))
 847             .with_err_path(|| NamedTempFile::path(self))
 848     }
 849
 850     /// Get a reference to the underlying file.
 851     pub fn as_file(&self) -> &File {
 852         &self.file
 853     }
 854
 855     /// Get a mutable reference to the underlying file.
 856     pub fn as_file_mut(&mut self) -> &mut File {
 857         &mut self.file
 858     }
 859
 860     /// Convert the temporary file into a `std::fs::File`.
 861     ///
 862     /// The inner file will be deleted.
 863     pub fn into_file(self) -> File {
 864         self.file
 865     }
 866
 867     /// Closes the file, leaving only the temporary file path.
 868     ///
 869     /// This is useful when another process must be able to open the temporary
 870     /// file.
 871     pub fn into_temp_path(self) -> TempPath {
 872         self.path
 873     }
 874
 875     /// Converts the named temporary file into its constituent parts.
 876     ///
 877     /// Note: When the path is dropped, the file is deleted but the file handle
 878     /// is still usable.
 879     pub fn into_parts(self) -> (File, TempPath) {
 880         (self.file, self.path)
 881     }
 882 }
 883
 884 impl Read for NamedTempFile {
 885     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 886         self.as_file_mut().read(buf).with_err_path(|| self.path())
 887     }
 888 }
 889
 890 impl<'a> Read for &'a NamedTempFile {
 891     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 892         self.as_file().read(buf).with_err_path(|| self.path())
 893     }
 894 }
 895
 896 impl Write for NamedTempFile {
 897     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 898         self.as_file_mut().write(buf).with_err_path(|| self.path())
 899     }
 900     #[inline]
 901     fn flush(&mut self) -> io::Result<()> {
 902         self.as_file_mut().flush().with_err_path(|| self.path())
 903     }
 904 }
 905
 906 impl<'a> Write for &'a NamedTempFile {
 907     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 908         self.as_file().write(buf).with_err_path(|| self.path())
 909     }
 910     #[inline]
 911     fn flush(&mut self) -> io::Result<()> {
 912         self.as_file().flush().with_err_path(|| self.path())
 913     }
 914 }
 915
 916 impl Seek for NamedTempFile {
 917     fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
 918         self.as_file_mut().seek(pos).with_err_path(|| self.path())
 919     }
 920 }
 921
 922 impl<'a> Seek for &'a NamedTempFile {
 923     fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
 924         self.as_file().seek(pos).with_err_path(|| self.path())
 925     }
 926 }
 927
 928 #[cfg(unix)]
 929 impl std::os::unix::io::AsRawFd for NamedTempFile {
 930     #[inline]
 931     fn as_raw_fd(&self) -> std::os::unix::io::RawFd {
 932         self.as_file().as_raw_fd()
 933     }
 934 }
 935
 936 #[cfg(windows)]
 937 impl std::os::windows::io::AsRawHandle for NamedTempFile {
 938     #[inline]
 939     fn as_raw_handle(&self) -> std::os::windows::io::RawHandle {
 940         self.as_file().as_raw_handle()
 941     }
 942 }
 943
 944 pub(crate) fn create_named(
 945     mut path: PathBuf,
 946     open_options: &mut OpenOptions,
 947 ) -> io::Result<NamedTempFile> {
 948     // Make the path absolute. Otherwise, changing directories could cause us to
 949     // delete the wrong file.
 950     if !path.is_absolute() {
 951         path = env::current_dir()?.join(path)
 952     }
 953     imp::create_named(&path, open_options)
 954         .with_err_path(|| path.clone())
 955         .map(|file| NamedTempFile {
 956             path: TempPath { path },
 957             file,
 958         })
 959 }