Revision control
Copy as Markdown
Other Tools
/*!
This crate provides a safe and simple **cross platform** way to determine
whether two file paths refer to the same file or directory.
Most uses of this crate should be limited to the top-level [`is_same_file`]
function, which takes two file paths and returns true if they refer to the
same file or directory:
```rust,no_run
# use std::error::Error;
use same_file::is_same_file;
# fn try_main() -> Result<(), Box<Error>> {
assert!(is_same_file("/bin/sh", "/usr/bin/sh")?);
# Ok(())
# }
#
# fn main() {
# try_main().unwrap();
# }
```
Additionally, this crate provides a [`Handle`] type that permits a more efficient
equality check depending on your access pattern. For example, if one wanted to
check whether any path in a list of paths corresponded to the process' stdout
handle, then one could build a handle once for stdout. The equality check for
each file in the list then only requires one stat call instead of two. The code
might look like this:
```rust,no_run
# use std::error::Error;
use same_file::Handle;
# fn try_main() -> Result<(), Box<Error>> {
let candidates = &[
"examples/is_same_file.rs",
"examples/is_stderr.rs",
"examples/stderr",
];
let stdout_handle = Handle::stdout()?;
for candidate in candidates {
let handle = Handle::from_path(candidate)?;
if stdout_handle == handle {
println!("{:?} is stdout!", candidate);
} else {
println!("{:?} is NOT stdout!", candidate);
}
}
# Ok(())
# }
#
# fn main() {
# try_main().unwrap();
# }
```
See [`examples/is_stderr.rs`] for a runnable example and compare the output of:
- `cargo run --example is_stderr 2> examples/stderr` and
- `cargo run --example is_stderr`.
[`is_same_file`]: fn.is_same_file.html
[`Handle`]: struct.Handle.html
[`examples/is_stderr.rs`]: https://github.com/BurntSushi/same-file/blob/master/examples/is_same_file.rs
*/
#![allow(bare_trait_objects, unknown_lints)]
#![deny(missing_docs)]
#[cfg(test)]
doc_comment::doctest!("../README.md");
use std::fs::File;
use std::io;
use std::path::Path;
#[cfg(any(target_os = "redox", unix))]
use crate::unix as imp;
#[cfg(not(any(target_os = "redox", unix, windows)))]
use unknown as imp;
#[cfg(windows)]
use win as imp;
#[cfg(any(target_os = "redox", unix))]
mod unix;
#[cfg(not(any(target_os = "redox", unix, windows)))]
mod unknown;
#[cfg(windows)]
mod win;
/// A handle to a file that can be tested for equality with other handles.
///
/// If two files are the same, then any two handles of those files will compare
/// equal. If two files are not the same, then any two handles of those files
/// will compare not-equal.
///
/// A handle consumes an open file resource as long as it exists.
///
/// Equality is determined by comparing inode numbers on Unix and a combination
/// of identifier, volume serial, and file size on Windows. Note that it's
/// possible for comparing two handles to produce a false positive on some
/// platforms. Namely, two handles can compare equal even if the two handles
/// *don't* point to the same file. Check the [source] for specific
/// implementation details.
///
#[derive(Debug, Eq, PartialEq, Hash)]
pub struct Handle(imp::Handle);
impl Handle {
/// Construct a handle from a path.
///
/// Note that the underlying [`File`] is opened in read-only mode on all
/// platforms.
///
///
/// # Errors
/// This method will return an [`io::Error`] if the path cannot
/// be opened, or the file's metadata cannot be obtained.
/// The most common reasons for this are: the path does not
/// exist, or there were not enough permissions.
///
///
/// # Examples
/// Check that two paths are not the same file:
///
/// ```rust,no_run
/// # use std::error::Error;
/// use same_file::Handle;
///
/// # fn try_main() -> Result<(), Box<Error>> {
/// let source = Handle::from_path("./source")?;
/// let target = Handle::from_path("./target")?;
/// assert_ne!(source, target, "The files are the same.");
/// # Ok(())
/// # }
/// #
/// # fn main() {
/// # try_main().unwrap();
/// # }
/// ```
pub fn from_path<P: AsRef<Path>>(p: P) -> io::Result<Handle> {
imp::Handle::from_path(p).map(Handle)
}
/// Construct a handle from a file.
///
/// # Errors
/// This method will return an [`io::Error`] if the metadata for
/// the given [`File`] cannot be obtained.
///
///
/// # Examples
/// Check that two files are not in fact the same file:
///
/// ```rust,no_run
/// # use std::error::Error;
/// # use std::fs::File;
/// use same_file::Handle;
///
/// # fn try_main() -> Result<(), Box<Error>> {
/// let source = File::open("./source")?;
/// let target = File::open("./target")?;
///
/// assert_ne!(
/// Handle::from_file(source)?,
/// Handle::from_file(target)?,
/// "The files are the same."
/// );
/// # Ok(())
/// # }
/// #
/// # fn main() {
/// # try_main().unwrap();
/// # }
/// ```
pub fn from_file(file: File) -> io::Result<Handle> {
imp::Handle::from_file(file).map(Handle)
}
/// Construct a handle from stdin.
///
/// # Errors
/// This method will return an [`io::Error`] if stdin cannot
/// be opened due to any I/O-related reason.
///
///
/// # Examples
///
/// ```rust
/// # use std::error::Error;
/// use same_file::Handle;
///
/// # fn try_main() -> Result<(), Box<Error>> {
/// let stdin = Handle::stdin()?;
/// let stdout = Handle::stdout()?;
/// let stderr = Handle::stderr()?;
///
/// if stdin == stdout {
/// println!("stdin == stdout");
/// }
/// if stdin == stderr {
/// println!("stdin == stderr");
/// }
/// if stdout == stderr {
/// println!("stdout == stderr");
/// }
/// #
/// # Ok(())
/// # }
/// #
/// # fn main() {
/// # try_main().unwrap();
/// # }
/// ```
///
/// The output differs depending on the platform.
///
/// On Linux:
///
/// ```text
/// $ ./example
/// stdin == stdout
/// stdin == stderr
/// stdout == stderr
/// $ ./example > result
/// $ cat result
/// stdin == stderr
/// $ ./example > result 2>&1
/// $ cat result
/// stdout == stderr
/// ```
///
/// Windows:
///
/// ```text
/// > example
/// > example > result 2>&1
/// > type result
/// stdout == stderr
/// ```
pub fn stdin() -> io::Result<Handle> {
imp::Handle::stdin().map(Handle)
}
/// Construct a handle from stdout.
///
/// # Errors
/// This method will return an [`io::Error`] if stdout cannot
/// be opened due to any I/O-related reason.
///
///
/// # Examples
/// See the example for [`stdin()`].
///
/// [`stdin()`]: #method.stdin
pub fn stdout() -> io::Result<Handle> {
imp::Handle::stdout().map(Handle)
}
/// Construct a handle from stderr.
///
/// # Errors
/// This method will return an [`io::Error`] if stderr cannot
/// be opened due to any I/O-related reason.
///
///
/// # Examples
/// See the example for [`stdin()`].
///
/// [`stdin()`]: #method.stdin
pub fn stderr() -> io::Result<Handle> {
imp::Handle::stderr().map(Handle)
}
/// Return a reference to the underlying file.
///
/// # Examples
/// Ensure that the target file is not the same as the source one,
/// and copy the data to it:
///
/// ```rust,no_run
/// # use std::error::Error;
/// use std::io::prelude::*;
/// use std::io::Write;
/// use std::fs::File;
/// use same_file::Handle;
///
/// # fn try_main() -> Result<(), Box<Error>> {
/// let source = File::open("source")?;
/// let target = File::create("target")?;
///
/// let source_handle = Handle::from_file(source)?;
/// let mut target_handle = Handle::from_file(target)?;
/// assert_ne!(source_handle, target_handle, "The files are the same.");
///
/// let mut source = source_handle.as_file();
/// let target = target_handle.as_file_mut();
///
/// let mut buffer = Vec::new();
/// // data copy is simplified for the purposes of the example
/// source.read_to_end(&mut buffer)?;
/// target.write_all(&buffer)?;
/// #
/// # Ok(())
/// # }
/// #
/// # fn main() {
/// # try_main().unwrap();
/// # }
/// ```
pub fn as_file(&self) -> &File {
self.0.as_file()
}
/// Return a mutable reference to the underlying file.
///
/// # Examples
/// See the example for [`as_file()`].
///
/// [`as_file()`]: #method.as_file
pub fn as_file_mut(&mut self) -> &mut File {
self.0.as_file_mut()
}
/// Return the underlying device number of this handle.
///
/// Note that this only works on unix platforms.
#[cfg(any(target_os = "redox", unix))]
pub fn dev(&self) -> u64 {
self.0.dev()
}
/// Return the underlying inode number of this handle.
///
/// Note that this only works on unix platforms.
#[cfg(any(target_os = "redox", unix))]
pub fn ino(&self) -> u64 {
self.0.ino()
}
}
/// Returns true if the two file paths may correspond to the same file.
///
/// Note that it's possible for this to produce a false positive on some
/// platforms. Namely, this can return true even if the two file paths *don't*
/// resolve to the same file.
/// # Errors
/// This function will return an [`io::Error`] if any of the two paths cannot
/// be opened. The most common reasons for this are: the path does not exist,
/// or there were not enough permissions.
///
///
/// # Example
///
/// ```rust,no_run
/// use same_file::is_same_file;
///
/// assert!(is_same_file("./foo", "././foo").unwrap_or(false));
/// ```
pub fn is_same_file<P, Q>(path1: P, path2: Q) -> io::Result<bool>
where
P: AsRef<Path>,
Q: AsRef<Path>,
{
Ok(Handle::from_path(path1)? == Handle::from_path(path2)?)
}
#[cfg(test)]
mod tests {
use std::env;
use std::error;
use std::fs::{self, File};
use std::io;
use std::path::{Path, PathBuf};
use std::result;
use super::is_same_file;
type Result<T> = result::Result<T, Box<error::Error + Send + Sync>>;
/// Create an error from a format!-like syntax.
macro_rules! err {
($($tt:tt)*) => {
Box::<error::Error + Send + Sync>::from(format!($($tt)*))
}
}
/// A simple wrapper for creating a temporary directory that is
/// automatically deleted when it's dropped.
///
/// We use this in lieu of tempfile because tempfile brings in too many
/// dependencies.
#[derive(Debug)]
struct TempDir(PathBuf);
impl Drop for TempDir {
fn drop(&mut self) {
fs::remove_dir_all(&self.0).unwrap();
}
}
impl TempDir {
/// Create a new empty temporary directory under the system's
/// configured temporary directory.
fn new() -> Result<TempDir> {
#![allow(deprecated)]
use std::sync::atomic::{
AtomicUsize, Ordering, ATOMIC_USIZE_INIT,
};
static TRIES: usize = 100;
static COUNTER: AtomicUsize = ATOMIC_USIZE_INIT;
let tmpdir = env::temp_dir();
for _ in 0..TRIES {
let count = COUNTER.fetch_add(1, Ordering::SeqCst);
let path = tmpdir.join("rust-walkdir").join(count.to_string());
if path.is_dir() {
continue;
}
fs::create_dir_all(&path).map_err(|e| {
err!("failed to create {}: {}", path.display(), e)
})?;
return Ok(TempDir(path));
}
Err(err!("failed to create temp dir after {} tries", TRIES))
}
/// Return the underlying path to this temporary directory.
fn path(&self) -> &Path {
&self.0
}
}
fn tmpdir() -> TempDir {
TempDir::new().unwrap()
}
#[cfg(unix)]
pub fn soft_link_dir<P: AsRef<Path>, Q: AsRef<Path>>(
src: P,
dst: Q,
) -> io::Result<()> {
use std::os::unix::fs::symlink;
symlink(src, dst)
}
#[cfg(unix)]
pub fn soft_link_file<P: AsRef<Path>, Q: AsRef<Path>>(
src: P,
dst: Q,
) -> io::Result<()> {
soft_link_dir(src, dst)
}
#[cfg(windows)]
pub fn soft_link_dir<P: AsRef<Path>, Q: AsRef<Path>>(
src: P,
dst: Q,
) -> io::Result<()> {
use std::os::windows::fs::symlink_dir;
symlink_dir(src, dst)
}
#[cfg(windows)]
pub fn soft_link_file<P: AsRef<Path>, Q: AsRef<Path>>(
src: P,
dst: Q,
) -> io::Result<()> {
use std::os::windows::fs::symlink_file;
symlink_file(src, dst)
}
// These tests are rather uninteresting. The really interesting tests
// would stress the edge cases. On Unix, this might be comparing two files
// on different mount points with the same inode number. On Windows, this
// might be comparing two files whose file indices are the same on file
// systems where such things aren't guaranteed to be unique.
//
// Alas, I don't know how to create those environmental conditions. ---AG
#[test]
fn same_file_trivial() {
let tdir = tmpdir();
let dir = tdir.path();
File::create(dir.join("a")).unwrap();
assert!(is_same_file(dir.join("a"), dir.join("a")).unwrap());
}
#[test]
fn same_dir_trivial() {
let tdir = tmpdir();
let dir = tdir.path();
fs::create_dir(dir.join("a")).unwrap();
assert!(is_same_file(dir.join("a"), dir.join("a")).unwrap());
}
#[test]
fn not_same_file_trivial() {
let tdir = tmpdir();
let dir = tdir.path();
File::create(dir.join("a")).unwrap();
File::create(dir.join("b")).unwrap();
assert!(!is_same_file(dir.join("a"), dir.join("b")).unwrap());
}
#[test]
fn not_same_dir_trivial() {
let tdir = tmpdir();
let dir = tdir.path();
fs::create_dir(dir.join("a")).unwrap();
fs::create_dir(dir.join("b")).unwrap();
assert!(!is_same_file(dir.join("a"), dir.join("b")).unwrap());
}
#[test]
fn same_file_hard() {
let tdir = tmpdir();
let dir = tdir.path();
File::create(dir.join("a")).unwrap();
fs::hard_link(dir.join("a"), dir.join("alink")).unwrap();
assert!(is_same_file(dir.join("a"), dir.join("alink")).unwrap());
}
#[test]
fn same_file_soft() {
let tdir = tmpdir();
let dir = tdir.path();
File::create(dir.join("a")).unwrap();
soft_link_file(dir.join("a"), dir.join("alink")).unwrap();
assert!(is_same_file(dir.join("a"), dir.join("alink")).unwrap());
}
#[test]
fn same_dir_soft() {
let tdir = tmpdir();
let dir = tdir.path();
fs::create_dir(dir.join("a")).unwrap();
soft_link_dir(dir.join("a"), dir.join("alink")).unwrap();
assert!(is_same_file(dir.join("a"), dir.join("alink")).unwrap());
}
#[test]
fn test_send() {
fn assert_send<T: Send>() {}
assert_send::<super::Handle>();
}
#[test]
fn test_sync() {
fn assert_sync<T: Sync>() {}
assert_sync::<super::Handle>();
}
}