Crate macho_unwind_info

A zero-copy parser for the contents of the __unwind_info section of a mach-O binary.

Quickly look up the unwinding opcode for an address. Then parse the opcode to find out how to recover the return address and the caller frame’s register values.

This crate is intended to be fast enough to be used in a sampling profiler. Re-parsing from scratch is cheap and can be done on every sample.

For the full unwinding experience, both __unwind_info and __eh_frame may need to be consulted. The two sections are complementary: __unwind_info handles the easy cases, and refers to an __eh_frame FDE for the hard cases. Conversely, __eh_frame only includes FDEs for functions whose unwinding info cannot be represented in __unwind_info.

On x86 and x86_64, __unwind_info can represent most functions regardless of whether they were compiled with framepointers or without.

On arm64, compiling without framepointers is strongly discouraged, and __unwind_info can only represent functions which have framepointers or which don’t need to restore any registers. As a result, if you have an arm64 binary without framepointers (rare!), then the __unwind_info basically just acts as an index for __eh_frame, similarly to .eh_frame_hdr for ELF.

In clang’s default configuration for arm64, non-leaf functions have framepointers and leaf functions without stored registers on the stack don’t have framepointers. For leaf functions, the return address is kept in the lr register for the entire duration of the function. And the unwind info lets you discern between these two types of functions (“frame-based” and “frameless”).

Example

use macho_unwind_info::UnwindInfo;
use macho_unwind_info::opcodes::OpcodeX86_64;

let unwind_info = UnwindInfo::parse(data)?;

if let Some(function) = unwind_info.lookup(0x1234)? {
    println!("Found function entry covering the address 0x1234:");
    let opcode = OpcodeX86_64::parse(function.opcode);
    println!("0x{:08x}..0x{:08x}: {}", function.start_address, function.end_address, opcode);
}

Modules

• opcodes
  Provides architecture-specific opcode parsing.
• raw
  Lower-level structs for interpreting the format data. Can be used if the convenience APIs are too limiting.

Structs

• Function
  The information about a single function in the UnwindInfo.
• FunctionIter
  An iterator over the functions in an UnwindInfo page.
• UnwindInfo
  A parsed representation of the unwind info.

Enums

• Error
  The error type used in this crate.
• ReadError
  This error indicates that the data slice was not large enough to read the respective item.