tempfile/file/mod.rs
1use std::env;
2use std::error;
3use std::ffi::OsStr;
4use std::fmt;
5use std::fs::{self, File, OpenOptions};
6use std::io::{self, Read, Seek, SeekFrom, Write};
7use std::mem;
8use std::ops::Deref;
9use std::path::{Path, PathBuf};
10
11use crate::error::IoResultExt;
12use crate::Builder;
13
14mod 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
54pub 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
95pub 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)]
101pub 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
108impl From<PathPersistError> for io::Error {
109 #[inline]
110 fn from(error: PathPersistError) -> io::Error {
111 error.error
112 }
113}
114
115impl From<PathPersistError> for TempPath {
116 #[inline]
117 fn from(error: PathPersistError) -> TempPath {
118 error.path
119 }
120}
121
122impl 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
128impl 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.
140pub struct TempPath {
141 path: PathBuf,
142}
143
144impl 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
356impl fmt::Debug for TempPath {
357 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
358 self.path.fmt(f)
359 }
360}
361
362impl Drop for TempPath {
363 fn drop(&mut self) {
364 let _ = fs::remove_file(&self.path);
365 }
366}
367
368impl Deref for TempPath {
369 type Target = Path;
370
371 fn deref(&self) -> &Path {
372 &self.path
373 }
374}
375
376impl AsRef<Path> for TempPath {
377 fn as_ref(&self) -> &Path {
378 &self.path
379 }
380}
381
382impl 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
469pub struct NamedTempFile {
470 path: TempPath,
471 file: File,
472}
473
474impl fmt::Debug for NamedTempFile {
475 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
476 write!(f, "NamedTempFile({:?})", self.path)
477 }
478}
479
480impl 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)]
489pub 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
496impl From<PersistError> for io::Error {
497 #[inline]
498 fn from(error: PersistError) -> io::Error {
499 error.error
500 }
501}
502
503impl From<PersistError> for NamedTempFile {
504 #[inline]
505 fn from(error: PersistError) -> NamedTempFile {
506 error.file
507 }
508}
509
510impl 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
516impl error::Error for PersistError {
517 fn source(&self) -> Option<&(dyn error::Error + 'static)> {
518 Some(&self.error)
519 }
520}
521
522impl 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
884impl 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
890impl<'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
896impl 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
906impl<'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
916impl 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
922impl<'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)]
929impl 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)]
937impl 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
944pub(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}