1// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2// file at the top-level directory of this distribution and at
3// http://rust-lang.org/COPYRIGHT.
4//
5// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8// option. This file may not be copied, modified, or distributed
9// except according to those terms.
10
11use std::ffi::OsStr;
12use std::fs::remove_dir_all;
13use std::mem;
14use std::path::{self, Path, PathBuf};
15use std::{fmt, io};
16
17use crate::error::IoResultExt;
18use crate::Builder;
19
20#[cfg(doc)]
21use crate::env;
22
23/// Create a new temporary directory.
24///
25/// The `tempdir` function creates a directory in the file system
26/// and returns a [`TempDir`].
27/// The directory will be automatically deleted when the `TempDir`s
28/// destructor is run.
29///
30/// # Resource Leaking
31///
32/// See [the resource leaking][resource-leaking] docs on `TempDir`.
33///
34/// # Errors
35///
36/// If the directory can not be created, `Err` is returned.
37///
38/// # Examples
39///
40/// ```
41/// use tempfile::tempdir;
42/// use std::fs::File;
43/// use std::io::Write;
44///
45/// // Create a directory inside of `env::temp_dir()`
46/// let tmp_dir = tempdir()?;
47///
48/// let file_path = tmp_dir.path().join("my-temporary-note.txt");
49/// let mut tmp_file = File::create(file_path)?;
50/// writeln!(tmp_file, "Brian was here. Briefly.")?;
51///
52/// // `tmp_dir` goes out of scope, the directory as well as
53/// // `tmp_file` will be deleted here.
54/// drop(tmp_file);
55/// tmp_dir.close()?;
56/// # Ok::<(), std::io::Error>(())
57/// ```
58///
59/// [`TempDir`]: struct.TempDir.html
60/// [resource-leaking]: struct.TempDir.html#resource-leaking
61pub fn tempdir() -> io::Result<TempDir> {
62 TempDir::new()
63}
64
65/// Create a new temporary directory in a specific directory.
66///
67/// The `tempdir_in` function creates a directory in the specified directory
68/// and returns a [`TempDir`].
69/// The directory will be automatically deleted when the `TempDir`s
70/// destructor is run.
71///
72/// # Resource Leaking
73///
74/// See [the resource leaking][resource-leaking] docs on `TempDir`.
75///
76/// # Errors
77///
78/// If the directory can not be created, `Err` is returned.
79///
80/// # Examples
81///
82/// ```
83/// use tempfile::tempdir_in;
84/// use std::fs::File;
85/// use std::io::Write;
86///
87/// // Create a directory inside of the current directory.
88/// let tmp_dir = tempdir_in(".")?;
89///
90/// let file_path = tmp_dir.path().join("my-temporary-note.txt");
91/// let mut tmp_file = File::create(file_path)?;
92/// writeln!(tmp_file, "Brian was here. Briefly.")?;
93///
94/// // `tmp_dir` goes out of scope, the directory as well as
95/// // `tmp_file` will be deleted here.
96/// drop(tmp_file);
97/// tmp_dir.close()?;
98/// # Ok::<(), std::io::Error>(())
99/// ```
100///
101/// [`TempDir`]: struct.TempDir.html
102/// [resource-leaking]: struct.TempDir.html#resource-leaking
103pub fn tempdir_in<P: AsRef<Path>>(dir: P) -> io::Result<TempDir> {
104 TempDir::new_in(dir)
105}
106
107/// A directory in the filesystem that is automatically deleted when
108/// it goes out of scope.
109///
110/// The [`TempDir`] type creates a directory on the file system that
111/// is deleted once it goes out of scope. At construction, the
112/// `TempDir` creates a new directory with a randomly generated name.
113///
114/// The default constructor, [`TempDir::new()`], creates directories in
115/// the location returned by [`env::temp_dir()`], but `TempDir`
116/// can be configured to manage a temporary directory in any location
117/// by constructing with a [`Builder`].
118///
119/// After creating a `TempDir`, work with the file system by doing
120/// standard [`std::fs`] file system operations on its [`Path`],
121/// which can be retrieved with [`TempDir::path()`]. Once the `TempDir`
122/// value is dropped, the directory at the path will be deleted, along
123/// with any files and directories it contains. It is your responsibility
124/// to ensure that no further file system operations are attempted
125/// inside the temporary directory once it has been deleted.
126///
127/// # Resource Leaking
128///
129/// Various platform-specific conditions may cause `TempDir` to fail
130/// to delete the underlying directory. It's important to ensure that
131/// handles (like [`File`] and [`ReadDir`]) to files inside the
132/// directory are dropped before the `TempDir` goes out of scope. The
133/// `TempDir` destructor will silently ignore any errors in deleting
134/// the directory; to instead handle errors call [`TempDir::close()`].
135///
136/// Note that if the program exits before the `TempDir` destructor is
137/// run, such as via [`std::process::exit()`], by segfaulting, or by
138/// receiving a signal like `SIGINT`, then the temporary directory
139/// will not be deleted.
140///
141/// # Examples
142///
143/// Create a temporary directory with a generated name:
144///
145/// ```
146/// use std::fs::File;
147/// use std::io::Write;
148/// use tempfile::TempDir;
149///
150/// // Create a directory inside of `env::temp_dir()`
151/// let tmp_dir = TempDir::new()?;
152/// # Ok::<(), std::io::Error>(())
153/// ```
154///
155/// Create a temporary directory with a prefix in its name:
156///
157/// ```
158/// use std::fs::File;
159/// use std::io::Write;
160/// use tempfile::Builder;
161///
162/// // Create a directory inside of `env::temp_dir()`,
163/// // whose name will begin with 'example'.
164/// let tmp_dir = Builder::new().prefix("example").tempdir()?;
165/// # Ok::<(), std::io::Error>(())
166/// ```
167///
168/// [`File`]: http://doc.rust-lang.org/std/fs/struct.File.html
169/// [`Path`]: http://doc.rust-lang.org/std/path/struct.Path.html
170/// [`ReadDir`]: http://doc.rust-lang.org/std/fs/struct.ReadDir.html
171/// [`Builder`]: struct.Builder.html
172/// [`TempDir::close()`]: struct.TempDir.html#method.close
173/// [`TempDir::new()`]: struct.TempDir.html#method.new
174/// [`TempDir::path()`]: struct.TempDir.html#method.path
175/// [`TempDir`]: struct.TempDir.html
176/// [`std::fs`]: http://doc.rust-lang.org/std/fs/index.html
177/// [`std::process::exit()`]: http://doc.rust-lang.org/std/process/fn.exit.html
178pub struct TempDir {
179 path: Box<Path>,
180 keep: bool,
181}
182
183impl TempDir {
184 /// Attempts to make a temporary directory inside of `env::temp_dir()`.
185 ///
186 /// See [`Builder`] for more configuration.
187 ///
188 /// The directory and everything inside it will be automatically deleted
189 /// once the returned `TempDir` is destroyed.
190 ///
191 /// # Errors
192 ///
193 /// If the directory can not be created, `Err` is returned.
194 ///
195 /// # Examples
196 ///
197 /// ```
198 /// use std::fs::File;
199 /// use std::io::Write;
200 /// use tempfile::TempDir;
201 ///
202 /// // Create a directory inside of `env::temp_dir()`
203 /// let tmp_dir = TempDir::new()?;
204 ///
205 /// let file_path = tmp_dir.path().join("my-temporary-note.txt");
206 /// let mut tmp_file = File::create(file_path)?;
207 /// writeln!(tmp_file, "Brian was here. Briefly.")?;
208 ///
209 /// // `tmp_dir` goes out of scope, the directory as well as
210 /// // `tmp_file` will be deleted here.
211 /// # Ok::<(), std::io::Error>(())
212 /// ```
213 ///
214 /// [`Builder`]: struct.Builder.html
215 pub fn new() -> io::Result<TempDir> {
216 Builder::new().tempdir()
217 }
218
219 /// Attempts to make a temporary directory inside of `dir`.
220 /// The directory and everything inside it will be automatically
221 /// deleted once the returned `TempDir` is destroyed.
222 ///
223 /// # Errors
224 ///
225 /// If the directory can not be created, `Err` is returned.
226 ///
227 /// # Examples
228 ///
229 /// ```
230 /// use std::fs::{self, File};
231 /// use std::io::Write;
232 /// use tempfile::TempDir;
233 ///
234 /// // Create a directory inside of the current directory
235 /// let tmp_dir = TempDir::new_in(".")?;
236 /// let file_path = tmp_dir.path().join("my-temporary-note.txt");
237 /// let mut tmp_file = File::create(file_path)?;
238 /// writeln!(tmp_file, "Brian was here. Briefly.")?;
239 /// # Ok::<(), std::io::Error>(())
240 /// ```
241 pub fn new_in<P: AsRef<Path>>(dir: P) -> io::Result<TempDir> {
242 Builder::new().tempdir_in(dir)
243 }
244
245 /// Attempts to make a temporary directory with the specified prefix inside of
246 /// `env::temp_dir()`. The directory and everything inside it will be automatically
247 /// deleted once the returned `TempDir` is destroyed.
248 ///
249 /// # Errors
250 ///
251 /// If the directory can not be created, `Err` is returned.
252 ///
253 /// # Examples
254 ///
255 /// ```
256 /// use std::fs::{self, File};
257 /// use std::io::Write;
258 /// use tempfile::TempDir;
259 ///
260 /// // Create a directory inside of the current directory
261 /// let tmp_dir = TempDir::with_prefix("foo-")?;
262 /// let tmp_name = tmp_dir.path().file_name().unwrap().to_str().unwrap();
263 /// assert!(tmp_name.starts_with("foo-"));
264 /// # Ok::<(), std::io::Error>(())
265 /// ```
266 pub fn with_prefix<S: AsRef<OsStr>>(prefix: S) -> io::Result<TempDir> {
267 Builder::new().prefix(&prefix).tempdir()
268 }
269
270 /// Attempts to make a temporary directory with the specified suffix inside of
271 /// `env::temp_dir()`. The directory and everything inside it will be automatically
272 /// deleted once the returned `TempDir` is destroyed.
273 ///
274 /// # Errors
275 ///
276 /// If the directory can not be created, `Err` is returned.
277 ///
278 /// # Examples
279 ///
280 /// ```
281 /// use std::fs::{self, File};
282 /// use std::io::Write;
283 /// use tempfile::TempDir;
284 ///
285 /// // Create a directory inside of the current directory
286 /// let tmp_dir = TempDir::with_suffix("-foo")?;
287 /// let tmp_name = tmp_dir.path().file_name().unwrap().to_str().unwrap();
288 /// assert!(tmp_name.ends_with("-foo"));
289 /// # Ok::<(), std::io::Error>(())
290 /// ```
291 pub fn with_suffix<S: AsRef<OsStr>>(suffix: S) -> io::Result<TempDir> {
292 Builder::new().suffix(&suffix).tempdir()
293 }
294 /// Attempts to make a temporary directory with the specified prefix inside
295 /// the specified directory. The directory and everything inside it will be
296 /// automatically deleted once the returned `TempDir` is destroyed.
297 ///
298 /// # Errors
299 ///
300 /// If the directory can not be created, `Err` is returned.
301 ///
302 /// # Examples
303 ///
304 /// ```
305 /// use std::fs::{self, File};
306 /// use std::io::Write;
307 /// use tempfile::TempDir;
308 ///
309 /// // Create a directory inside of the current directory
310 /// let tmp_dir = TempDir::with_suffix_in("-foo", ".")?;
311 /// let tmp_name = tmp_dir.path().file_name().unwrap().to_str().unwrap();
312 /// assert!(tmp_name.ends_with("-foo"));
313 /// # Ok::<(), std::io::Error>(())
314 /// ```
315 pub fn with_suffix_in<S: AsRef<OsStr>, P: AsRef<Path>>(
316 suffix: S,
317 dir: P,
318 ) -> io::Result<TempDir> {
319 Builder::new().suffix(&suffix).tempdir_in(dir)
320 }
321
322 /// Attempts to make a temporary directory with the specified prefix inside
323 /// the specified directory. The directory and everything inside it will be
324 /// automatically deleted once the returned `TempDir` is destroyed.
325 ///
326 /// # Errors
327 ///
328 /// If the directory can not be created, `Err` is returned.
329 ///
330 /// # Examples
331 ///
332 /// ```
333 /// use std::fs::{self, File};
334 /// use std::io::Write;
335 /// use tempfile::TempDir;
336 ///
337 /// // Create a directory inside of the current directory
338 /// let tmp_dir = TempDir::with_prefix_in("foo-", ".")?;
339 /// let tmp_name = tmp_dir.path().file_name().unwrap().to_str().unwrap();
340 /// assert!(tmp_name.starts_with("foo-"));
341 /// # Ok::<(), std::io::Error>(())
342 /// ```
343 pub fn with_prefix_in<S: AsRef<OsStr>, P: AsRef<Path>>(
344 prefix: S,
345 dir: P,
346 ) -> io::Result<TempDir> {
347 Builder::new().prefix(&prefix).tempdir_in(dir)
348 }
349
350 /// Accesses the [`Path`] to the temporary directory.
351 ///
352 /// [`Path`]: http://doc.rust-lang.org/std/path/struct.Path.html
353 ///
354 /// # Examples
355 ///
356 /// ```
357 /// use tempfile::TempDir;
358 ///
359 /// let tmp_path;
360 ///
361 /// {
362 /// let tmp_dir = TempDir::new()?;
363 /// tmp_path = tmp_dir.path().to_owned();
364 ///
365 /// // Check that the temp directory actually exists.
366 /// assert!(tmp_path.exists());
367 ///
368 /// // End of `tmp_dir` scope, directory will be deleted
369 /// }
370 ///
371 /// // Temp directory should be deleted by now
372 /// assert_eq!(tmp_path.exists(), false);
373 /// # Ok::<(), std::io::Error>(())
374 /// ```
375 #[must_use]
376 pub fn path(&self) -> &path::Path {
377 self.path.as_ref()
378 }
379
380 /// Persist the temporary directory to disk, returning the [`PathBuf`] where it is located.
381 ///
382 /// This consumes the [`TempDir`] without deleting directory on the filesystem, meaning that
383 /// the directory will no longer be automatically deleted.
384 ///
385 /// [`TempDir`]: struct.TempDir.html
386 /// [`PathBuf`]: http://doc.rust-lang.org/std/path/struct.PathBuf.html
387 ///
388 /// # Examples
389 ///
390 /// ```
391 /// use std::fs;
392 /// use tempfile::TempDir;
393 ///
394 /// let tmp_dir = TempDir::new()?;
395 ///
396 /// // Persist the temporary directory to disk,
397 /// // getting the path where it is.
398 /// let tmp_path = tmp_dir.into_path();
399 ///
400 /// // Delete the temporary directory ourselves.
401 /// fs::remove_dir_all(tmp_path)?;
402 /// # Ok::<(), std::io::Error>(())
403 /// ```
404 #[must_use]
405 pub fn into_path(self) -> PathBuf {
406 // Prevent the Drop impl from being called.
407 let mut this = mem::ManuallyDrop::new(self);
408
409 // replace this.path with an empty Box, since an empty Box does not
410 // allocate any heap memory.
411 mem::replace(&mut this.path, PathBuf::new().into_boxed_path()).into()
412 }
413
414 /// Closes and removes the temporary directory, returning a `Result`.
415 ///
416 /// Although `TempDir` removes the directory on drop, in the destructor
417 /// any errors are ignored. To detect errors cleaning up the temporary
418 /// directory, call `close` instead.
419 ///
420 /// # Errors
421 ///
422 /// This function may return a variety of [`std::io::Error`]s that result from deleting
423 /// the files and directories contained with the temporary directory,
424 /// as well as from deleting the temporary directory itself. These errors
425 /// may be platform specific.
426 ///
427 /// [`std::io::Error`]: http://doc.rust-lang.org/std/io/struct.Error.html
428 ///
429 /// # Examples
430 ///
431 /// ```
432 /// use std::fs::File;
433 /// use std::io::Write;
434 /// use tempfile::TempDir;
435 ///
436 /// // Create a directory inside of `env::temp_dir()`.
437 /// let tmp_dir = TempDir::new()?;
438 /// let file_path = tmp_dir.path().join("my-temporary-note.txt");
439 /// let mut tmp_file = File::create(file_path)?;
440 /// writeln!(tmp_file, "Brian was here. Briefly.")?;
441 ///
442 /// // By closing the `TempDir` explicitly we can check that it has
443 /// // been deleted successfully. If we don't close it explicitly,
444 /// // the directory will still be deleted when `tmp_dir` goes out
445 /// // of scope, but we won't know whether deleting the directory
446 /// // succeeded.
447 /// drop(tmp_file);
448 /// tmp_dir.close()?;
449 /// # Ok::<(), std::io::Error>(())
450 /// ```
451 pub fn close(mut self) -> io::Result<()> {
452 let result = remove_dir_all(self.path()).with_err_path(|| self.path());
453
454 // Set self.path to empty Box to release the memory, since an empty
455 // Box does not allocate any heap memory.
456 self.path = PathBuf::new().into_boxed_path();
457
458 // Prevent the Drop impl from being called.
459 mem::forget(self);
460
461 result
462 }
463}
464
465impl AsRef<Path> for TempDir {
466 fn as_ref(&self) -> &Path {
467 self.path()
468 }
469}
470
471impl fmt::Debug for TempDir {
472 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
473 f&mut DebugStruct<'_, '_>.debug_struct("TempDir")
474 .field(name:"path", &self.path())
475 .finish()
476 }
477}
478
479impl Drop for TempDir {
480 fn drop(&mut self) {
481 if !self.keep {
482 let _ = remove_dir_all(self.path());
483 }
484 }
485}
486
487pub(crate) fn create(
488 path: PathBuf,
489 permissions: Option<&std::fs::Permissions>,
490 keep: bool,
491) -> io::Result<TempDir> {
492 imp::create(path, permissions, keep)
493}
494
495mod imp;
496