BinaryIIReader 1.0.0

BinaryIIReader

A lightweight .NET library for reading Binary II archive files (.bny, .bxy). Binary II is a wrapper format developed by Gary B. Little to preserve ProDOS file attributes during file transfers on Apple II computers. A single Binary II file can hold multiple disk files, making it easy to keep related files "glued" together.

Features

• Read Binary II archives (.bny, .bxy files)
• Support for archives containing multiple files
• Parse file information headers with full metadata preservation
• Extract file data with 128-byte boundary alignment
• Preserve ProDOS file attributes:
  • File type and auxiliary type
  • Access flags (read, write, delete, etc.)
  • Storage type
  • Creation and modification dates
• Support for GS/OS extended attributes
• Support for multiple operating systems:
  • ProDOS/SOS
  • DOS 3.3/3.2
  • Apple II Pascal
  • Macintosh HFS/MFS
  • MS-DOS
  • CP/M
  • And more
• Zero external dependencies (core library)
• Built for .NET 9.0

Installation

Add the project reference to your .NET application:

dotnet add reference path/to/BinaryIIReader.csproj

Or, if published on NuGet:

dotnet add package BinaryIIReader

Usage

Opening a Binary II Archive

using BinaryIIReader;

// Open a Binary II archive file
using var stream = File.OpenRead("archive.bny");

// Parse the archive
var archive = new BinaryIIArchive(stream);

// Get archive information
Console.WriteLine($"Total Entries: {archive.Count}");

Listing Files in the Archive

// Enumerate all entries in the archive
foreach (var entry in archive.Entries)
{
    var header = entry.Header;
    Console.WriteLine($"{header.FileName}");
    Console.WriteLine($"  OS Type: {header.OperatingSystemType}");
    Console.WriteLine($"  File Type: 0x{header.FileType:X2}");
    Console.WriteLine($"  Aux Type: 0x{header.AuxType:X4}");
    Console.WriteLine($"  Storage Type: {header.StorageType}");
    Console.WriteLine($"  File Length: {header.FileLength} bytes");
    Console.WriteLine($"  Files to Follow: {header.FilesToFollow}");
}

Extracting File Data

foreach (var entry in archive.Entries)
{
    var fileName = entry.Header.FileName.ToString();

    // Extract file data as byte array
    var data = entry.GetData();
    File.WriteAllBytes(fileName, data);

    // Or extract to a stream
    using var outputStream = File.Create($"{fileName}.out");
    entry.GetData(outputStream);
}

Working with Multiple Files

Binary II archives can contain multiple files in series. Each header's FilesToFollow byte indicates how many files remain:

using var stream = File.OpenRead("multi-file.bny");
var archive = new BinaryIIArchive(stream);

Console.WriteLine($"Archive contains {archive.Count} file(s)");

for (int i = 0; i < archive.Count; i++)
{
    var entry = archive[i];
    Console.WriteLine($"Entry {i + 1}: {entry.Header.FileName}");
    Console.WriteLine($"  Files to follow: {entry.Header.FilesToFollow}");
}

API Overview

BinaryIIArchive

The main class for reading Binary II archives. Implements IReadOnlyList<BinaryIIEntry>.

• BinaryIIArchive(Stream stream) - Opens an archive from a stream
• Count - Gets the number of entries in the archive
• Entries - Gets a read-only collection of all entries
• this[int index] - Gets the entry at the specified index
• GetEnumerator() - Enumerates all entries

BinaryIIEntry

Represents a single file entry within the archive:

• Header - Gets the file information header
• GetData() - Extracts the file data as a byte array
• GetData(Stream destination) - Copies the file data to a stream

BinaryIIHeader

Contains file-level metadata (128 bytes):

ProDOS Attributes:

• AccessCode - ProDOS access flags
• FileType - ProDOS file type
• AuxType - ProDOS auxiliary type
• StorageType - ProDOS storage type
• SizeInBlocks - File size in 512-byte blocks
• FileLength - File length in bytes (EOF)
• FileName - File name (max 64 characters)
• CreationDate / CreationTime - Creation timestamp
• ModificationDate / ModificationTime - Modification timestamp

Archive Information:

• FilesToFollow - Number of files remaining in the archive
• DiskSpaceNeeded - Total disk space needed (first entry only)
• Version - Binary II format version (0 or 1)

Operating System:

• OperatingSystemType - Native OS type
• NativeFileType - Native file type (16-bit)

Data Flags:

• DataFlags - Compression/encryption flags
• PhantomFileFlag - Phantom file indicator

GS/OS Extended Attributes:

• GsosAuxTypeHigh - GS/OS auxiliary type high word
• GsosAccessHigh - GS/OS access high byte
• GsosFileTypeHigh - GS/OS file type high byte
• GsosStorageTypeHigh - GS/OS storage type high byte
• GsosSizeInBlocksHigh - GS/OS file size in blocks high word
• GsosEofHigh - GS/OS EOF high byte

Helper Properties:

• TotalEntrySize - Total size including header and padded data
• IsBinaryII(ReadOnlySpan<byte>) - Static method to check for Binary II signature

Enumerations

BinaryIIOperatingSystem

• ProDOS_SOS - ProDOS or SOS
• DOS_3_3 - Apple DOS 3.3
• DOS_3_2 - Apple DOS 3.2 or 3.1
• AppleII_Pascal - Apple II Pascal
• Macintosh_MFS - Macintosh MFS
• Macintosh_HFS - Macintosh HFS
• Lisa - Lisa Filing System
• Apple_CP_M - Apple CP/M
• MS_DOS - MS-DOS
• HighSierra - High Sierra (CD-ROM)
• ISO_9660 - ISO 9660 (CD-ROM)
• AppleShare - AppleShare

BinaryIIDataFlags

• Compressed - File is compressed
• Encrypted - File is encrypted
• Sparse - File is sparse

Archive Structure

A Binary II file containing multiple files is structured as a series of header/data pairs:

  start                                                           end
  -------------------------------------------------------------------
  | Header #1 | #1 Data | Header #2 | #2 Data | Header #3 | #3 Data |
  -------------------------------------------------------------------
    +127 = 2              +127 = 1              +127 = 0

• Each header is exactly 128 bytes
• Data areas are padded to 128-byte boundaries
• The FilesToFollow byte (offset 127) indicates remaining files
• Last file has FilesToFollow = 0

Building

Build the project using the .NET SDK:

dotnet build

Run tests:

dotnet test

BinaryIIDumper CLI

Extract files from Binary II archives using the command-line dumper tool.

Build

dotnet build dumper/BinaryIIDumper.csproj -c Release

Usage

dotnet run --project dumper/BinaryIIDumper.csproj -- <input> [-o|--output <path>]

Arguments:

• <input>: Path to the Binary II archive file (.bny, .bxy)
• -o|--output: Destination directory for extracted files (defaults to archive name)

Example:

dotnet run --project dumper/BinaryIIDumper.csproj -- archive.bny -o extracted_files

Output:

Archive: archive.bny
Total Entries: 3
Output Directory: /path/to/extracted_files

Extracting: MYFILE
  OS Type: ProDOS_SOS
  Type: 0x06  Aux: 0x0000  Storage: Standard
  File Length: 4096 bytes
  Files to Follow: 2
  Data: /path/to/extracted_files/MYFILE (4 KB)
Extracting: README
  OS Type: ProDOS_SOS
  Type: 0x04  Aux: 0x0000  Storage: Standard
  File Length: 1024 bytes
  Files to Follow: 1
  Data: /path/to/extracted_files/README (1 KB)
Extracting: DATA.BIN
  OS Type: ProDOS_SOS
  Type: 0x00  Aux: 0x0000  Storage: Standard
  File Length: 512 bytes
  Files to Follow: 0
  Data: /path/to/extracted_files/DATA.BIN (512 B)

Extraction complete: /path/to/extracted_files

Requirements

• .NET 9.0 or later

License

MIT License. See LICENSE for details.

Copyright (c) 2026 Hugh Bellamy

About Binary II

Binary II was created by Gary B. Little in 1986 as a way to preserve Apple II file attributes during file transfers. Before Binary II, transferring files between Apple II computers via modems or bulletin board systems would lose important metadata like file type, auxiliary type, and access permissions.

Key Features:

• Preserves ProDOS file attributes during transfer
• 128-byte header with comprehensive metadata
• Support for multiple files in a single archive
• Data padding to 128-byte boundaries
• Version 0 and version 1 format support
• GS/OS extended attribute support

File Extensions:

• .bny - Binary II archive
• .bxy - Binary II wrapped ShrinkIt archive (contains compressed data)

Identification: Binary II files are identified by:

• Signature bytes: $0A $47 $4C (linefeed, 'G', 'L') at offset 0
• ID byte: $02 at offset 18 ($12)

Related Projects

• AppleDiskImageReader - Reader for Apple II universal disk (.2mg) images
• AppleIIDiskReader - Reader for Apple II DOS 3.3 disk (.dsk) images
• ProDosVolumeReader - Reader for ProDOS (.po) volumes
• WozDiskImageReader - Reader for WOZ (.woz) disk images
• DiskCopyReader - Reader for Disk Copy 4.2 (.dc42) images
• MfsReader - Reader for MFS (Macintosh File System) volumes
• HfsReader - Reader for HFS (Hierarchical File System) volumes
• ResourceForkReader - Reader for Macintosh resource forks
• StuffItReader - Reader for StuffIt (.sit) archives

Documentation

• Binary II Format Specification (FTN.e0.8000)
• Binary II Notes (CiderPress2)
• Apple II File Type Notes