may change and this may end up accounting for files such \
as symlinks differently",
issue = "27707")]
+#[rustc_deprecated(reason = "superceded by the walkdir crate",
+ since = "1.6.0")]
pub struct WalkDir {
cur: Option<ReadDir>,
stack: Vec<io::Result<ReadDir>>,
/// A builder used to create directories in various manners.
///
/// This builder also supports platform-specific options.
-#[unstable(feature = "dir_builder", reason = "recently added API",
- issue = "27710")]
+#[stable(feature = "dir_builder", since = "1.6.0")]
pub struct DirBuilder {
inner: fs_imp::DirBuilder,
recursive: bool,
/// guarantee that the file is immediately deleted (e.g. depending on
/// platform, other open file descriptors may prevent immediate removal).
///
+/// # Platform behavior
+///
+/// This function currently corresponds to the `unlink` function on Unix
+/// and the `DeleteFile` function on Windows.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
/// # Errors
///
-/// This function will return an error if `path` points to a directory, if the
-/// user lacks permissions to remove the file, or if some other filesystem-level
-/// error occurs.
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * `path` points to a directory.
+/// * The user lacks permissions to remove the file.
///
/// # Examples
///
/// This function will traverse symbolic links to query information about the
/// destination file.
///
+/// # Platform behavior
+///
+/// This function currently corresponds to the `stat` function on Unix
+/// and the `GetFileAttributesEx` function on Windows.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * The user lacks permissions to perform `metadata` call on `path`.
+/// * `path` does not exist.
+///
/// # Examples
///
/// ```rust
/// # Ok(())
/// # }
/// ```
-///
-/// # Errors
-///
-/// This function will return an error if the user lacks the requisite
-/// permissions to perform a `metadata` call on the given `path` or if there
-/// is no entry in the filesystem at the provided path.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
fs_imp::stat(path.as_ref()).map(Metadata)
/// Query the metadata about a file without following symlinks.
///
+/// # Platform behavior
+///
+/// This function currently corresponds to the `lstat` function on Unix
+/// and the `GetFileAttributesEx` function on Windows.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * The user lacks permissions to perform `metadata` call on `path`.
+/// * `path` does not exist.
+///
/// # Examples
///
/// ```rust
///
/// This will not work if the new name is on a different mount point.
///
+/// # Platform behavior
+///
+/// This function currently corresponds to the `rename` function on Unix
+/// and the `MoveFileEx` function with the `MOVEFILE_REPLACE_EXISTING` flag on Windows.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
/// # Errors
///
-/// This function will return an error if the provided `from` doesn't exist, if
-/// the process lacks permissions to view the contents, if `from` and `to`
-/// reside on separate filesystems, or if some other intermittent I/O error
-/// occurs.
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * `from` does not exist.
+/// * The user lacks permissions to view contents.
+/// * `from` and `to` are on separate filesystems.
///
/// # Examples
///
/// use std::fs;
///
/// # fn foo() -> std::io::Result<()> {
-/// try!(fs::rename("a.txt", "b.txt"));
+/// try!(fs::rename("a.txt", "b.txt")); // Rename a.txt to b.txt
/// # Ok(())
/// # }
/// ```
///
/// On success, the total number of bytes copied is returned.
///
+/// # Platform behavior
+///
+/// This function currently corresponds to the `open` function in Unix
+/// with `O_RDONLY` for `from` and `O_WRONLY`, `O_CREAT`, and `O_TRUNC` for `to`.
+/// `O_CLOEXEC` is set for returned file descriptors.
+/// On Windows, this function currently corresponds to `CopyFileEx`.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
/// # Errors
///
/// This function will return an error in the following situations, but is not
/// limited to just these cases:
///
-/// * The `from` path is not a file
-/// * The `from` file does not exist
+/// * The `from` path is not a file.
+/// * The `from` file does not exist.
/// * The current process does not have the permission rights to access
-/// `from` or write `to`
+/// `from` or write `to`.
///
/// # Examples
///
/// use std::fs;
///
/// # fn foo() -> std::io::Result<()> {
-/// try!(fs::copy("foo.txt", "bar.txt"));
+/// try!(fs::copy("foo.txt", "bar.txt")); // Copy foo.txt to bar.txt
/// # Ok(()) }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
/// The `dst` path will be a link pointing to the `src` path. Note that systems
/// often require these two paths to both be located on the same filesystem.
///
+/// # Platform behavior
+///
+/// This function currently corresponds to the `link` function on Unix
+/// and the `CreateHardLink` function on Windows.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * The `src` path is not a file or doesn't exist.
+///
/// # Examples
///
/// ```
/// use std::fs;
///
/// # fn foo() -> std::io::Result<()> {
-/// try!(fs::hard_link("a.txt", "b.txt"));
+/// try!(fs::hard_link("a.txt", "b.txt")); // Hard link a.txt to b.txt
/// # Ok(())
/// # }
/// ```
/// # Ok(())
/// # }
/// ```
+#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_deprecated(since = "1.1.0",
reason = "replaced with std::os::unix::fs::symlink and \
std::os::windows::fs::{symlink_file, symlink_dir}")]
-#[stable(feature = "rust1", since = "1.0.0")]
pub fn soft_link<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()> {
fs_imp::symlink(src.as_ref(), dst.as_ref())
}
/// Reads a symbolic link, returning the file that the link points to.
///
+/// # Platform behavior
+///
+/// This function currently corresponds to the `readlink` function on Unix
+/// and the `CreateFile` function with `FILE_FLAG_OPEN_REPARSE_POINT` and
+/// `FILE_FLAG_BACKUP_SEMANTICS` flags on Windows.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
/// # Errors
///
-/// This function will return an error on failure. Failure conditions include
-/// reading a file that does not exist or reading a file that is not a symbolic
-/// link.
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * `path` is not a symbolic link.
+/// * `path` does not exist.
///
/// # Examples
///
/// Returns the canonical form of a path with all intermediate components
/// normalized and symbolic links resolved.
///
-/// This function may return an error in situations like where the path does not
-/// exist, a component in the path is not a directory, or an I/O error happens.
+/// # Platform behavior
+///
+/// This function currently corresponds to the `realpath` function on Unix
+/// and the `CreateFile` and `GetFinalPathNameByHandle` functions on Windows.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * `path` does not exist.
+/// * A component in path is not a directory.
///
/// # Examples
///
/// Creates a new, empty directory at the provided path
///
+/// # Platform behavior
+///
+/// This function currently corresponds to the `mkdir` function on Unix
+/// and the `CreateDirectory` function on Windows.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
/// # Errors
///
-/// This function will return an error if the user lacks permissions to make a
-/// new directory at the provided `path`, or if the directory already exists.
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * User lacks permissions to create directory at `path`.
+/// * `path` already exists.
///
/// # Examples
///
/// Recursively create a directory and all of its parent components if they
/// are missing.
///
+/// # Platform behavior
+///
+/// This function currently corresponds to the `mkdir` function on Unix
+/// and the `CreateDirectory` function on Windows.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
/// # Errors
///
-/// This function will fail if any directory in the path specified by `path`
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * If any directory in the path specified by `path`
/// does not already exist and it could not be created otherwise. The specific
/// error conditions for when a directory is being created (after it is
/// determined to not exist) are outlined by `fs::create_dir`.
/// Removes an existing, empty directory.
///
+/// # Platform behavior
+///
+/// This function currently corresponds to the `rmdir` function on Unix
+/// and the `RemoveDirectory` function on Windows.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
/// # Errors
///
-/// This function will return an error if the user lacks permissions to remove
-/// the directory at the provided `path`, or if the directory isn't empty.
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * The user lacks permissions to remove the directory at the provided `path`.
+/// * The directory isn't empty.
///
/// # Examples
///
/// This function does **not** follow symbolic links and it will simply remove the
/// symbolic link itself.
///
+/// # Platform behavior
+///
+/// This function currently corresponds to `opendir`, `lstat`, `rm` and `rmdir` functions on Unix
+/// and the `FindFirstFile`, `GetFileAttributesEx`, `DeleteFile`, and `RemoveDirectory` functions
+/// on Windows.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
/// # Errors
///
/// See `file::remove_file` and `fs::remove_dir`.
/// The iterator will yield instances of `io::Result<DirEntry>`. New errors may
/// be encountered after an iterator is initially constructed.
///
+/// # Platform behavior
+///
+/// This function currently corresponds to the `opendir` function on Unix
+/// and the `FindFirstFile` function on Windows.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * The provided `path` doesn't exist.
+/// * The process lacks permissions to view the contents.
+/// * The `path` points at a non-directory file.
+///
/// # Examples
///
/// ```
/// Ok(())
/// }
/// ```
-///
-/// # Errors
-///
-/// This function will return an error if the provided `path` doesn't exist, if
-/// the process lacks permissions to view the contents or if the `path` points
-/// at a non-directory file
#[stable(feature = "rust1", since = "1.0.0")]
pub fn read_dir<P: AsRef<Path>>(path: P) -> io::Result<ReadDir> {
fs_imp::readdir(path.as_ref()).map(ReadDir)
may change and this may end up accounting for files such \
as symlinks differently",
issue = "27707")]
+#[rustc_deprecated(reason = "superceded by the walkdir crate",
+ since = "1.6.0")]
+#[allow(deprecated)]
pub fn walk_dir<P: AsRef<Path>>(path: P) -> io::Result<WalkDir> {
_walk_dir(path.as_ref())
}
+#[allow(deprecated)]
fn _walk_dir(path: &Path) -> io::Result<WalkDir> {
let start = try!(read_dir(path));
Ok(WalkDir { cur: Some(start), stack: Vec::new() })
}
#[unstable(feature = "fs_walk", issue = "27707")]
+#[rustc_deprecated(reason = "superceded by the walkdir crate",
+ since = "1.6.0")]
+#[allow(deprecated)]
impl Iterator for WalkDir {
type Item = io::Result<DirEntry>;
}
}
-/// Utility methods for paths.
-#[unstable(feature = "path_ext_deprecated",
- reason = "The precise set of methods exposed on this trait may \
- change and some methods may be removed. For stable code, \
- see the std::fs::metadata function.",
- issue = "27725")]
-#[rustc_deprecated(since = "1.5.0", reason = "replaced with inherent methods")]
-pub trait PathExt {
- /// Gets information on the file, directory, etc at this path.
- ///
- /// Consult the `fs::metadata` documentation for more info.
- ///
- /// This call preserves identical runtime/error semantics with
- /// `fs::metadata`.
- fn metadata(&self) -> io::Result<Metadata>;
-
- /// Gets information on the file, directory, etc at this path.
- ///
- /// Consult the `fs::symlink_metadata` documentation for more info.
- ///
- /// This call preserves identical runtime/error semantics with
- /// `fs::symlink_metadata`.
- fn symlink_metadata(&self) -> io::Result<Metadata>;
-
- /// Returns the canonical form of a path, normalizing all components and
- /// eliminate all symlinks.
- ///
- /// This call preserves identical runtime/error semantics with
- /// `fs::canonicalize`.
- fn canonicalize(&self) -> io::Result<PathBuf>;
-
- /// Reads the symlink at this path.
- ///
- /// For more information see `fs::read_link`.
- fn read_link(&self) -> io::Result<PathBuf>;
-
- /// Reads the directory at this path.
- ///
- /// For more information see `fs::read_dir`.
- fn read_dir(&self) -> io::Result<ReadDir>;
-
- /// Boolean value indicator whether the underlying file exists on the local
- /// filesystem. Returns false in exactly the cases where `fs::metadata`
- /// fails.
- fn exists(&self) -> bool;
-
- /// Whether the underlying implementation (be it a file path, or something
- /// else) points at a "regular file" on the FS. Will return false for paths
- /// to non-existent locations or directories or other non-regular files
- /// (named pipes, etc). Follows links when making this determination.
- fn is_file(&self) -> bool;
-
- /// Whether the underlying implementation (be it a file path, or something
- /// else) is pointing at a directory in the underlying FS. Will return
- /// false for paths to non-existent locations or if the item is not a
- /// directory (eg files, named pipes, etc). Follows links when making this
- /// determination.
- fn is_dir(&self) -> bool;
-}
-
-#[allow(deprecated)]
-#[unstable(feature = "path_ext_deprecated", issue = "27725")]
-impl PathExt for Path {
- fn metadata(&self) -> io::Result<Metadata> { metadata(self) }
- fn symlink_metadata(&self) -> io::Result<Metadata> { symlink_metadata(self) }
- fn canonicalize(&self) -> io::Result<PathBuf> { canonicalize(self) }
- fn read_link(&self) -> io::Result<PathBuf> { read_link(self) }
- fn read_dir(&self) -> io::Result<ReadDir> { read_dir(self) }
- fn exists(&self) -> bool { metadata(self).is_ok() }
-
- fn is_file(&self) -> bool {
- metadata(self).map(|s| s.is_file()).unwrap_or(false)
- }
-
- fn is_dir(&self) -> bool {
- metadata(self).map(|s| s.is_dir()).unwrap_or(false)
- }
-}
-
/// Changes the permissions found on a file or a directory.
///
+/// # Platform behavior
+///
+/// This function currently corresponds to the `chmod` function on Unix
+/// and the `SetFileAttributes` function on Windows.
+/// Note that, this [may change in the future][changes].
+/// [changes]: https://github.com/rust-lang/rust/pull/28613
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * `path` does not exist.
+/// * The user lacks the permission to change attributes of the file.
+///
/// # Examples
///
/// ```
/// # Ok(())
/// # }
/// ```
-///
-/// # Errors
-///
-/// This function will return an error if the provided `path` doesn't exist, if
-/// the process lacks permissions to change the attributes of the file, or if
-/// some other I/O error is encountered.
#[stable(feature = "set_permissions", since = "1.1.0")]
pub fn set_permissions<P: AsRef<Path>>(path: P, perm: Permissions)
-> io::Result<()> {
fs_imp::set_perm(path.as_ref(), perm.0)
}
-#[unstable(feature = "dir_builder", reason = "recently added API",
- issue = "27710")]
impl DirBuilder {
/// Creates a new set of options with default mode/security settings for all
/// platforms and also non-recursive.
+ #[stable(feature = "dir_builder", since = "1.6.0")]
pub fn new() -> DirBuilder {
DirBuilder {
inner: fs_imp::DirBuilder::new(),
/// permissions settings.
///
/// This option defaults to `false`
+ #[stable(feature = "dir_builder", since = "1.6.0")]
pub fn recursive(&mut self, recursive: bool) -> &mut Self {
self.recursive = recursive;
self
/// # Examples
///
/// ```no_run
- /// #![feature(dir_builder)]
/// use std::fs::{self, DirBuilder};
///
/// let path = "/tmp/foo/bar/baz";
///
/// assert!(fs::metadata(path).unwrap().is_dir());
/// ```
+ #[stable(feature = "dir_builder", since = "1.6.0")]
pub fn create<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
self._create(path.as_ref())
}
use io::{ErrorKind, SeekFrom};
use path::PathBuf;
use path::Path as Path2;
- use os;
use rand::{self, StdRng, Rng};
use str;
let message = "ten-four";
let mut read_mem = [0; 4];
let set_cursor = 4 as u64;
- let mut tell_pos_pre_read;
- let mut tell_pos_post_read;
+ let tell_pos_pre_read;
+ let tell_pos_post_read;
let tmpdir = tmpdir();
let filename = &tmpdir.join("file_rt_io_file_test_seeking.txt");
{