Crate goblin

libgoblin

libgoblin is a cross-platform trifecta of binary parsing and loading fun. It supports:

• An ELF32/64 parser, and raw C structs
• A 32/64-bit, zero-copy, endian aware, Mach-o parser, and raw C structs
• A PE32/PE32+ (64-bit) parser, and raw C structs
• A Unix archive parser and loader

Goblin requires at least rustc 1.15

Example

use goblin::{error, Hint, pe, elf, mach, archive};
use std::path::Path;
use std::env;
use std::fs::File;
use std::io::Read;

fn run () -> error::Result<()> {
    for (i, arg) in env::args().enumerate() {
        if i == 1 {
            let path = Path::new(arg.as_str());
            let mut fd = File::open(path)?;
            let peek = goblin::peek(&mut fd)?;
            let mut buffer = Vec::new();
            fd.read_to_end(&mut buffer)?;
            match peek {
                Hint::Elf(_) => {
                    let elf = elf::Elf::parse(&buffer)?;
                    println!("elf: {:#?}", &elf);
                },
                Hint::PE => {
                    let pe = pe::PE::parse(&buffer)?;
                    println!("pe: {:#?}", &pe);
                },
                Hint::Mach(_) => {
                    let mach = mach::Mach::parse(&buffer)?;
                    println!("mach: {:#?}", &mach);
                },
                Hint::Archive => {
                    let archive = archive::Archive::parse(&buffer)?;
                    println!("archive: {:#?}", &archive);
                },
                _ => {}
            }
        }
    }
    Ok(())
}

Feature Usage

libgoblin is engineered to be tailored towards very different use-case scenarios, for example:

• a no-std mode; just simply set default features to false
• a endian aware parsing and reading
• for binary loaders which don't require this, simply use elf32 and elf64 (and std of course)

For example, if you are writing a 64-bit kernel, or just want a barebones C-like header interface which defines the structures, just select elf64, --cfg feature=\"elf64\", which will compile without std.

Similarly, if you want to use host endianness loading via the various from_fd methods, --cfg feature=\"std\", which will not use the byteorder extern crate, and read the bytes from disk in the endianness of the host machine.

If you want endian aware reading, and you don't use default, then you need to opt in as normal via endian_fd

Modules

archive	Implements a simple parser and extractor for a Unix Archive.
container	Binary container size information and byte-order context
elf	The generic ELF module, which gives access to ELF constants and other helper functions, which are independent of ELF bithood. Also defines an Elf struct which implements a unified parser that returns a wrapped Elf64 or Elf32 binary.
elf32	The ELF 32-bit struct definitions and associated values, re-exported for easy "type-punning"
elf64	The ELF 64-bit struct definitions and associated values, re-exported for easy "type-punning"
error	A custom Goblin error
mach	The Mach-o, mostly zero-copy, binary format parser and raw struct definitions
pe	A PE32 and PE32+ parser
strtab	A byte-offset based string table. Commonly used in ELF binaries, and also archives.

Structs

HintData

Information obtained from a peek Hint

Enums

Hint	A hint at the underlying binary format for 16 bytes of arbitrary data

Functions

peek	Peeks at the underlying Read object. Requires the underlying bytes to have at least 16 byte length. Resets the seek to Start after reading.
peek_bytes	Peeks at bytes, and returns a Hint