Struct FileID

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

A file’s identifier, can be compared with other FileIDs to check if 2 variables point to the same file.

This struct is the combination of 2 identifiers:

• The id of the storage that contains the file.
• The internal file id, unique only across files in the same storage.

Combining both allows to uniquely identify the file within the entire system.

FileID can be used to identify everything that implements AsRawFd (or AsRawHandle on Windows), but it may function differently when identifying non-files.
For example, when used on stdout/stderr/stdin, the 3 will share the same identifier if they belong to the same process. (Only works on Unix, on Windows it will just error…)

Implementations

impl FileID

pub fn new<T: GetID + ?Sized>(file: &T) -> Result<Self>

Obtains the identifier of a file, directory, etc.

Platform-specific behavior

While on Unix obtaining the identifier of a directory is possible, on Windows an error will be returned instead.

This function uses:

• fstat64 on Unix
• GetFileInformationByHandleEx on Windows.
• fd_filestat_get on WASI.

This may change in the future.

Errors

This function will error if it fails to open the file or fails to obtain the metadata containing the identifier.

Examples

Basic usage:

use fs_id::FileID;
 
fn main() -> std::io::Result<()> {
    let file_id1 = FileID::new("/some/file/path.txt")?;
    let file_id2 = FileID::new("/some/file/path.txt")?;
    let file_id3 = FileID::new("/some/other/file.txt")?;
    assert_eq!(file_id1, file_id2);
    assert_ne!(file_id1, file_id3);
    Ok(())
}

Many different types can be used:

use fs_id::FileID;
 
fn main() -> std::io::Result<()> {
    let file_id1 = FileID::new("using_str.txt")?;
    let file_id2 = FileID::new(std::ffi::OsStr::new("using_os_str.txt"))?;
    let file_id3 = FileID::new(&std::fs::File::open("using_a_file.txt")?)?;
    let file_id4 = FileID::new(&std::io::stdout())?;
    // etc...
    Ok(())
}

pub const fn storage_id(&self) -> u64

Returns the storage identifier from the file identifier.

Platform-specific behavior

This returns:

• st_dev on Unix.
• VolumeSerialNumber on Windows.
• dev on WASI.

This may change in the future.

Examples

use fs_id::FileID;
 
fn main() -> std::io::Result<()> {
    let file_id = FileID::new("/some/file/path.txt")?;
    println!("{}", file_id.storage_id());
    Ok(())
}

pub const fn internal_file_id(&self) -> u128

Returns the internal file identifier from the file identifier.
Note that this value alone cannot uniquely identify the file within the system.

Platform-specific behavior

This returns:

• st_ino on Unix.
• FileId on Windows.
• ino on WASI.

This may change in the future.

On Unix and WASI only 64 of the returned 128 bits are effectively used.

Examples

use fs_id::FileID;
 
fn main() -> std::io::Result<()> {
    let file_id = FileID::new("/some/file/path.txt")?;
    println!("{}", file_id.internal_file_id());
    Ok(())
}

Trait Implementations

impl Clone for FileID

fn clone(&self) -> FileID

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FileID

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

Formats the value using the given formatter.

impl GetID for FileID

fn get_id(&self) -> Result<FileID>

Returns a copy of itself wrapped inside Ok.

impl Hash for FileID

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for FileID

fn eq(&self, other: &FileID) -> 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 Copy for FileID

impl Eq for FileID

impl StructuralPartialEq for FileID