ntfs Rust library

The ntfs library provides several high-level and low-level capabilities:

• Filesystem Abstraction: Convenience functions allow treating NTFS like a standard filesystem using Read and Seek traits.
• Attribute Access: Read arbitrary resident and non-resident attributes, including those in Attribute Lists and sparse attribute data. This enables reading file data and Alternate Data Streams (ADS) of any size.
• Flattened View: Provides a "data-centric" view of NTFS Attributes, abstracting away nested Attribute Lists.
• Efficient Directory Operations:
  • In-order iteration of directory contents at $O(1)$.
  • Efficient file finding using the filesystem's $Upcase Table for case-insensitive searches.
• Type Safety: Uses Rust's type system to handle various NTFS index types safely.
• Error Handling: Uses a custom NtfsError type that implements Display and provides location-specific details where applicable.

The ntfs-shell is a demonstration tool included with the crate that allows you to explore the internal structures of an NTFS filesystem at any detail level. It opens the filesystem in read-only mode, making it safe to use on mounted partitions.

Building

To build the shell with all features enabled, run:

cargo build --example ntfs-shell --all-features

Running

Pass the path to an NTFS image (works on all OSs) or a partition (Windows only) to the binary.

• On Windows: You can pass a partition path like \\.\C:, but you must run with administrative privileges.
• On all OSs: You can pass a path to an NTFS disk image.

Using the Shell

• Use help to see all supported commands.
• Use help COMMAND to see the syntax for a specific command.
• File Referencing: Most commands accepting a filename also accept an NTFS File Record Number. Prepend the number with / or 0x for hexadecimal.

Examples of file referencing:

fileinfo Windows
fileinfo /146810
fileinfo /0x23d7a

The NtfsIndex struct is a helper for iterating over or finding specific entries within an NTFS index (such as a directory's file name index).

To avoid manual attribute lookup, use NtfsFile::directory_index to obtain an NtfsIndex object directly for a directory.

Key capabilities:

• In-order traversal: Use .entries() to get an iterator that traverses all entries sorted by their index key.
• Efficient searching: Use .finder() to get an NtfsIndexFinder for locating specific entries using a comparison function.

// Example of obtaining an index from a directory file
let root_dir_index = root_dir.directory_index(&mut testfs).unwrap();

// 1. Iterate through entries
let mut iter = root_dir_index.entries();
while let Some(Ok(entry)) = iter.next(&mut testfs) {
    // process entry
}

// 2. Find a specific entry
let mut finder = root_dir_index.finder();
let entry = NtfsFileNameIndex::find(&mut finder, &ntfs, &mut testfs, "target_name").unwrap().unwrap();

To traverse all records within an $INDEX_ALLOCATION attribute, you can use the records method to create an iterator. There are two ways to consume these records depending on how you want to manage the filesystem reader (fs) borrow:

1. Manual Iteration (NtfsIndexRecords)

Use records() to get a NtfsIndexRecords object. This requires you to manually pass a mutable reference to the filesystem (&mut T) to the next() method on each iteration.

2. Standard Iterator (NtfsIndexRecordsAttached)

Use records().attach(fs) to get a NtfsIndexRecordsAttached object. This implements the standard Rust Iterator and FusedIterator traits by mutably borrowing the filesystem for the duration of the iteration. This allows you to use standard iterator methods like for loops or collect().

// Option 1: Manual next()
let mut iter = index_allocation.records(index_record_size);
while let Some(result) = iter.next(fs) { 
    let record = result?; 
    // ...
}

// Option 2: Standard Iterator (Recommended)
for result in index_allocation.records(index_record_size).attach(fs) {
    let record = result?;
    // ...
}

To interact with an NTFS filesystem using this crate, follow these steps:

1. Initialize an Ntfs structure by calling Ntfs::new(reader), where reader is a type implementing Read and Seek.
2. Access the root directory using ntfs.root_directory(reader) to obtain an NtfsFile.
3. Use NtfsFile methods to explore the filesystem:
   • attributes(reader): Retrieve file attributes.
   • attributes_raw(reader): Retrieve raw file attributes.
   • directory_index(reader): Access the directory index for a directory.
   • info(reader): Get file information.
   • name(): Get the file name.

The crate is no_std-compatible, making it suitable for environments ranging from firmware to user-mode applications.

# use ntfs::Ntfs;
# let mut fs = std::io::Cursor::new(vec![]);
// 1. Create an Ntfs structure from a reader
let mut ntfs = Ntfs::new(&mut fs).unwrap();

// 2. Retrieve the root directory
let root_dir = ntfs.root_directory(&mut fs).unwrap();

// 3. Dig into attributes or use convenience functions
let index = root_dir.directory_index(&mut fs).unwrap();
let mut iter = index.entries();

while let Some(entry) = iter.next(&mut fs) {
    let entry = entry.unwrap();
    let file_name = entry.key().unwrap().unwrap();
    println!("{}", file_name.name());
}