src/libstd/fs/mod.rs

   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
  11 //! Filesystem manipulation operations
  12 //!
  13 //! This module contains basic methods to manipulate the contents of the local
  14 //! filesystem. All methods in this module represent cross-platform filesystem
  15 //! operations. Extra platform-specific functionality can be found in the
  16 //! extension traits of `std::os::$platform`.
  17
  18 #![stable(feature = "rust1", since = "1.0.0")]
  19
  20 use core::prelude::*;
  21
  22 use io::{self, Error, ErrorKind, SeekFrom, Seek, Read, Write};
  23 use path::{Path, PathBuf};
  24 use sys::fs2 as fs_imp;
  25 use sys_common::{AsInnerMut, FromInner, AsInner};
  26 use vec::Vec;
  27
  28 #[allow(deprecated)]
  29 pub use self::tempdir::TempDir;
  30
  31 mod tempdir;
  32
  33 /// A reference to an open file on the filesystem.
  34 ///
  35 /// An instance of a `File` can be read and/or written depending on what options
  36 /// it was opened with. Files also implement `Seek` to alter the logical cursor
  37 /// that the file contains internally.
  38 ///
  39 /// # Examples
  40 ///
  41 /// ```no_run
  42 /// use std::io::prelude::*;
  43 /// use std::fs::File;
  44 ///
  45 /// # fn foo() -> std::io::Result<()> {
  46 /// let mut f = try!(File::create("foo.txt"));
  47 /// try!(f.write_all(b"Hello, world!"));
  48 ///
  49 /// let mut f = try!(File::open("foo.txt"));
  50 /// let mut s = String::new();
  51 /// try!(f.read_to_string(&mut s));
  52 /// assert_eq!(s, "Hello, world!");
  53 /// # Ok(())
  54 /// # }
  55 /// ```
  56 #[stable(feature = "rust1", since = "1.0.0")]
  57 pub struct File {
  58     inner: fs_imp::File,
  59     path: Option<PathBuf>,
  60 }
  61
  62 /// Metadata information about a file.
  63 ///
  64 /// This structure is returned from the `metadata` function or method and
  65 /// represents known metadata about a file such as its permissions, size,
  66 /// modification times, etc.
  67 #[stable(feature = "rust1", since = "1.0.0")]
  68 pub struct Metadata(fs_imp::FileAttr);
  69
  70 /// Iterator over the entries in a directory.
  71 ///
  72 /// This iterator is returned from the `read_dir` function of this module and
  73 /// will yield instances of `io::Result<DirEntry>`. Through a `DirEntry`
  74 /// information like the entry's path and possibly other metadata can be
  75 /// learned.
  76 ///
  77 /// # Failure
  78 ///
  79 /// This `io::Result` will be an `Err` if there's some sort of intermittent
  80 /// IO error during iteration.
  81 #[stable(feature = "rust1", since = "1.0.0")]
  82 pub struct ReadDir(fs_imp::ReadDir);
  83
  84 /// Entries returned by the `ReadDir` iterator.
  85 ///
  86 /// An instance of `DirEntry` represents an entry inside of a directory on the
  87 /// filesystem. Each entry can be inspected via methods to learn about the full
  88 /// path or possibly other metadata through per-platform extension traits.
  89 #[stable(feature = "rust1", since = "1.0.0")]
  90 pub struct DirEntry(fs_imp::DirEntry);
  91
  92 /// An iterator that recursively walks over the contents of a directory.
  93 #[unstable(feature = "fs_walk",
  94            reason = "the precise semantics and defaults for a recursive walk \
  95                      may change and this may end up accounting for files such \
  96                      as symlinks differently")]
  97 pub struct WalkDir {
  98     cur: Option<ReadDir>,
  99     stack: Vec<io::Result<ReadDir>>,
 100 }
 101
 102 /// Options and flags which can be used to configure how a file is opened.
 103 ///
 104 /// This builder exposes the ability to configure how a `File` is opened and
 105 /// what operations are permitted on the open file. The `File::open` and
 106 /// `File::create` methods are aliases for commonly used options using this
 107 /// builder.
 108 #[derive(Clone)]
 109 #[stable(feature = "rust1", since = "1.0.0")]
 110 pub struct OpenOptions(fs_imp::OpenOptions);
 111
 112 /// Representation of the various permissions on a file.
 113 ///
 114 /// This module only currently provides one bit of information, `readonly`,
 115 /// which is exposed on all currently supported platforms. Unix-specific
 116 /// functionality, such as mode bits, is available through the
 117 /// `os::unix::PermissionsExt` trait.
 118 #[derive(Clone, PartialEq, Eq, Debug)]
 119 #[stable(feature = "rust1", since = "1.0.0")]
 120 pub struct Permissions(fs_imp::FilePermissions);
 121
 122 impl File {
 123     /// Attempts to open a file in read-only mode.
 124     ///
 125     /// See the `OpenOptions::open` method for more details.
 126     ///
 127     /// # Errors
 128     ///
 129     /// This function will return an error if `path` does not already exist.
 130     /// Other errors may also be returned according to `OpenOptions::open`.
 131     ///
 132     /// # Examples
 133     ///
 134     /// ```no_run
 135     /// use std::fs::File;
 136     ///
 137     /// # fn foo() -> std::io::Result<()> {
 138     /// let mut f = try!(File::open("foo.txt"));
 139     /// # Ok(())
 140     /// # }
 141     /// ```
 142     #[stable(feature = "rust1", since = "1.0.0")]
 143     pub fn open<P: AsRef<Path>>(path: P) -> io::Result<File> {
 144         OpenOptions::new().read(true).open(path)
 145     }
 146
 147     /// Open a file in write-only mode.
 148     ///
 149     /// This function will create a file if it does not exist,
 150     /// and will truncate it if it does.
 151     ///
 152     /// See the `OpenOptions::open` function for more details.
 153     ///
 154     /// # Examples
 155     ///
 156     /// ```no_run
 157     /// use std::fs::File;
 158     ///
 159     /// # fn foo() -> std::io::Result<()> {
 160     /// let mut f = try!(File::create("foo.txt"));
 161     /// # Ok(())
 162     /// # }
 163     /// ```
 164     #[stable(feature = "rust1", since = "1.0.0")]
 165     pub fn create<P: AsRef<Path>>(path: P) -> io::Result<File> {
 166         OpenOptions::new().write(true).create(true).truncate(true).open(path)
 167     }
 168
 169     /// Returns the original path that was used to open this file.
 170     #[unstable(feature = "file_path",
 171                reason = "this abstraction is imposed by this library instead \
 172                          of the underlying OS and may be removed")]
 173     pub fn path(&self) -> Option<&Path> {
 174         self.path.as_ref().map(|p| &**p)
 175     }
 176
 177     /// Attempt to sync all OS-internal metadata to disk.
 178     ///
 179     /// This function will attempt to ensure that all in-core data reaches the
 180     /// filesystem before returning.
 181     ///
 182     /// # Examples
 183     ///
 184     /// ```no_run
 185     /// use std::fs::File;
 186     /// use std::io::prelude::*;
 187     ///
 188     /// # fn foo() -> std::io::Result<()> {
 189     /// let mut f = try!(File::create("foo.txt"));
 190     /// try!(f.write_all(b"Hello, world!"));
 191     ///
 192     /// try!(f.sync_all());
 193     /// # Ok(())
 194     /// # }
 195     /// ```
 196     #[stable(feature = "rust1", since = "1.0.0")]
 197     pub fn sync_all(&self) -> io::Result<()> {
 198         self.inner.fsync()
 199     }
 200
 201     /// This function is similar to `sync_all`, except that it may not
 202     /// synchronize file metadata to the filesystem.
 203     ///
 204     /// This is intended for use cases that must synchronize content, but don't
 205     /// need the metadata on disk. The goal of this method is to reduce disk
 206     /// operations.
 207     ///
 208     /// Note that some platforms may simply implement this in terms of
 209     /// `sync_all`.
 210     ///
 211     /// # Examples
 212     ///
 213     /// ```no_run
 214     /// use std::fs::File;
 215     /// use std::io::prelude::*;
 216     ///
 217     /// # fn foo() -> std::io::Result<()> {
 218     /// let mut f = try!(File::create("foo.txt"));
 219     /// try!(f.write_all(b"Hello, world!"));
 220     ///
 221     /// try!(f.sync_data());
 222     /// # Ok(())
 223     /// # }
 224     /// ```
 225     #[stable(feature = "rust1", since = "1.0.0")]
 226     pub fn sync_data(&self) -> io::Result<()> {
 227         self.inner.datasync()
 228     }
 229
 230     /// Truncates or extends the underlying file, updating the size of
 231     /// this file to become `size`.
 232     ///
 233     /// If the `size` is less than the current file's size, then the file will
 234     /// be shrunk. If it is greater than the current file's size, then the file
 235     /// will be extended to `size` and have all of the intermediate data filled
 236     /// in with 0s.
 237     ///
 238     /// # Examples
 239     ///
 240     /// ```no_run
 241     /// use std::fs::File;
 242     ///
 243     /// # fn foo() -> std::io::Result<()> {
 244     /// let mut f = try!(File::open("foo.txt"));
 245     /// try!(f.set_len(0));
 246     /// # Ok(())
 247     /// # }
 248     /// ```
 249     #[stable(feature = "rust1", since = "1.0.0")]
 250     pub fn set_len(&self, size: u64) -> io::Result<()> {
 251         self.inner.truncate(size)
 252     }
 253
 254     /// Queries metadata about the underlying file.
 255     ///
 256     /// # Examples
 257     ///
 258     /// ```no_run
 259     /// use std::fs::File;
 260     ///
 261     /// # fn foo() -> std::io::Result<()> {
 262     /// let mut f = try!(File::open("foo.txt"));
 263     /// let metadata = try!(f.metadata());
 264     /// # Ok(())
 265     /// # }
 266     /// ```
 267     #[stable(feature = "rust1", since = "1.0.0")]
 268     pub fn metadata(&self) -> io::Result<Metadata> {
 269         self.inner.file_attr().map(Metadata)
 270     }
 271 }
 272
 273 impl AsInner<fs_imp::File> for File {
 274     fn as_inner(&self) -> &fs_imp::File { &self.inner }
 275 }
 276 impl FromInner<fs_imp::File> for File {
 277     fn from_inner(f: fs_imp::File) -> File {
 278         File { inner: f, path: None }
 279     }
 280 }
 281
 282 #[stable(feature = "rust1", since = "1.0.0")]
 283 impl Read for File {
 284     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 285         self.inner.read(buf)
 286     }
 287 }
 288 #[stable(feature = "rust1", since = "1.0.0")]
 289 impl Write for File {
 290     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 291         self.inner.write(buf)
 292     }
 293     fn flush(&mut self) -> io::Result<()> { self.inner.flush() }
 294 }
 295 #[stable(feature = "rust1", since = "1.0.0")]
 296 impl Seek for File {
 297     fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
 298         self.inner.seek(pos)
 299     }
 300 }
 301 #[stable(feature = "rust1", since = "1.0.0")]
 302 impl<'a> Read for &'a File {
 303     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 304         self.inner.read(buf)
 305     }
 306 }
 307 #[stable(feature = "rust1", since = "1.0.0")]
 308 impl<'a> Write for &'a File {
 309     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 310         self.inner.write(buf)
 311     }
 312     fn flush(&mut self) -> io::Result<()> { self.inner.flush() }
 313 }
 314 #[stable(feature = "rust1", since = "1.0.0")]
 315 impl<'a> Seek for &'a File {
 316     fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
 317         self.inner.seek(pos)
 318     }
 319 }
 320
 321 impl OpenOptions {
 322     /// Creates a blank net set of options ready for configuration.
 323     ///
 324     /// All options are initially set to `false`.
 325     #[stable(feature = "rust1", since = "1.0.0")]
 326     pub fn new() -> OpenOptions {
 327         OpenOptions(fs_imp::OpenOptions::new())
 328     }
 329
 330     /// Set the option for read access.
 331     ///
 332     /// This option, when true, will indicate that the file should be
 333     /// `read`-able if opened.
 334     #[stable(feature = "rust1", since = "1.0.0")]
 335     pub fn read(&mut self, read: bool) -> &mut OpenOptions {
 336         self.0.read(read); self
 337     }
 338
 339     /// Set the option for write access.
 340     ///
 341     /// This option, when true, will indicate that the file should be
 342     /// `write`-able if opened.
 343     #[stable(feature = "rust1", since = "1.0.0")]
 344     pub fn write(&mut self, write: bool) -> &mut OpenOptions {
 345         self.0.write(write); self
 346     }
 347
 348     /// Set the option for the append mode.
 349     ///
 350     /// This option, when true, means that writes will append to a file instead
 351     /// of overwriting previous contents.
 352     #[stable(feature = "rust1", since = "1.0.0")]
 353     pub fn append(&mut self, append: bool) -> &mut OpenOptions {
 354         self.0.append(append); self
 355     }
 356
 357     /// Set the option for truncating a previous file.
 358     ///
 359     /// If a file is successfully opened with this option set it will truncate
 360     /// the file to 0 length if it already exists.
 361     #[stable(feature = "rust1", since = "1.0.0")]
 362     pub fn truncate(&mut self, truncate: bool) -> &mut OpenOptions {
 363         self.0.truncate(truncate); self
 364     }
 365
 366     /// Set the option for creating a new file.
 367     ///
 368     /// This option indicates whether a new file will be created if the file
 369     /// does not yet already exist.
 370     #[stable(feature = "rust1", since = "1.0.0")]
 371     pub fn create(&mut self, create: bool) -> &mut OpenOptions {
 372         self.0.create(create); self
 373     }
 374
 375     /// Open a file at `path` with the options specified by `self`.
 376     ///
 377     /// # Errors
 378     ///
 379     /// This function will return an error under a number of different
 380     /// circumstances, to include but not limited to:
 381     ///
 382     /// * Opening a file that does not exist with read access.
 383     /// * Attempting to open a file with access that the user lacks
 384     ///   permissions for
 385     /// * Filesystem-level errors (full disk, etc)
 386     #[stable(feature = "rust1", since = "1.0.0")]
 387     pub fn open<P: AsRef<Path>>(&self, path: P) -> io::Result<File> {
 388         let path = path.as_ref();
 389         let inner = try!(fs_imp::File::open(path, &self.0));
 390         Ok(File { path: Some(path.to_path_buf()), inner: inner })
 391     }
 392 }
 393
 394 impl AsInnerMut<fs_imp::OpenOptions> for OpenOptions {
 395     fn as_inner_mut(&mut self) -> &mut fs_imp::OpenOptions { &mut self.0 }
 396 }
 397
 398 impl Metadata {
 399     /// Returns whether this metadata is for a directory.
 400     #[stable(feature = "rust1", since = "1.0.0")]
 401     pub fn is_dir(&self) -> bool { self.0.is_dir() }
 402
 403     /// Returns whether this metadata is for a regular file.
 404     #[stable(feature = "rust1", since = "1.0.0")]
 405     pub fn is_file(&self) -> bool { self.0.is_file() }
 406
 407     /// Returns the size of the file, in bytes, this metadata is for.
 408     #[stable(feature = "rust1", since = "1.0.0")]
 409     pub fn len(&self) -> u64 { self.0.size() }
 410
 411     /// Returns the permissions of the file this metadata is for.
 412     #[stable(feature = "rust1", since = "1.0.0")]
 413     pub fn permissions(&self) -> Permissions {
 414         Permissions(self.0.perm())
 415     }
 416
 417     /// Returns the most recent access time for a file.
 418     ///
 419     /// The return value is in milliseconds since the epoch.
 420     #[unstable(feature = "fs_time",
 421                reason = "the return type of u64 is not quite appropriate for \
 422                          this method and may change if the standard library \
 423                          gains a type to represent a moment in time")]
 424     pub fn accessed(&self) -> u64 { self.0.accessed() }
 425
 426     /// Returns the most recent modification time for a file.
 427     ///
 428     /// The return value is in milliseconds since the epoch.
 429     #[unstable(feature = "fs_time",
 430                reason = "the return type of u64 is not quite appropriate for \
 431                          this method and may change if the standard library \
 432                          gains a type to represent a moment in time")]
 433     pub fn modified(&self) -> u64 { self.0.modified() }
 434 }
 435
 436 impl Permissions {
 437     /// Returns whether these permissions describe a readonly file.
 438     #[stable(feature = "rust1", since = "1.0.0")]
 439     pub fn readonly(&self) -> bool { self.0.readonly() }
 440
 441     /// Modify the readonly flag for this set of permissions.
 442     ///
 443     /// This operation does **not** modify the filesystem. To modify the
 444     /// filesystem use the `fs::set_permissions` function.
 445     #[stable(feature = "rust1", since = "1.0.0")]
 446     pub fn set_readonly(&mut self, readonly: bool) {
 447         self.0.set_readonly(readonly)
 448     }
 449 }
 450
 451 impl FromInner<fs_imp::FilePermissions> for Permissions {
 452     fn from_inner(f: fs_imp::FilePermissions) -> Permissions {
 453         Permissions(f)
 454     }
 455 }
 456
 457 impl AsInner<fs_imp::FilePermissions> for Permissions {
 458     fn as_inner(&self) -> &fs_imp::FilePermissions { &self.0 }
 459 }
 460
 461 #[stable(feature = "rust1", since = "1.0.0")]
 462 impl Iterator for ReadDir {
 463     type Item = io::Result<DirEntry>;
 464
 465     fn next(&mut self) -> Option<io::Result<DirEntry>> {
 466         self.0.next().map(|entry| entry.map(DirEntry))
 467     }
 468 }
 469
 470 #[stable(feature = "rust1", since = "1.0.0")]
 471 impl DirEntry {
 472     /// Returns the full path to the file that this entry represents.
 473     ///
 474     /// The full path is created by joining the original path to `read_dir` or
 475     /// `walk_dir` with the filename of this entry.
 476     #[stable(feature = "rust1", since = "1.0.0")]
 477     pub fn path(&self) -> PathBuf { self.0.path() }
 478 }
 479
 480 /// Remove a file from the underlying filesystem.
 481 ///
 482 /// # Examples
 483 ///
 484 /// ```rust,no_run
 485 /// use std::fs;
 486 ///
 487 /// fs::remove_file("/some/file/path.txt");
 488 /// ```
 489 ///
 490 /// Note that, just because an unlink call was successful, it is not
 491 /// guaranteed that a file is immediately deleted (e.g. depending on
 492 /// platform, other open file descriptors may prevent immediate removal).
 493 ///
 494 /// # Errors
 495 ///
 496 /// This function will return an error if `path` points to a directory, if the
 497 /// user lacks permissions to remove the file, or if some other filesystem-level
 498 /// error occurs.
 499 #[stable(feature = "rust1", since = "1.0.0")]
 500 pub fn remove_file<P: AsRef<Path>>(path: P) -> io::Result<()> {
 501     fs_imp::unlink(path.as_ref())
 502 }
 503
 504 /// Given a path, query the file system to get information about a file,
 505 /// directory, etc.
 506 ///
 507 /// This function will traverse soft links to query information about the
 508 /// destination file.
 509 ///
 510 /// # Examples
 511 ///
 512 /// ```rust,no_run
 513 /// # fn foo() -> std::io::Result<()> {
 514 /// use std::fs;
 515 ///
 516 /// let attr = try!(fs::metadata("/some/file/path.txt"));
 517 /// // inspect attr ...
 518 /// # Ok(())
 519 /// # }
 520 /// ```
 521 ///
 522 /// # Errors
 523 ///
 524 /// This function will return an error if the user lacks the requisite
 525 /// permissions to perform a `metadata` call on the given `path` or if there
 526 /// is no entry in the filesystem at the provided path.
 527 #[stable(feature = "rust1", since = "1.0.0")]
 528 pub fn metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
 529     fs_imp::stat(path.as_ref()).map(Metadata)
 530 }
 531
 532 /// Rename a file or directory to a new name.
 533 ///
 534 /// # Examples
 535 ///
 536 /// ```rust,no_run
 537 /// use std::fs;
 538 ///
 539 /// fs::rename("foo", "bar");
 540 /// ```
 541 ///
 542 /// # Errors
 543 ///
 544 /// This function will return an error if the provided `from` doesn't exist, if
 545 /// the process lacks permissions to view the contents, if `from` and `to`
 546 /// reside on separate filesystems, or if some other intermittent I/O error
 547 /// occurs.
 548 #[stable(feature = "rust1", since = "1.0.0")]
 549 pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<()> {
 550     fs_imp::rename(from.as_ref(), to.as_ref())
 551 }
 552
 553 /// Copies the contents of one file to another. This function will also
 554 /// copy the permission bits of the original file to the destination file.
 555 ///
 556 /// This function will **overwrite** the contents of `to`.
 557 ///
 558 /// Note that if `from` and `to` both point to the same file, then the file
 559 /// will likely get truncated by this operation.
 560 ///
 561 /// # Examples
 562 ///
 563 /// ```
 564 /// use std::fs;
 565 ///
 566 /// fs::copy("foo.txt", "bar.txt");
 567 /// ```
 568 ///
 569 /// # Errors
 570 ///
 571 /// This function will return an error in the following situations, but is not
 572 /// limited to just these cases:
 573 ///
 574 /// * The `from` path is not a file
 575 /// * The `from` file does not exist
 576 /// * The current process does not have the permission rights to access
 577 ///   `from` or write `to`
 578 #[stable(feature = "rust1", since = "1.0.0")]
 579 pub fn copy<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<u64> {
 580     let from = from.as_ref();
 581     let to = to.as_ref();
 582     if !from.is_file() {
 583         return Err(Error::new(ErrorKind::InvalidInput,
 584                               "the source path is not an existing file",
 585                               None))
 586     }
 587
 588     let mut reader = try!(File::open(from));
 589     let mut writer = try!(File::create(to));
 590     let perm = try!(reader.metadata()).permissions();
 591
 592     let ret = try!(io::copy(&mut reader, &mut writer));
 593     try!(set_permissions(to, perm));
 594     Ok(ret)
 595 }
 596
 597 /// Creates a new hard link on the filesystem.
 598 ///
 599 /// The `dst` path will be a link pointing to the `src` path. Note that systems
 600 /// often require these two paths to both be located on the same filesystem.
 601 #[stable(feature = "rust1", since = "1.0.0")]
 602 pub fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()> {
 603     fs_imp::link(src.as_ref(), dst.as_ref())
 604 }
 605
 606 /// Creates a new soft link on the filesystem.
 607 ///
 608 /// The `dst` path will be a soft link pointing to the `src` path.
 609 #[stable(feature = "rust1", since = "1.0.0")]
 610 pub fn soft_link<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()> {
 611     fs_imp::symlink(src.as_ref(), dst.as_ref())
 612 }
 613
 614 /// Reads a soft link, returning the file that the link points to.
 615 ///
 616 /// # Errors
 617 ///
 618 /// This function will return an error on failure. Failure conditions include
 619 /// reading a file that does not exist or reading a file that is not a soft
 620 /// link.
 621 #[stable(feature = "rust1", since = "1.0.0")]
 622 pub fn read_link<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
 623     fs_imp::readlink(path.as_ref())
 624 }
 625
 626 /// Create a new, empty directory at the provided path
 627 ///
 628 /// # Examples
 629 ///
 630 /// ```
 631 /// use std::fs;
 632 ///
 633 /// fs::create_dir("/some/dir");
 634 /// ```
 635 ///
 636 /// # Errors
 637 ///
 638 /// This function will return an error if the user lacks permissions to make a
 639 /// new directory at the provided `path`, or if the directory already exists.
 640 #[stable(feature = "rust1", since = "1.0.0")]
 641 pub fn create_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
 642     fs_imp::mkdir(path.as_ref())
 643 }
 644
 645 /// Recursively create a directory and all of its parent components if they
 646 /// are missing.
 647 ///
 648 /// # Errors
 649 ///
 650 /// This function will fail if any directory in the path specified by `path`
 651 /// does not already exist and it could not be created otherwise. The specific
 652 /// error conditions for when a directory is being created (after it is
 653 /// determined to not exist) are outlined by `fs::create_dir`.
 654 #[stable(feature = "rust1", since = "1.0.0")]
 655 pub fn create_dir_all<P: AsRef<Path>>(path: P) -> io::Result<()> {
 656     let path = path.as_ref();
 657     if path == Path::new("") || path.is_dir() { return Ok(()) }
 658     if let Some(p) = path.parent() { try!(create_dir_all(p)) }
 659     create_dir(path)
 660 }
 661
 662 /// Remove an existing, empty directory
 663 ///
 664 /// # Examples
 665 ///
 666 /// ```
 667 /// use std::fs;
 668 ///
 669 /// fs::remove_dir("/some/dir");
 670 /// ```
 671 ///
 672 /// # Errors
 673 ///
 674 /// This function will return an error if the user lacks permissions to remove
 675 /// the directory at the provided `path`, or if the directory isn't empty.
 676 #[stable(feature = "rust1", since = "1.0.0")]
 677 pub fn remove_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
 678     fs_imp::rmdir(path.as_ref())
 679 }
 680
 681 /// Removes a directory at this path, after removing all its contents. Use
 682 /// carefully!
 683 ///
 684 /// This function does **not** follow soft links and it will simply remove the
 685 /// soft link itself.
 686 ///
 687 /// # Errors
 688 ///
 689 /// See `file::remove_file` and `fs::remove_dir`
 690 #[stable(feature = "rust1", since = "1.0.0")]
 691 pub fn remove_dir_all<P: AsRef<Path>>(path: P) -> io::Result<()> {
 692     let path = path.as_ref();
 693     for child in try!(read_dir(path)) {
 694         let child = try!(child).path();
 695         let stat = try!(lstat(&*child));
 696         if stat.is_dir() {
 697             try!(remove_dir_all(&*child));
 698         } else {
 699             try!(remove_file(&*child));
 700         }
 701     }
 702     return remove_dir(path);
 703
 704     #[cfg(unix)]
 705     fn lstat(path: &Path) -> io::Result<fs_imp::FileAttr> { fs_imp::lstat(path) }
 706     #[cfg(windows)]
 707     fn lstat(path: &Path) -> io::Result<fs_imp::FileAttr> { fs_imp::stat(path) }
 708 }
 709
 710 /// Returns an iterator over the entries within a directory.
 711 ///
 712 /// The iterator will yield instances of `io::Result<DirEntry>`. New errors may
 713 /// be encountered after an iterator is initially constructed.
 714 ///
 715 /// # Examples
 716 ///
 717 /// ```
 718 /// # #![feature(path_ext)]
 719 /// use std::io;
 720 /// use std::fs::{self, PathExt, DirEntry};
 721 /// use std::path::Path;
 722 ///
 723 /// // one possible implementation of fs::walk_dir only visiting files
 724 /// fn visit_dirs(dir: &Path, cb: &mut FnMut(DirEntry)) -> io::Result<()> {
 725 ///     if dir.is_dir() {
 726 ///         for entry in try!(fs::read_dir(dir)) {
 727 ///             let entry = try!(entry);
 728 ///             if entry.path().is_dir() {
 729 ///                 try!(visit_dirs(&entry.path(), cb));
 730 ///             } else {
 731 ///                 cb(entry);
 732 ///             }
 733 ///         }
 734 ///     }
 735 ///     Ok(())
 736 /// }
 737 /// ```
 738 ///
 739 /// # Errors
 740 ///
 741 /// This function will return an error if the provided `path` doesn't exist, if
 742 /// the process lacks permissions to view the contents or if the `path` points
 743 /// at a non-directory file
 744 #[stable(feature = "rust1", since = "1.0.0")]
 745 pub fn read_dir<P: AsRef<Path>>(path: P) -> io::Result<ReadDir> {
 746     fs_imp::readdir(path.as_ref()).map(ReadDir)
 747 }
 748
 749 /// Returns an iterator that will recursively walk the directory structure
 750 /// rooted at `path`.
 751 ///
 752 /// The path given will not be iterated over, and this will perform iteration in
 753 /// some top-down order.  The contents of unreadable subdirectories are ignored.
 754 ///
 755 /// The iterator will yield instances of `io::Result<DirEntry>`. New errors may
 756 /// be encountered after an iterator is initially constructed.
 757 #[unstable(feature = "fs_walk",
 758            reason = "the precise semantics and defaults for a recursive walk \
 759                      may change and this may end up accounting for files such \
 760                      as symlinks differently")]
 761 pub fn walk_dir<P: AsRef<Path>>(path: P) -> io::Result<WalkDir> {
 762     let start = try!(read_dir(path));
 763     Ok(WalkDir { cur: Some(start), stack: Vec::new() })
 764 }
 765
 766 #[unstable(feature = "fs_walk")]
 767 impl Iterator for WalkDir {
 768     type Item = io::Result<DirEntry>;
 769
 770     fn next(&mut self) -> Option<io::Result<DirEntry>> {
 771         loop {
 772             if let Some(ref mut cur) = self.cur {
 773                 match cur.next() {
 774                     Some(Err(e)) => return Some(Err(e)),
 775                     Some(Ok(next)) => {
 776                         let path = next.path();
 777                         if path.is_dir() {
 778                             self.stack.push(read_dir(&*path));
 779                         }
 780                         return Some(Ok(next))
 781                     }
 782                     None => {}
 783                 }
 784             }
 785             self.cur = None;
 786             match self.stack.pop() {
 787                 Some(Err(e)) => return Some(Err(e)),
 788                 Some(Ok(next)) => self.cur = Some(next),
 789                 None => return None,
 790             }
 791         }
 792     }
 793 }
 794
 795 /// Utility methods for paths.
 796 #[unstable(feature = "path_ext",
 797            reason = "the precise set of methods exposed on this trait may \
 798                      change and some methods may be removed")]
 799 pub trait PathExt {
 800     /// Get information on the file, directory, etc at this path.
 801     ///
 802     /// Consult the `fs::stat` documentation for more info.
 803     ///
 804     /// This call preserves identical runtime/error semantics with `file::stat`.
 805     fn metadata(&self) -> io::Result<Metadata>;
 806
 807     /// Boolean value indicator whether the underlying file exists on the local
 808     /// filesystem. Returns false in exactly the cases where `fs::stat` fails.
 809     fn exists(&self) -> bool;
 810
 811     /// Whether the underlying implementation (be it a file path, or something
 812     /// else) points at a "regular file" on the FS. Will return false for paths
 813     /// to non-existent locations or directories or other non-regular files
 814     /// (named pipes, etc). Follows links when making this determination.
 815     fn is_file(&self) -> bool;
 816
 817     /// Whether the underlying implementation (be it a file path, or something
 818     /// else) is pointing at a directory in the underlying FS. Will return
 819     /// false for paths to non-existent locations or if the item is not a
 820     /// directory (eg files, named pipes, etc). Follows links when making this
 821     /// determination.
 822     fn is_dir(&self) -> bool;
 823 }
 824
 825 impl PathExt for Path {
 826     fn metadata(&self) -> io::Result<Metadata> { metadata(self) }
 827
 828     fn exists(&self) -> bool { metadata(self).is_ok() }
 829
 830     fn is_file(&self) -> bool {
 831         metadata(self).map(|s| s.is_file()).unwrap_or(false)
 832     }
 833     fn is_dir(&self) -> bool {
 834         metadata(self).map(|s| s.is_dir()).unwrap_or(false)
 835     }
 836 }
 837
 838 /// Changes the timestamps for a file's last modification and access time.
 839 ///
 840 /// The file at the path specified will have its last access time set to
 841 /// `atime` and its modification time set to `mtime`. The times specified should
 842 /// be in milliseconds.
 843 #[unstable(feature = "fs_time",
 844            reason = "the argument type of u64 is not quite appropriate for \
 845                      this function and may change if the standard library \
 846                      gains a type to represent a moment in time")]
 847 pub fn set_file_times<P: AsRef<Path>>(path: P, accessed: u64,
 848                                  modified: u64) -> io::Result<()> {
 849     fs_imp::utimes(path.as_ref(), accessed, modified)
 850 }
 851
 852 /// Changes the permissions found on a file or a directory.
 853 ///
 854 /// # Examples
 855 ///
 856 /// ```
 857 /// # #![feature(fs)]
 858 /// # fn foo() -> std::io::Result<()> {
 859 /// use std::fs;
 860 ///
 861 /// let mut perms = try!(fs::metadata("foo.txt")).permissions();
 862 /// perms.set_readonly(true);
 863 /// try!(fs::set_permissions("foo.txt", perms));
 864 /// # Ok(())
 865 /// # }
 866 /// ```
 867 ///
 868 /// # Errors
 869 ///
 870 /// This function will return an error if the provided `path` doesn't exist, if
 871 /// the process lacks permissions to change the attributes of the file, or if
 872 /// some other I/O error is encountered.
 873 #[unstable(feature = "fs",
 874            reason = "a more granual ability to set specific permissions may \
 875                      be exposed on the Permissions structure itself and this \
 876                      method may not always exist")]
 877 pub fn set_permissions<P: AsRef<Path>>(path: P, perm: Permissions) -> io::Result<()> {
 878     fs_imp::set_perm(path.as_ref(), perm.0)
 879 }
 880
 881 #[cfg(test)]
 882 mod tests {
 883     #![allow(deprecated)] //rand
 884
 885     use prelude::v1::*;
 886     use io::prelude::*;
 887
 888     use env;
 889     use fs::{self, File, OpenOptions};
 890     use io::{ErrorKind, SeekFrom};
 891     use path::PathBuf;
 892     use path::Path as Path2;
 893     use os;
 894     use rand::{self, StdRng, Rng};
 895     use str;
 896
 897     macro_rules! check { ($e:expr) => (
 898         match $e {
 899             Ok(t) => t,
 900             Err(e) => panic!("{} failed with: {}", stringify!($e), e),
 901         }
 902     ) }
 903
 904     macro_rules! error { ($e:expr, $s:expr) => (
 905         match $e {
 906             Ok(_) => panic!("Unexpected success. Should've been: {:?}", $s),
 907             Err(ref err) => assert!(err.to_string().contains($s),
 908                                     format!("`{}` did not contain `{}`", err, $s))
 909         }
 910     ) }
 911
 912     pub struct TempDir(PathBuf);
 913
 914     impl TempDir {
 915         fn join(&self, path: &str) -> PathBuf {
 916             let TempDir(ref p) = *self;
 917             p.join(path)
 918         }
 919
 920         fn path<'a>(&'a self) -> &'a Path2 {
 921             let TempDir(ref p) = *self;
 922             p
 923         }
 924     }
 925
 926     impl Drop for TempDir {
 927         fn drop(&mut self) {
 928             // Gee, seeing how we're testing the fs module I sure hope that we
 929             // at least implement this correctly!
 930             let TempDir(ref p) = *self;
 931             check!(fs::remove_dir_all(p));
 932         }
 933     }
 934
 935     pub fn tmpdir() -> TempDir {
 936         let p = env::temp_dir();
 937         let ret = p.join(&format!("rust-{}", rand::random::<u32>()));
 938         check!(fs::create_dir(&ret));
 939         TempDir(ret)
 940     }
 941
 942     #[test]
 943     fn file_test_io_smoke_test() {
 944         let message = "it's alright. have a good time";
 945         let tmpdir = tmpdir();
 946         let filename = &tmpdir.join("file_rt_io_file_test.txt");
 947         {
 948             let mut write_stream = check!(File::create(filename));
 949             check!(write_stream.write(message.as_bytes()));
 950         }
 951         {
 952             let mut read_stream = check!(File::open(filename));
 953             let mut read_buf = [0; 1028];
 954             let read_str = match check!(read_stream.read(&mut read_buf)) {
 955                 -1|0 => panic!("shouldn't happen"),
 956                 n => str::from_utf8(&read_buf[..n]).unwrap().to_string()
 957             };
 958             assert_eq!(read_str, message);
 959         }
 960         check!(fs::remove_file(filename));
 961     }
 962
 963     #[test]
 964     fn invalid_path_raises() {
 965         let tmpdir = tmpdir();
 966         let filename = &tmpdir.join("file_that_does_not_exist.txt");
 967         let result = File::open(filename);
 968
 969         if cfg!(unix) {
 970             error!(result, "o such file or directory");
 971         }
 972         // error!(result, "couldn't open path as file");
 973         // error!(result, format!("path={}; mode=open; access=read", filename.display()));
 974     }
 975
 976     #[test]
 977     fn file_test_iounlinking_invalid_path_should_raise_condition() {
 978         let tmpdir = tmpdir();
 979         let filename = &tmpdir.join("file_another_file_that_does_not_exist.txt");
 980
 981         let result = fs::remove_file(filename);
 982
 983         if cfg!(unix) {
 984             error!(result, "o such file or directory");
 985         }
 986         // error!(result, "couldn't unlink path");
 987         // error!(result, format!("path={}", filename.display()));
 988     }
 989
 990     #[test]
 991     fn file_test_io_non_positional_read() {
 992         let message: &str = "ten-four";
 993         let mut read_mem = [0; 8];
 994         let tmpdir = tmpdir();
 995         let filename = &tmpdir.join("file_rt_io_file_test_positional.txt");
 996         {
 997             let mut rw_stream = check!(File::create(filename));
 998             check!(rw_stream.write(message.as_bytes()));
 999         }
1000         {
1001             let mut read_stream = check!(File::open(filename));
1002             {
1003                 let read_buf = &mut read_mem[0..4];
1004                 check!(read_stream.read(read_buf));
1005             }
1006             {
1007                 let read_buf = &mut read_mem[4..8];
1008                 check!(read_stream.read(read_buf));
1009             }
1010         }
1011         check!(fs::remove_file(filename));
1012         let read_str = str::from_utf8(&read_mem).unwrap();
1013         assert_eq!(read_str, message);
1014     }
1015
1016     #[test]
1017     fn file_test_io_seek_and_tell_smoke_test() {
1018         let message = "ten-four";
1019         let mut read_mem = [0; 4];
1020         let set_cursor = 4 as u64;
1021         let mut tell_pos_pre_read;
1022         let mut tell_pos_post_read;
1023         let tmpdir = tmpdir();
1024         let filename = &tmpdir.join("file_rt_io_file_test_seeking.txt");
1025         {
1026             let mut rw_stream = check!(File::create(filename));
1027             check!(rw_stream.write(message.as_bytes()));
1028         }
1029         {
1030             let mut read_stream = check!(File::open(filename));
1031             check!(read_stream.seek(SeekFrom::Start(set_cursor)));
1032             tell_pos_pre_read = check!(read_stream.seek(SeekFrom::Current(0)));
1033             check!(read_stream.read(&mut read_mem));
1034             tell_pos_post_read = check!(read_stream.seek(SeekFrom::Current(0)));
1035         }
1036         check!(fs::remove_file(filename));
1037         let read_str = str::from_utf8(&read_mem).unwrap();
1038         assert_eq!(read_str, &message[4..8]);
1039         assert_eq!(tell_pos_pre_read, set_cursor);
1040         assert_eq!(tell_pos_post_read, message.len() as u64);
1041     }
1042
1043     #[test]
1044     fn file_test_io_seek_and_write() {
1045         let initial_msg =   "food-is-yummy";
1046         let overwrite_msg =    "-the-bar!!";
1047         let final_msg =     "foo-the-bar!!";
1048         let seek_idx = 3;
1049         let mut read_mem = [0; 13];
1050         let tmpdir = tmpdir();
1051         let filename = &tmpdir.join("file_rt_io_file_test_seek_and_write.txt");
1052         {
1053             let mut rw_stream = check!(File::create(filename));
1054             check!(rw_stream.write(initial_msg.as_bytes()));
1055             check!(rw_stream.seek(SeekFrom::Start(seek_idx)));
1056             check!(rw_stream.write(overwrite_msg.as_bytes()));
1057         }
1058         {
1059             let mut read_stream = check!(File::open(filename));
1060             check!(read_stream.read(&mut read_mem));
1061         }
1062         check!(fs::remove_file(filename));
1063         let read_str = str::from_utf8(&read_mem).unwrap();
1064         assert!(read_str == final_msg);
1065     }
1066
1067     #[test]
1068     fn file_test_io_seek_shakedown() {
1069         //                   01234567890123
1070         let initial_msg =   "qwer-asdf-zxcv";
1071         let chunk_one: &str = "qwer";
1072         let chunk_two: &str = "asdf";
1073         let chunk_three: &str = "zxcv";
1074         let mut read_mem = [0; 4];
1075         let tmpdir = tmpdir();
1076         let filename = &tmpdir.join("file_rt_io_file_test_seek_shakedown.txt");
1077         {
1078             let mut rw_stream = check!(File::create(filename));
1079             check!(rw_stream.write(initial_msg.as_bytes()));
1080         }
1081         {
1082             let mut read_stream = check!(File::open(filename));
1083
1084             check!(read_stream.seek(SeekFrom::End(-4)));
1085             check!(read_stream.read(&mut read_mem));
1086             assert_eq!(str::from_utf8(&read_mem).unwrap(), chunk_three);
1087
1088             check!(read_stream.seek(SeekFrom::Current(-9)));
1089             check!(read_stream.read(&mut read_mem));
1090             assert_eq!(str::from_utf8(&read_mem).unwrap(), chunk_two);
1091
1092             check!(read_stream.seek(SeekFrom::Start(0)));
1093             check!(read_stream.read(&mut read_mem));
1094             assert_eq!(str::from_utf8(&read_mem).unwrap(), chunk_one);
1095         }
1096         check!(fs::remove_file(filename));
1097     }
1098
1099     #[test]
1100     fn file_test_stat_is_correct_on_is_file() {
1101         let tmpdir = tmpdir();
1102         let filename = &tmpdir.join("file_stat_correct_on_is_file.txt");
1103         {
1104             let mut opts = OpenOptions::new();
1105             let mut fs = check!(opts.read(true).write(true)
1106                                     .create(true).open(filename));
1107             let msg = "hw";
1108             fs.write(msg.as_bytes()).unwrap();
1109
1110             let fstat_res = check!(fs.metadata());
1111             assert!(fstat_res.is_file());
1112         }
1113         let stat_res_fn = check!(fs::metadata(filename));
1114         assert!(stat_res_fn.is_file());
1115         let stat_res_meth = check!(filename.metadata());
1116         assert!(stat_res_meth.is_file());
1117         check!(fs::remove_file(filename));
1118     }
1119
1120     #[test]
1121     fn file_test_stat_is_correct_on_is_dir() {
1122         let tmpdir = tmpdir();
1123         let filename = &tmpdir.join("file_stat_correct_on_is_dir");
1124         check!(fs::create_dir(filename));
1125         let stat_res_fn = check!(fs::metadata(filename));
1126         assert!(stat_res_fn.is_dir());
1127         let stat_res_meth = check!(filename.metadata());
1128         assert!(stat_res_meth.is_dir());
1129         check!(fs::remove_dir(filename));
1130     }
1131
1132     #[test]
1133     fn file_test_fileinfo_false_when_checking_is_file_on_a_directory() {
1134         let tmpdir = tmpdir();
1135         let dir = &tmpdir.join("fileinfo_false_on_dir");
1136         check!(fs::create_dir(dir));
1137         assert!(dir.is_file() == false);
1138         check!(fs::remove_dir(dir));
1139     }
1140
1141     #[test]
1142     fn file_test_fileinfo_check_exists_before_and_after_file_creation() {
1143         let tmpdir = tmpdir();
1144         let file = &tmpdir.join("fileinfo_check_exists_b_and_a.txt");
1145         check!(check!(File::create(file)).write(b"foo"));
1146         assert!(file.exists());
1147         check!(fs::remove_file(file));
1148         assert!(!file.exists());
1149     }
1150
1151     #[test]
1152     fn file_test_directoryinfo_check_exists_before_and_after_mkdir() {
1153         let tmpdir = tmpdir();
1154         let dir = &tmpdir.join("before_and_after_dir");
1155         assert!(!dir.exists());
1156         check!(fs::create_dir(dir));
1157         assert!(dir.exists());
1158         assert!(dir.is_dir());
1159         check!(fs::remove_dir(dir));
1160         assert!(!dir.exists());
1161     }
1162
1163     #[test]
1164     fn file_test_directoryinfo_readdir() {
1165         let tmpdir = tmpdir();
1166         let dir = &tmpdir.join("di_readdir");
1167         check!(fs::create_dir(dir));
1168         let prefix = "foo";
1169         for n in 0..3 {
1170             let f = dir.join(&format!("{}.txt", n));
1171             let mut w = check!(File::create(&f));
1172             let msg_str = format!("{}{}", prefix, n.to_string());
1173             let msg = msg_str.as_bytes();
1174             check!(w.write(msg));
1175         }
1176         let files = check!(fs::read_dir(dir));
1177         let mut mem = [0; 4];
1178         for f in files {
1179             let f = f.unwrap().path();
1180             {
1181                 let n = f.file_stem().unwrap();
1182                 check!(check!(File::open(&f)).read(&mut mem));
1183                 let read_str = str::from_utf8(&mem).unwrap();
1184                 let expected = format!("{}{}", prefix, n.to_str().unwrap());
1185                 assert_eq!(expected, read_str);
1186             }
1187             check!(fs::remove_file(&f));
1188         }
1189         check!(fs::remove_dir(dir));
1190     }
1191
1192     #[test]
1193     fn file_test_walk_dir() {
1194         let tmpdir = tmpdir();
1195         let dir = &tmpdir.join("walk_dir");
1196         check!(fs::create_dir(dir));
1197
1198         let dir1 = &dir.join("01/02/03");
1199         check!(fs::create_dir_all(dir1));
1200         check!(File::create(&dir1.join("04")));
1201
1202         let dir2 = &dir.join("11/12/13");
1203         check!(fs::create_dir_all(dir2));
1204         check!(File::create(&dir2.join("14")));
1205
1206         let files = check!(fs::walk_dir(dir));
1207         let mut cur = [0; 2];
1208         for f in files {
1209             let f = f.unwrap().path();
1210             let stem = f.file_stem().unwrap().to_str().unwrap();
1211             let root = stem.as_bytes()[0] - b'0';
1212             let name = stem.as_bytes()[1] - b'0';
1213             assert!(cur[root as usize] < name);
1214             cur[root as usize] = name;
1215         }
1216
1217         check!(fs::remove_dir_all(dir));
1218     }
1219
1220     #[test]
1221     fn mkdir_path_already_exists_error() {
1222         let tmpdir = tmpdir();
1223         let dir = &tmpdir.join("mkdir_error_twice");
1224         check!(fs::create_dir(dir));
1225         let e = fs::create_dir(dir).err().unwrap();
1226         assert_eq!(e.kind(), ErrorKind::AlreadyExists);
1227     }
1228
1229     #[test]
1230     fn recursive_mkdir() {
1231         let tmpdir = tmpdir();
1232         let dir = tmpdir.join("d1/d2");
1233         check!(fs::create_dir_all(&dir));
1234         assert!(dir.is_dir())
1235     }
1236
1237     #[test]
1238     fn recursive_mkdir_failure() {
1239         let tmpdir = tmpdir();
1240         let dir = tmpdir.join("d1");
1241         let file = dir.join("f1");
1242
1243         check!(fs::create_dir_all(&dir));
1244         check!(File::create(&file));
1245
1246         let result = fs::create_dir_all(&file);
1247
1248         assert!(result.is_err());
1249         // error!(result, "couldn't recursively mkdir");
1250         // error!(result, "couldn't create directory");
1251         // error!(result, "mode=0700");
1252         // error!(result, format!("path={}", file.display()));
1253     }
1254
1255     #[test]
1256     fn recursive_mkdir_slash() {
1257         check!(fs::create_dir_all(&Path2::new("/")));
1258     }
1259
1260     // FIXME(#12795) depends on lstat to work on windows
1261     #[cfg(not(windows))]
1262     #[test]
1263     fn recursive_rmdir() {
1264         let tmpdir = tmpdir();
1265         let d1 = tmpdir.join("d1");
1266         let dt = d1.join("t");
1267         let dtt = dt.join("t");
1268         let d2 = tmpdir.join("d2");
1269         let canary = d2.join("do_not_delete");
1270         check!(fs::create_dir_all(&dtt));
1271         check!(fs::create_dir_all(&d2));
1272         check!(check!(File::create(&canary)).write(b"foo"));
1273         check!(fs::soft_link(&d2, &dt.join("d2")));
1274         check!(fs::remove_dir_all(&d1));
1275
1276         assert!(!d1.is_dir());
1277         assert!(canary.exists());
1278     }
1279
1280     #[test]
1281     fn unicode_path_is_dir() {
1282         assert!(Path2::new(".").is_dir());
1283         assert!(!Path2::new("test/stdtest/fs.rs").is_dir());
1284
1285         let tmpdir = tmpdir();
1286
1287         let mut dirpath = tmpdir.path().to_path_buf();
1288         dirpath.push(&format!("test-가一ー你好"));
1289         check!(fs::create_dir(&dirpath));
1290         assert!(dirpath.is_dir());
1291
1292         let mut filepath = dirpath;
1293         filepath.push("unicode-file-\u{ac00}\u{4e00}\u{30fc}\u{4f60}\u{597d}.rs");
1294         check!(File::create(&filepath)); // ignore return; touch only
1295         assert!(!filepath.is_dir());
1296         assert!(filepath.exists());
1297     }
1298
1299     #[test]
1300     fn unicode_path_exists() {
1301         assert!(Path2::new(".").exists());
1302         assert!(!Path2::new("test/nonexistent-bogus-path").exists());
1303
1304         let tmpdir = tmpdir();
1305         let unicode = tmpdir.path();
1306         let unicode = unicode.join(&format!("test-각丁ー再见"));
1307         check!(fs::create_dir(&unicode));
1308         assert!(unicode.exists());
1309         assert!(!Path2::new("test/unicode-bogus-path-각丁ー再见").exists());
1310     }
1311
1312     #[test]
1313     fn copy_file_does_not_exist() {
1314         let from = Path2::new("test/nonexistent-bogus-path");
1315         let to = Path2::new("test/other-bogus-path");
1316
1317         match fs::copy(&from, &to) {
1318             Ok(..) => panic!(),
1319             Err(..) => {
1320                 assert!(!from.exists());
1321                 assert!(!to.exists());
1322             }
1323         }
1324     }
1325
1326     #[test]
1327     fn copy_file_ok() {
1328         let tmpdir = tmpdir();
1329         let input = tmpdir.join("in.txt");
1330         let out = tmpdir.join("out.txt");
1331
1332         check!(check!(File::create(&input)).write(b"hello"));
1333         check!(fs::copy(&input, &out));
1334         let mut v = Vec::new();
1335         check!(check!(File::open(&out)).read_to_end(&mut v));
1336         assert_eq!(v.as_slice(), b"hello");
1337
1338         assert_eq!(check!(input.metadata()).permissions(),
1339                    check!(out.metadata()).permissions());
1340     }
1341
1342     #[test]
1343     fn copy_file_dst_dir() {
1344         let tmpdir = tmpdir();
1345         let out = tmpdir.join("out");
1346
1347         check!(File::create(&out));
1348         match fs::copy(&*out, tmpdir.path()) {
1349             Ok(..) => panic!(), Err(..) => {}
1350         }
1351     }
1352
1353     #[test]
1354     fn copy_file_dst_exists() {
1355         let tmpdir = tmpdir();
1356         let input = tmpdir.join("in");
1357         let output = tmpdir.join("out");
1358
1359         check!(check!(File::create(&input)).write("foo".as_bytes()));
1360         check!(check!(File::create(&output)).write("bar".as_bytes()));
1361         check!(fs::copy(&input, &output));
1362
1363         let mut v = Vec::new();
1364         check!(check!(File::open(&output)).read_to_end(&mut v));
1365         assert_eq!(v, b"foo".to_vec());
1366     }
1367
1368     #[test]
1369     fn copy_file_src_dir() {
1370         let tmpdir = tmpdir();
1371         let out = tmpdir.join("out");
1372
1373         match fs::copy(tmpdir.path(), &out) {
1374             Ok(..) => panic!(), Err(..) => {}
1375         }
1376         assert!(!out.exists());
1377     }
1378
1379     #[test]
1380     fn copy_file_preserves_perm_bits() {
1381         let tmpdir = tmpdir();
1382         let input = tmpdir.join("in.txt");
1383         let out = tmpdir.join("out.txt");
1384
1385         let attr = check!(check!(File::create(&input)).metadata());
1386         let mut p = attr.permissions();
1387         p.set_readonly(true);
1388         check!(fs::set_permissions(&input, p));
1389         check!(fs::copy(&input, &out));
1390         assert!(check!(out.metadata()).permissions().readonly());
1391         check!(fs::set_permissions(&input, attr.permissions()));
1392         check!(fs::set_permissions(&out, attr.permissions()));
1393     }
1394
1395     #[cfg(not(windows))] // FIXME(#10264) operation not permitted?
1396     #[test]
1397     fn symlinks_work() {
1398         let tmpdir = tmpdir();
1399         let input = tmpdir.join("in.txt");
1400         let out = tmpdir.join("out.txt");
1401
1402         check!(check!(File::create(&input)).write("foobar".as_bytes()));
1403         check!(fs::soft_link(&input, &out));
1404         // if cfg!(not(windows)) {
1405         //     assert_eq!(check!(lstat(&out)).kind, FileType::Symlink);
1406         //     assert_eq!(check!(out.lstat()).kind, FileType::Symlink);
1407         // }
1408         assert_eq!(check!(fs::metadata(&out)).len(),
1409                    check!(fs::metadata(&input)).len());
1410         let mut v = Vec::new();
1411         check!(check!(File::open(&out)).read_to_end(&mut v));
1412         assert_eq!(v, b"foobar".to_vec());
1413     }
1414
1415     #[cfg(not(windows))] // apparently windows doesn't like symlinks
1416     #[test]
1417     fn symlink_noexist() {
1418         let tmpdir = tmpdir();
1419         // symlinks can point to things that don't exist
1420         check!(fs::soft_link(&tmpdir.join("foo"), &tmpdir.join("bar")));
1421         assert_eq!(check!(fs::read_link(&tmpdir.join("bar"))),
1422                    tmpdir.join("foo"));
1423     }
1424
1425     #[test]
1426     fn readlink_not_symlink() {
1427         let tmpdir = tmpdir();
1428         match fs::read_link(tmpdir.path()) {
1429             Ok(..) => panic!("wanted a failure"),
1430             Err(..) => {}
1431         }
1432     }
1433
1434     #[test]
1435     fn links_work() {
1436         let tmpdir = tmpdir();
1437         let input = tmpdir.join("in.txt");
1438         let out = tmpdir.join("out.txt");
1439
1440         check!(check!(File::create(&input)).write("foobar".as_bytes()));
1441         check!(fs::hard_link(&input, &out));
1442         assert_eq!(check!(fs::metadata(&out)).len(),
1443                    check!(fs::metadata(&input)).len());
1444         assert_eq!(check!(fs::metadata(&out)).len(),
1445                    check!(input.metadata()).len());
1446         let mut v = Vec::new();
1447         check!(check!(File::open(&out)).read_to_end(&mut v));
1448         assert_eq!(v, b"foobar".to_vec());
1449
1450         // can't link to yourself
1451         match fs::hard_link(&input, &input) {
1452             Ok(..) => panic!("wanted a failure"),
1453             Err(..) => {}
1454         }
1455         // can't link to something that doesn't exist
1456         match fs::hard_link(&tmpdir.join("foo"), &tmpdir.join("bar")) {
1457             Ok(..) => panic!("wanted a failure"),
1458             Err(..) => {}
1459         }
1460     }
1461
1462     #[test]
1463     fn chmod_works() {
1464         let tmpdir = tmpdir();
1465         let file = tmpdir.join("in.txt");
1466
1467         check!(File::create(&file));
1468         let attr = check!(fs::metadata(&file));
1469         assert!(!attr.permissions().readonly());
1470         let mut p = attr.permissions();
1471         p.set_readonly(true);
1472         check!(fs::set_permissions(&file, p.clone()));
1473         let attr = check!(fs::metadata(&file));
1474         assert!(attr.permissions().readonly());
1475
1476         match fs::set_permissions(&tmpdir.join("foo"), p.clone()) {
1477             Ok(..) => panic!("wanted an error"),
1478             Err(..) => {}
1479         }
1480
1481         p.set_readonly(false);
1482         check!(fs::set_permissions(&file, p));
1483     }
1484
1485     #[test]
1486     fn sync_doesnt_kill_anything() {
1487         let tmpdir = tmpdir();
1488         let path = tmpdir.join("in.txt");
1489
1490         let mut file = check!(File::create(&path));
1491         check!(file.sync_all());
1492         check!(file.sync_data());
1493         check!(file.write(b"foo"));
1494         check!(file.sync_all());
1495         check!(file.sync_data());
1496     }
1497
1498     #[test]
1499     fn truncate_works() {
1500         let tmpdir = tmpdir();
1501         let path = tmpdir.join("in.txt");
1502
1503         let mut file = check!(File::create(&path));
1504         check!(file.write(b"foo"));
1505         check!(file.sync_all());
1506
1507         // Do some simple things with truncation
1508         assert_eq!(check!(file.metadata()).len(), 3);
1509         check!(file.set_len(10));
1510         assert_eq!(check!(file.metadata()).len(), 10);
1511         check!(file.write(b"bar"));
1512         check!(file.sync_all());
1513         assert_eq!(check!(file.metadata()).len(), 10);
1514
1515         let mut v = Vec::new();
1516         check!(check!(File::open(&path)).read_to_end(&mut v));
1517         assert_eq!(v, b"foobar\0\0\0\0".to_vec());
1518
1519         // Truncate to a smaller length, don't seek, and then write something.
1520         // Ensure that the intermediate zeroes are all filled in (we have `seek`ed
1521         // past the end of the file).
1522         check!(file.set_len(2));
1523         assert_eq!(check!(file.metadata()).len(), 2);
1524         check!(file.write(b"wut"));
1525         check!(file.sync_all());
1526         assert_eq!(check!(file.metadata()).len(), 9);
1527         let mut v = Vec::new();
1528         check!(check!(File::open(&path)).read_to_end(&mut v));
1529         assert_eq!(v, b"fo\0\0\0\0wut".to_vec());
1530     }
1531
1532     #[test]
1533     fn open_flavors() {
1534         use fs::OpenOptions as OO;
1535         fn c<T: Clone>(t: &T) -> T { t.clone() }
1536
1537         let tmpdir = tmpdir();
1538
1539         let mut r = OO::new(); r.read(true);
1540         let mut w = OO::new(); w.write(true);
1541         let mut rw = OO::new(); rw.write(true).read(true);
1542
1543         match r.open(&tmpdir.join("a")) {
1544             Ok(..) => panic!(), Err(..) => {}
1545         }
1546
1547         // Perform each one twice to make sure that it succeeds the second time
1548         // (where the file exists)
1549         check!(c(&w).create(true).open(&tmpdir.join("b")));
1550         assert!(tmpdir.join("b").exists());
1551         check!(c(&w).create(true).open(&tmpdir.join("b")));
1552         check!(w.open(&tmpdir.join("b")));
1553
1554         check!(c(&rw).create(true).open(&tmpdir.join("c")));
1555         assert!(tmpdir.join("c").exists());
1556         check!(c(&rw).create(true).open(&tmpdir.join("c")));
1557         check!(rw.open(&tmpdir.join("c")));
1558
1559         check!(c(&w).append(true).create(true).open(&tmpdir.join("d")));
1560         assert!(tmpdir.join("d").exists());
1561         check!(c(&w).append(true).create(true).open(&tmpdir.join("d")));
1562         check!(c(&w).append(true).open(&tmpdir.join("d")));
1563
1564         check!(c(&rw).append(true).create(true).open(&tmpdir.join("e")));
1565         assert!(tmpdir.join("e").exists());
1566         check!(c(&rw).append(true).create(true).open(&tmpdir.join("e")));
1567         check!(c(&rw).append(true).open(&tmpdir.join("e")));
1568
1569         check!(c(&w).truncate(true).create(true).open(&tmpdir.join("f")));
1570         assert!(tmpdir.join("f").exists());
1571         check!(c(&w).truncate(true).create(true).open(&tmpdir.join("f")));
1572         check!(c(&w).truncate(true).open(&tmpdir.join("f")));
1573
1574         check!(c(&rw).truncate(true).create(true).open(&tmpdir.join("g")));
1575         assert!(tmpdir.join("g").exists());
1576         check!(c(&rw).truncate(true).create(true).open(&tmpdir.join("g")));
1577         check!(c(&rw).truncate(true).open(&tmpdir.join("g")));
1578
1579         check!(check!(File::create(&tmpdir.join("h"))).write("foo".as_bytes()));
1580         check!(r.open(&tmpdir.join("h")));
1581         {
1582             let mut f = check!(r.open(&tmpdir.join("h")));
1583             assert!(f.write("wut".as_bytes()).is_err());
1584         }
1585         assert_eq!(check!(fs::metadata(&tmpdir.join("h"))).len(), 3);
1586         {
1587             let mut f = check!(c(&w).append(true).open(&tmpdir.join("h")));
1588             check!(f.write("bar".as_bytes()));
1589         }
1590         assert_eq!(check!(fs::metadata(&tmpdir.join("h"))).len(), 6);
1591         {
1592             let mut f = check!(c(&w).truncate(true).open(&tmpdir.join("h")));
1593             check!(f.write("bar".as_bytes()));
1594         }
1595         assert_eq!(check!(fs::metadata(&tmpdir.join("h"))).len(), 3);
1596     }
1597
1598     #[test]
1599     fn utime() {
1600         let tmpdir = tmpdir();
1601         let path = tmpdir.join("a");
1602         check!(File::create(&path));
1603         // These numbers have to be bigger than the time in the day to account
1604         // for timezones Windows in particular will fail in certain timezones
1605         // with small enough values
1606         check!(fs::set_file_times(&path, 100000, 200000));
1607         assert_eq!(check!(path.metadata()).accessed(), 100000);
1608         assert_eq!(check!(path.metadata()).modified(), 200000);
1609     }
1610
1611     #[test]
1612     fn utime_noexist() {
1613         let tmpdir = tmpdir();
1614
1615         match fs::set_file_times(&tmpdir.join("a"), 100, 200) {
1616             Ok(..) => panic!(),
1617             Err(..) => {}
1618         }
1619     }
1620
1621     #[test]
1622     fn binary_file() {
1623         let mut bytes = [0; 1024];
1624         StdRng::new().unwrap().fill_bytes(&mut bytes);
1625
1626         let tmpdir = tmpdir();
1627
1628         check!(check!(File::create(&tmpdir.join("test"))).write(&bytes));
1629         let mut v = Vec::new();
1630         check!(check!(File::open(&tmpdir.join("test"))).read_to_end(&mut v));
1631         assert!(v == bytes.as_slice());
1632     }
1633
1634     #[test]
1635     #[cfg(not(windows))]
1636     fn unlink_readonly() {
1637         let tmpdir = tmpdir();
1638         let path = tmpdir.join("file");
1639         check!(File::create(&path));
1640         let mut perm = check!(fs::metadata(&path)).permissions();
1641         perm.set_readonly(true);
1642         check!(fs::set_permissions(&path, perm));
1643         check!(fs::remove_file(&path));
1644     }
1645
1646     #[test]
1647     fn mkdir_trailing_slash() {
1648         let tmpdir = tmpdir();
1649         let path = tmpdir.join("file");
1650         check!(fs::create_dir_all(&path.join("a/")));
1651     }
1652 }