Crate usbh_fatfs

Crate usbh_fatfs 

Source
Expand description

§USBh-FatFS

A userspace library for interacting directly with FAT file systems on USB mass-storage devices.

Unlike traditional approaches, this crate does not require mounting the USB drive through the operating system. Instead, it uses rusb for USB access and fatfs for working with FAT partitions directly in userspace.

§Advantages

  • No OS mounting required Work directly with USB storage devices without relying on the operating system’s block device or filesystem layers. This avoids mount permissions, auto-mount races, and OS-specific device paths.

  • Cross-platform Works uniformly across Linux, macOS, and Windows (anywhere rusb is supported). No platform-specific filesystem APIs are needed.

  • Safe partition access PartitionView provides a restricted window into a specific partition, ensuring reads and writes cannot escape its boundaries.

  • Filesystem control in userspace Full control over how and when partitions are read/written, useful for embedded tooling, automated flashing utilities, or sandboxed environments.

  • Integrates with usbh-scsi Built on top of [usbh-scsi], giving access to both high-level FAT operations and low-level SCSI commands in the same ecosystem.

§Supported Platforms

Works on any OS that rusb supports (Linux, macOS, Windows, etc.).

§Core Types

  • StorageUsb: Represents a physical USB mass-storage device. Can be enumerated via StorageUsb::list_usbs and opened for block I/O.
  • FatPartition: A parsed FAT partition on a device. Provides metadata such as volume label, FAT type, and cluster size.
  • PartitionView: A safe “window” into a block device that restricts reads/writes to a single partition’s byte range. Used when creating a fatfs::FileSystem instance.

Together, these abstractions make it possible to safely:

  1. Detect USB storage devices.
  2. Parse their partition tables.
  3. Mount FAT partitions entirely in userspace.

§Example

use usbh_fatfs::{
    FatPartition, PartitionView, StorageUsb,
    fatfs::{FileSystem, FsOptions},
};

fn main() {
    // Enumerate all connected USB mass-storage devices.
    let usbs = StorageUsb::list_usbs().unwrap();
    println!("usbs: {:?}", usbs);

    for mut usb in usbs {
        // Parse FAT partitions on this device.
        let partitions = FatPartition::list_partitions(&mut usb).unwrap();
        println!("partitions: {:?}", partitions);

        for partition in partitions {
            // Open device for block access.
            let opened = usb.open().unwrap();
            let mut block_device = opened.block_device().unwrap();

            // Restrict I/O to the partition boundaries.
            let part_view = PartitionView::new(&mut block_device, partition.first_byte, partition.length).unwrap();

            // Mount the FAT filesystem in userspace.
            let fatfs = FileSystem::new(part_view, FsOptions::new()).unwrap();

            println!("Listing root dir on volume:");
            for item in fatfs.root_dir().iter() {
                let item = item.unwrap();
                println!("    {}", item.file_name());
            }
        }
    }
}

§See Also

§Crates Used

  • rusb — USB device enumeration and communication.
  • fatfs — Pure Rust FAT filesystem implementation.
  • bootsector — Partition table parsing.
  • [usbh-scsi] — USB Bulk-Only Transport and SCSI protocol support.

Re-exports§

pub use bootsector;
pub use fatfs;
pub use rusb;

Structs§

FatPartition
Represents a FAT partition discovered on a USB mass-storage device.
PartitionView
Provides a “window” into a block device, restricted to a single partition.
StorageUsb
Represents a USB mass-storage device connected to the system.

Enums§

FatError
Errors that can occur when reading/writing FAT partitions.
StorageUsbError
Errors that can occur when working with StorageUsb or partitions.
StorageUsbInner
Represents the state of a StorageUsb device.