Crate object_lang

Expand description

§object-lang

Writes and reads the files operating systems run. A format-neutral Object — sections, symbols, relocations, and for executables an entry point — goes in, and ELF64 bytes for x86-64 or AArch64 come out: relocatable objects a linker can consume, or static executables the kernel loads directly, with no system linker or assembler involved. Reading turns ELF bytes back into the same model, strictly and within budgets, without panicking on any input.

§Quick start

A static Linux x86-64 program that exits with status 42, from hand-assembled bytes:

use object_lang::Architecture;

let code = [
    0xbf, 0x2a, 0x00, 0x00, 0x00, // mov edi, 42
    0xb8, 0x3c, 0x00, 0x00, 0x00, // mov eax, 60 (exit)
    0x0f, 0x05, //                   syscall
];
let program = object_lang::elf::executable(Architecture::X86_64, &code)?;
assert_eq!(&program[..4], b"\x7fELF");

A relocatable object, written and read back:

use object_lang::{
    Architecture, Object, Relocation, RelocationTarget, Section, SectionKind, Symbol,
    X86_64Reloc,
};

let mut obj = Object::relocatable(Architecture::X86_64);
// main: call helper; ret
let text = obj.add_section(
    Section::new(".text", SectionKind::Text)
        .with_align(16)
        .with_data(vec![0xe8, 0, 0, 0, 0, 0xc3]),
);
obj.add_symbol(Symbol::function("main", text, 0, 6));
let helper = obj.add_symbol(Symbol::undefined("helper"));
obj.add_relocation(
    text,
    Relocation::new(1, X86_64Reloc::Plt32, RelocationTarget::Symbol(helper), -4),
)?;

let bytes = object_lang::elf::write(&obj)?;
assert_eq!(object_lang::elf::read(&bytes)?, obj);

§The model

An Object is a FileKind (relocatable or executable), an Architecture, Sections, Symbols, and an entry point.
A Section has a SectionKind, SectionFlags, an alignment, an address, and either bytes or (for BSS) a size, plus the Relocations that patch it.
A Relocation patches offset with a RelocationKind computed from a RelocationTarget (a symbol or a section) and an explicit addend.
Object::validate checks every rule; writers run it first and readers run it on what they read, so errors are values (ModelError, WriteError, ReadError), never malformed files.

Nothing in the model is ELF-specific: kinds are named for what they mean, not for one format’s numbering, so COFF/PE and Mach-O writers fit the same model.

§Features

std (default): nothing beyond alloc is used; without it the crate is no_std and the API is identical.

Modules§

elf: ELF64, little-endian, for x86-64 and AArch64: relocatable objects (ET_REL) and static executables (ET_EXEC).

Structs§

Limits: Budgets for reading untrusted files.
Object: One object file or executable, independent of the format it is written in.
Relocation: A place in a section to patch: the bytes at offset receive the value kind computes from the address of target plus addend.
Section: One section: a name, a kind, flags, an alignment, its contents (bytes, or for Bss only a size), an address, and the Relocations that patch it.
SectionFlags: Attributes of a section, independent of the file format.
SectionId: The identity of a section within its Object: its position in Object::sections.
Symbol: One symbol: a name, what it names, where it is defined, and who can see it.
SymbolId: The identity of a symbol within its Object: its position in Object::symbols.

Enums§

Aarch64Reloc: An AArch64 relocation. Each variant names its ELF counterpart; in the formulas, S is the target’s address, A the addend, P the address of the patched bytes, Page(x) is x with its low 12 bits cleared, and G the address of the target’s GOT entry. Instruction relocations patch an immediate field of a 4-byte instruction, so their offset must be a multiple of 4.
Architecture: The instruction set an object is built for.
Binding: Who can see a symbol: this object only, or every object in the link.
FileKind: What a file is for: input to a linker, or a program the OS can run.
ModelError: A rule of the object model that an Object breaks, from Object::validate, from the builders on Section, or from a reader whose input decodes to an invalid model.
ReadError: Why bytes could not be read as an object.
RelocationKind: How a relocation patches its bytes: an architecture-specific kind.
RelocationProblem: What is wrong with one relocation. Reported inside ModelError::Relocation.
RelocationTarget: What a relocation’s address comes from.
SectionKind: What a section holds. The kind decides how a format stores the section (an ELF section type, a COFF characteristic, a Mach-O section type) and which SectionFlags it may carry.
SectionProblem: What is wrong with one section. Reported inside ModelError::Section.
SymbolKind: What a symbol names.
SymbolProblem: What is wrong with one symbol. Reported inside ModelError::Symbol.
SymbolSection: Where a symbol is defined.
Visibility: How far a global symbol is exported beyond the module it is linked into.
WriteError: Why an object could not be written.
X86_64Reloc: An x86-64 relocation. Each variant names its ELF counterpart; in the formulas, S is the target’s address, A the addend, P the address of the patched bytes, L the address of the target’s PLT entry (or the target itself in a static link), and G the address of the target’s GOT entry.