ELF (Linux / BSD) binary reader in pure OCaml
README.md

ocaml-elf #

ELF (Linux / BSD) binary reader in pure OCaml.

Overview #

A tool that wants to know what a binary contains, such as the size of each section or which symbols it defines, usually shells out to nm, size or readelf and parses their text. ocaml-elf reads 64-bit ELF images, the executable and object format of Linux and the BSDs, directly. The on-disk structures (the ELF header, the section header table, and the .symtab symbol table with its string table) are described with the wire combinator library and decoded through bytesrw.

Unlike Mach-O, ELF symbol records carry an explicit size, so each symbol's byte size is read directly rather than inferred. Only 64-bit little-endian images (ELFCLASS64 and ELFDATA2LSB) are read.

Installation #

Install with opam:

$ opam install elf

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install elf

Reading #

Elf.of_string parses an image and exposes its architecture, sections and defined symbols. Malformed input is rejected with a message rather than an exception:

# Elf.of_string
    "this text is plainly not an ELF binary; it is just an ordinary sentence."
- : (Elf.t, string) result = Error "ELF: not an ELF image"

On a real binary, Elf.sections and Elf.symbols return the section layout and the section-defined symbols, each tagged with the section-header index that Elf.section_by_index resolves.

The target architecture needs far less than the image. Elf.cpu_of_prefix reads it from the first Elf.cpu_prefix_size bytes (the e_ident bytes and e_machine), so asking what a half-gigabyte executable was built for costs twenty bytes rather than the whole file:

# Elf.cpu_prefix_size
- : int = 20
# Elf.cpu_of_prefix
    "\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\xb7\x00"
- : (Elf.cpu, string) result = Ok Elf.Aarch64

An e_machine value this reader has no name for comes back as Other n rather than an error, since the image is well formed and the caller decides which architectures to refuse. Elf_eio.cpu, in the elf-eio package, reads exactly that prefix from a file.

Status #

The ELF header, the section header table (including the extended numbering encoded in section 0), the program headers, and the symbol and string tables are parsed and bounds-checked against the input. The ELF header keeps the section count (e_shnum) and the index of the section-name table (e_shstrndx) in 16-bit fields. A file with 0xff00 sections or more puts 0 in e_shnum and SHN_XINDEX (0xffff) in e_shstrndx, and the real values go in the sh_size and sh_link fields of section header 0, which is otherwise unused (System V gABI, "Sections"). Elf_eio.segments and Elf_eio.has_interpreter read the program headers from a file without reading the rest of the image. Undefined, absolute and common symbols are dropped. Only 64-bit little-endian images are read, and the library does not write ELF.

Licence #

ISC. See LICENSE.md.