Skip to content

faq.md

Latest commit

 

History

History
168 lines (111 loc) · 6.31 KB

faq.md

File metadata and controls

168 lines (111 loc) · 6.31 KB
Raw

FAQ

Frequently asked questions about XISOSharp, XISO images, and Xbox disc formats.

General

What is XISO / XDVDFS?

XISO (XDVDFS — Xbox DVD Filesystem) is the filesystem used on Xbox game discs. It is a simple, sector-based filesystem with an AVL-tree directory structure — see XISO Format.

Is XISOSharp a wrapper around the C tool?

No. It is a pure C# port of extract-xiso.c v2.7.1 — no native code, no P/Invoke. The C sources under References/ are used only for cross-checking during development.

Is the output byte-identical to the original extract-xiso?

Yes, by design. The port reproduces the C tool's algorithms exactly (including AVL rebalancing and directory layout), and the test suite plus Verify-Output.ps1 continuously verify SHA-256 equality of outputs.

Which disc formats are supported?

RAW (bare XISO), GLOBAL, XGD2, XGD3, and XGD1 — detected automatically. Redump images with a video partition are supported via --skip-sectors / --prepend-sectors (see Redump & Disc Layouts).

Usage

Why does extract-xiso say a Redump image is invalid?

Redump dumps contain a video partition followed by the game partition. If the game partition sits at a nonstandard offset, auto-detection can fail. Find the offset and use --skip-sectors:

XISOSharp.Cli --skip-sectors 129824 -d ./out dump.iso    # XGD2-style offset

Do I need --skip-sectors for every Redump image?

Only when the game partition is not at one of the probed offsets (RAW, 0x0FD90000, 0x02080000, 0x18300000). Many dumps are detected automatically.

What does -s do exactly?

-s skips $SystemUpdate entries. During create it is implemented as the exclude pattern **/$SystemUpdate/** (matches entries named exactly $SystemUpdate); during extract/rewrite it filters $SystemUpdate paths while reading (substring match).

How do I exclude files when creating an image?

Use the repeatable -X flag with glob patterns:

XISOSharp.Cli -X "**/*.tmp" -X "**/node_modules/**" -c ./game_files

Patterns without a **/ prefix match only at the root. See CLI Reference.

Why is my ISO "already optimized"?

The image carries the optimized tag (in!xiso!2.7.1 (01.11.14) at offset 31337), which means it was already rewritten by an extract-xiso-family tool. Rewrite mode skips such images because there is nothing left to optimize.

How do I resume an interrupted extraction?

Re-run the same command with --skip-existing (extract, --unpack, or --copy-out; pairs with --batch):

XISOSharp.Cli --skip-existing --unpack game.iso ./out

Files already on disk with matching sizes are skipped (skip: <path>); missing or short files are written. XISO stores no per-file timestamps, so size is the match signal. See CLI Reference.

Why does rewrite/compress refuse with "is the same file as the input"?

An output pointing back at its own input is refused (exit 1) to prevent silent data loss — e.g. -r -o game.iso game.iso, or a rebuild -o naming a component. Omit -o to rewrite in place, or choose another name. See CLI Reference.

What is the 4 GB limit?

The on-disk file-size field is a 32-bit unsigned integer, so individual files cannot exceed 4,294,967,295 bytes (~4 GB). Larger files throw XisoFileTooLargeException.

Library

Which .NET versions does the library support?

net8.0, net9.0, and net10.0. The CLI targets net10.0 but can be published self-contained for any platform (see Building).

Is the library thread-safe?

The engine uses thread-static scratch buffers, so independent operations on different threads are safe. However, CreateXiso walks the file system using Directory.SetCurrentDirectory internally — concurrent create operations in the same process are not supported.

How do I suppress console output from the library?

Logger.Quiet = true;      // suppress normal output
Logger.RealQuiet = true;  // suppress everything, including errors

You can also redirect Logger.Out / Logger.Error to any TextWriter.

What does llCompat mean?

It selects the directory right-offset calculation: true for legacy linked-list-compatible images (not written by extract-xiso-family tools), false for optimized images. The CLI chooses automatically via the optimized tag.

Format

Are filenames UTF-8?

No. XDVDFS filenames are byte strings (Windows-1252 / Latin-1). XISOSharp reads and writes them with a Latin-1 encoding so every byte round-trips; names containing ., .., /, or \ are rejected on read.

What is the optimized tag for?

It marks an image as having the optimized AVL directory layout so readers can skip the legacy linked-list compatibility path. It is a 24-byte marker at byte offset 31337.

Why are empty directories one sector of 0xFF?

The format has no explicit empty-directory marker; an empty directory table is written as a single 0xFF-filled sector with a table size of 2048 bytes, and readers detect the leading 0xFFFF as "end of table".

Does XISOSharp support split ISOs (.iso.001, …)?

No — split-file images are out of scope. XISOSharp works with single-file images only.

Misc

Where is the C# code different from the C original?

Only additively: new CLI flags (-t, -i, -V, -o, --copy-out, --md5, --sha256, -X, --skip-sectors, --prepend-sectors, --skip-existing, validate/--validate*), the input==output safety guard, misplaced-flag diagnostics, -d tolerance for batch-script artifacts (trailing separators, UNC paths, spaces), unpack resume (UnpackOptions), per-file extraction errors with entry/sector/size context plus --continue-on-error (ExtractFileException), GUI drag-and-drop, async APIs, progress callbacks, a public stream-based read API (OpenImageStream + Stream overloads of Extract/UnpackImage/List/Tree/DecodeXiso), and a public library surface. Core algorithms are unchanged.

Where can I report bugs or request features?

Open an issue on the repository. Feature ideas are tracked in ProposedEnhancements.md.

See also: Getting Started · CLI Reference · Troubleshooting