elfie 0.1.0

A Dart library for parsing and analyzing ELF (Executable and Linkable Format) files.

elfie

A pure Dart library for parsing ELF (Executable and Linkable Format) files.

elfie provides a clean, type-safe API for reading and analyzing ELF binaries, supporting both 32-bit and 64-bit formats in little-endian and big-endian byte orders.

Features

• Comprehensive Parsing:
  • ELF Headers (File type, machine, entry point, etc.)
  • Program Headers (Segments)
  • Section Headers
  • Symbol Tables (.symtab, .dynsym)
  • Dynamic Sections
• Cross-Platform Support: Handle ELF32 and ELF64 files from any architecture (x86, ARM, RISC-V, etc.).
• Endianness Aware: Seamlessly parses little-endian and big-endian files.
• Zero Dependencies: Written in pure Dart.

Getting started

Add elfie to your pubspec.yaml:

dependencies:
  elfie: ^1.0.0

Or run:

dart pub add elfie

Usage

Quick Start

The simplest way to parse an ELF file:

import 'package:elfie/elfie.dart';

void main() {
  // Parse from bytes
  final elf = Elfie.parse(bytes);

  // Or parse from a file path
  final elf = Elfie.parseFile('/path/to/binary');

  print('Entry Point: 0x${elf.header.entryPoint.toRadixString(16)}');
}

Non-Throwing API

Use tryParse and tryParseFile for error handling without exceptions:

import 'package:elfie/elfie.dart';

void main() {
  final result = Elfie.tryParseFile('/path/to/binary');

  if (result.isSuccess) {
    final elf = result.value;
    print('Parsed successfully!');
    print('Class: ${elf.header.elfClass.displayName}');
  } else {
    print('Error: ${result.error}');
  }
}

The Result<T> type provides:

• isSuccess / isFailure - Check the result status
• value - Get the parsed ElfFile (throws if failure)
• error - Get the error object (throws if success)
• getOrElse(fallback) - Get value or compute fallback from error

Inspecting Headers

final elf = Elfie.parseFile('/path/to/binary');

print('=== ELF Header ===');
print('Class:      ${elf.header.elfClass.displayName}');
print('Endianness: ${elf.header.elfEndianness.displayName}');
print('Type:       ${elf.header.typeName}');
print('Machine:    ${elf.header.machineName}');
print('Entry:      0x${elf.header.entryPoint.toRadixString(16)}');

Inspecting Sections

for (final section in elf.sectionHeaders) {
  print('Section: ${section.name}');
  print('  Type: ${section.typeName}');
  print('  Size: ${section.size} bytes');
  print('  Address: 0x${section.virtualAddress.toRadixString(16)}');
}

Inspecting Program Headers

for (final ph in elf.programHeaders) {
  print('Segment: ${ph.typeName}');
  print('  Offset: 0x${ph.offset.toRadixString(16)}');
  print('  VAddr:  0x${ph.virtualAddress.toRadixString(16)}');
  print('  Flags:  ${ph.flagsString}');
}

Exception-Based Error Handling

If you prefer exceptions, use parse and parseFile:

try {
  final elf = Elfie.parseFile('/path/to/binary');
} on ElfFormatException catch (e) {
  print('Invalid ELF format: ${e.message}');
} on ElfTruncatedFileException catch (e) {
  print('File is incomplete. Expected ${e.expectedBytes} bytes.');
} on ElfCorruptDataException catch (e) {
  print('Corrupt data encountered at offset ${e.offset}.');
} on FileSystemException catch (e) {
  print('Could not read file: ${e.message}');
}

Low-Level Parser Access

For more control, use ElfParser directly:

final parser = ElfParser();

// Parse from bytes
final elf = parser.parseBytes(bytes);

// Parse from file
final elf = parser.parseFile('/path/to/binary');

API Reference

Elfie (Recommended)

Method	Description
Elfie.parse(bytes)	Parse ELF from bytes. Throws on error.
Elfie.parseFile(path)	Parse ELF from file. Throws on error.
Elfie.tryParse(bytes)	Parse ELF from bytes. Returns Result<ElfFile>.
Elfie.tryParseFile(path)	Parse ELF from file. Returns Result<ElfFile>.

Result<T>

Member	Description
isSuccess	true if parsing succeeded.
isFailure	true if parsing failed.
value	The parsed ElfFile. Throws StateError if failure.
error	The error object. Throws StateError if success.
stackTrace	Stack trace of the error, if available.
getOrElse(fn)	Returns value, or result of fn(error) if failure.

Exceptions

Exception	Description
ElfException	Base class for all ELF parsing errors.
ElfFormatException	Invalid ELF format (bad magic, unsupported version).
ElfTruncatedFileException	File is too short or truncated.
ElfCorruptDataException	Data is corrupt or malformed.
ElfUnsupportedFeatureException	Unsupported ELF feature encountered.

Additional information

For more details, see the example/ folder.