Crate hadris_iso 

Hadris ISO

A pure Rust ISO 9660 filesystem and disk-image library with allocation-free ISO 9660/Joliet reading, Rock Ridge (RRIP), El Torito booting, and no_std support.

This crate provides both reading and writing capabilities for ISO 9660 images, making it suitable for:

• Bootloaders: Allocation-free path lookup and caller-buffered file streaming
• OS Kernels: Read ISO filesystems with only a heap allocator
• Desktop Applications: Full-featured ISO creation and extraction
• Build Systems: Automated bootable ISO generation

I/O modes

std selects standard-library integration but does not enable an I/O mode. Enable sync, async, or both. The default configuration enables sync for compatibility. ISO creation and modification are currently synchronous-only; the async module exposes the implemented read APIs.

Quick Start

Reading an ISO Image

use hadris_iso::read::IsoImage;

let image = IsoImage::open(reader).unwrap();

// Get the root directory
let root = image.root_dir();

// Iterate through files
for entry in root.iter(&image).entries() {
    let entry = entry.unwrap();
    println!("File: {:?}", String::from_utf8_lossy(entry.name()));
}

Creating a Bootable ISO

use std::io::Cursor;
use std::sync::Arc;
use hadris_iso::boot::options::{BootEntryOptions, BootOptions};
use hadris_iso::boot::EmulationType;
use hadris_iso::read::PathSeparator;
use hadris_iso::write::options::{BaseIsoLevel, CreationFeatures, IsoFormatOptions};
use hadris_iso::write::{File as IsoFile, InputFiles, IsoImageWriter};

// Prepare files to include (use dummy boot image for example)
let files = InputFiles {
    path_separator: PathSeparator::ForwardSlash,
    files: vec![
        IsoFile::File {
            name: Arc::new("boot.bin".to_string()),
            contents: boot_image,
        },
    ],
};

// Configure boot options
let boot_options = BootOptions {
    write_boot_catalog: true,
    default: BootEntryOptions {
        boot_image_path: "boot.bin".to_string(),
        load_size: Some(std::num::NonZeroU16::new(4).unwrap()),
        boot_info_table: false,
        grub2_boot_info: false,
        emulation: EmulationType::NoEmulation,
    },
    entries: vec![],
};

// Create the ISO
let format_options = IsoFormatOptions {
    volume_name: "MY_BOOTABLE_ISO".to_string(),
    system_id: None, volume_set_id: None, publisher_id: None,
    preparer_id: None, application_id: None,
    sector_size: 2048,
    path_separator: PathSeparator::ForwardSlash,
    features: CreationFeatures {
        filenames: BaseIsoLevel::Level1 {
            supports_lowercase: false,
            supports_rrip: false,
        },
        long_filenames: false,
        joliet: None,
        rock_ridge: None,
        el_torito: Some(boot_options),
        hybrid_boot: None,
    },
    strict_charset: false,
};

let mut buffer = Cursor::new(vec![0u8; 2 * 1024 * 1024]); // 2MB buffer
IsoImageWriter::create(&mut buffer, files, format_options).unwrap();

Feature Flags

This crate uses feature flags to control functionality and dependencies:

Feature	Description	Dependencies
read	Allocation-free ISO 9660/Joliet navigation and streaming	No heap allocator
alloc	Owned collections, RRIP enrichment, and convenience reads	alloc crate
std	Full standard library support	std, alloc, thiserror, tracing, chrono
write	ISO creation/formatting	std, alloc
joliet	Allocating Joliet encode/write helpers (read already supports Joliet lookup)	alloc

Feature Combinations

For Bootloaders (minimal footprint):

[dependencies]
hadris-iso = { version = "0.2", default-features = false, features = ["read"] }

For Kernels with Heap (no-std + alloc):

[dependencies]
hadris-iso = { version = "0.2", default-features = false, features = ["read", "alloc"] }

For Desktop Applications (full features):

[dependencies]
hadris-iso = { version = "0.2" }  # Uses default features: std, write

ISO 9660 Extensions

Joliet Extension

Joliet provides Unicode filename support using UTF-16 encoding. It allows filenames up to 64 characters and preserves case. Enable with the joliet feature.

use hadris_iso::joliet::JolietLevel;
use hadris_iso::write::options::CreationFeatures;

let features = CreationFeatures {
    joliet: Some(JolietLevel::Level3), // Full Unicode support
    ..Default::default()
};

Rock Ridge (RRIP) Extension

Rock Ridge provides POSIX filesystem semantics including:

• Long filenames (up to 255 characters)
• Unix permissions and ownership
• Symbolic links
• Device files

El-Torito Boot Extension

El-Torito enables bootable CD/DVD images. This crate supports:

• BIOS boot (x86/x86_64)
• UEFI boot
• No-emulation boot mode
• Boot information table injection

Hybrid Boot (USB Boot)

Hybrid boot enables ISOs to be bootable when written directly to USB drives:

• MBR mode - For BIOS systems (isohybrid-compatible)
• GPT mode - For UEFI systems
• Hybrid MBR+GPT - For dual BIOS/UEFI compatibility

use hadris_iso::write::options::{CreationFeatures, HybridBootOptions, PartitionScheme};

// Enable MBR-based hybrid boot for USB
let features = CreationFeatures {
    hybrid_boot: Some(HybridBootOptions::mbr()),
    ..Default::default()
};

// Enable dual BIOS/UEFI boot
let features = CreationFeatures {
    hybrid_boot: Some(HybridBootOptions::hybrid()),
    ..Default::default()
};

Architecture

The crate is organized into several modules:

• boot - El-Torito boot catalog structures and options
• directory - Directory record parsing and creation
• file - File entry types and filename handling
• io - Sector-based I/O abstractions
• joliet - Joliet UTF-16 extension support
• path - Path table structures
• read - ISO image reading and navigation
• rrip - Rock Ridge extension support
• susp - System Use Sharing Protocol (base for Rock Ridge)
• types - Common types (endian values, strings, dates)
• volume - Volume descriptor structures
• write - ISO image creation

Compatibility

ISOs created with this crate are compatible with:

• Linux (mount, isoinfo)
• Windows (built-in ISO support)
• macOS (built-in ISO support)
• QEMU/VirtualBox (bootable ISOs)
• xorriso (can read/verify)

Specification References

This implementation follows these specifications:

• ECMA-119 (ISO 9660)
• Joliet Specification (Microsoft)
• IEEE P1282 (Rock Ridge / RRIP)
• El-Torito Bootable CD-ROM Format Specification

For detailed specification documentation, see the spec directory.

Known Limitations

• Rock Ridge write: POSIX metadata, timestamps, symlinks, device numbers, and deep-directory relocation (CL/PL/RE) are supported.
• Joliet + Rock Ridge on read: When an image has both namespaces, the reader selects a single root via usefulness scoring (root_dir() / best_choice()). Joliet roots are treated as non-RRIP, so a Level-1 + RRIP root can win over Joliet and hide Unicode Joliet names. Prefer read::RootDirs::iter or read::RootDirs::get when you need an explicit namespace.
• El-Torito emulation images: Multi-section catalogs are supported, but floppy and hard-disk images are caller-supplied opaque disk images; the writer does not synthesize a filesystem inside them.
• High-level IsoImage: Requires the alloc feature. read alone exposes low-level modules suitable for no-alloc bootloaders.
• Not supported (writer rejects or does not emit): files larger than 4 GiB / multi-extent write; Extended Attribute Record contents; the Volume Partition Descriptor body; interleaved files; associated-file write; the optional secondary path tables; RRIP SF (sparse) and RR (legacy presence) entries; zisofs compression; and the Apple Partition Map.
• Non-2048 logical block size: IsoImage requires a 2048-byte logical block and rejects other sizes; the allocation-free IsoReader honors the declared block size.
• Hybrid GPT backup: the embedded GPT writes the primary header/entries only; a spec-valid backup GPT at end-of-disk is not written.

Re-exports

pub use sync::*;sync

Modules

asyncasync

Asynchronous ISO 9660 API.

file

File entry types and interchange levels.

jolietalloc or read

Joliet extension for Unicode filenames.

syncsync

Synchronous ISO 9660 API.

types

Common types used throughout the crate.