src/lib.rs - platform/external/rust/crates/same-file - Git at Google

 /*!
 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.
 ///
 /// [source]: https://github.com/BurntSushi/same-file/tree/master/src
 #[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.
     ///
     /// [`File`]: https://doc.rust-lang.org/std/fs/struct.File.html
     ///
     /// # 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.
     ///
     /// [`io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html
     ///
     /// # 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.
     ///
     /// [`io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html
     /// [`File`]: https://doc.rust-lang.org/std/fs/struct.File.html
     ///
     /// # 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.
     ///
     /// [`io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html
     ///
     /// # 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.
     ///
     /// [`io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html
     ///
     /// # 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.
     ///
     /// [`io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html
     ///
     /// # 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.
 ///
 /// [`io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html
 ///
 /// # 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>();
     }
 }
	/*!
	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.
	///
	/// [source]: https://github.com/BurntSushi/same-file/tree/master/src
	#[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.
	///
	/// [`File`]: https://doc.rust-lang.org/std/fs/struct.File.html
	///
	/// # 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.
	///
	/// [`io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html
	///
	/// # 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.
	///
	/// [`io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html
	/// [`File`]: https://doc.rust-lang.org/std/fs/struct.File.html
	///
	/// # 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.
	///
	/// [`io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html
	///
	/// # 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.
	///
	/// [`io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html
	///
	/// # 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.
	///
	/// [`io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html
	///
	/// # 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.
	///
	/// [`io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html
	///
	/// # 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>();
	}
	}