Struct Handle

pub struct Handle(/* private fields */);

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.

Implementations

impl Handle

pub fn from_path<P: AsRef<Path>>(p: P) -> Result<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:

use same_file::Handle;

let source = Handle::from_path("./source")?;
let target = Handle::from_path("./target")?;
assert_ne!(source, target, "The files are the same.");

pub fn from_file(file: File) -> Result<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:

use same_file::Handle;

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."
);

pub fn stdin() -> Result<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

use same_file::Handle;

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");
}

The output differs depending on the platform.

On Linux:

$ ./example
stdin == stdout
stdin == stderr
stdout == stderr
$ ./example > result
$ cat result
stdin == stderr
$ ./example > result 2>&1
$ cat result
stdout == stderr

Windows:

> example
> example > result 2>&1
> type result
stdout == stderr

pub fn stdout() -> Result<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().

pub fn stderr() -> Result<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().

pub fn as_file(&self) -> &File

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:

use std::io::prelude::*;
use std::io::Write;
use std::fs::File;
use same_file::Handle;

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)?;

pub fn as_file_mut(&mut self) -> &mut File

Return a mutable reference to the underlying file.

Examples

See the example for as_file().

pub fn dev(&self) -> u64

Return the underlying device number of this handle.

Note that this only works on unix platforms.

pub fn ino(&self) -> u64

Return the underlying inode number of this handle.

Note that this only works on unix platforms.

Trait Implementations

impl AsRawFd for Handle

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Handle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl IntoRawFd for Handle

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.

impl PartialEq for Handle

fn eq(&self, other: &Handle) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Handle

impl StructuralPartialEq for Handle