BinHandle

BinHandle is the front-end entry point for most B2R2 scripts. It owns the loaded binary, exposes file metadata, provides architecture-specific register lookup, and creates lifting units for parsing and LowUIR lifting.

Sources:

B2R2/src/FrontEnd/API/BinHandle.fsi
B2R2/src/FrontEnd/BinFile/IBinMetadata.fs
B2R2/src/FrontEnd/BinFile/IBinOrganization.fs
B2R2/src/FrontEnd/BinFile/BinFilePointer.fs
B2R2/src/FrontEnd/BinFile/ELFBinFile.fs

Constructors

Constructor	Use
`BinHandle(path: string)`	Load a file with default Intel 64-bit ISA; file format is detected.
`BinHandle(path: string, isa: ISA)`	Load a file with an explicit ISA.
`BinHandle(path: string, isa: ISA, baseAddrOpt: Addr option)`	Load a file with an explicit ISA and optional base address.
`BinHandle(bytes: byte[], isa: ISA)`	Load raw bytes with base address `0`; file format detection is disabled.
`BinHandle(bytes: byte[], isa: ISA, baseAddrOpt: Addr option, detectFormat: bool)`	Load bytes with optional base address and optional format detection.
`BinHandle(isa: ISA)`	Create an empty handle for an ISA.

Properties

API	Meaning
`File: IBinFile`	Binary metadata, sections, symbols, entry point, ISA, and address checks.
`RegisterFactory: IRegisterFactory`	Architecture-specific register lookup and register metadata.

File Metadata and Sections

hdl.File exposes binary-format metadata through IBinFile and related interfaces. Tutorial scripts use this to find executable address ranges before filtering recovered functions.

API	Meaning
`hdl.File.EntryPoint`	Optional binary entry address.
`hdl.File.ISA`	ISA detected or supplied for the binary.
`hdl.File.IsValidAddr addr`	True when `addr` belongs to a valid loaded range.
`hdl.File.IsValidRange range`	True when the whole address range is valid.
`hdl.File.GetTextSectionPointer()`	Return a `BinFilePointer` for the text/code section.

BinFilePointer represents an inclusive address and file-offset range.

Field or member	Meaning
`Addr` / `MaxAddr`	First and last virtual address covered by the pointer.
`Offset` / `MaxOffset`	First and last file offset covered by the pointer.
`IsValid`	True when both address and offset ranges are usable.
`IsNull`	True for the null pointer value.
`IsVirtual`	True when the range is mapped in memory but not backed by file bytes.
`ReadableAmount`	Number of bytes readable from the pointer.
`CanRead(size)`	True when `size` bytes fit in the pointer range.
`Advance(amount)`	Return a pointer moved forward by `amount` bytes.

let text = hdl.File.GetTextSectionPointer()

let isInText (addr: Addr) =
  text.IsValid && text.Addr <= addr && addr <= text.MaxAddr

For ELF-specific metadata, pattern-match hdl.File to ELFBinFile.

API	Meaning
`ELFBinFile.GlobalPointer`	Optional MIPS GP value computed from the GOT section.

match hdl.File with
| :? ELFBinFile as elf ->
  match elf.GlobalPointer with
  | Some gp -> printfn "GP = 0x%x" gp
  | None -> ()
| _ -> ()

Lifting

API	Meaning
`NewLiftingUnit(): LiftingUnit`	Create a fresh parser/lifter for instructions and LowUIR statements.

let hdl = BinHandle("bin/findme")
let lifter = hdl.NewLiftingUnit()

match hdl.File.EntryPoint with
| Some entry ->
  match lifter.TryParseInstruction entry with
  | Ok ins -> printfn "%O" ins
  | Error err -> printfn "parse failed: %A" err
| None -> printfn "no entry point"

Reading Data

API	Meaning
`TryReadBytes(addr, nBytes)`	Safe byte read by virtual address.
`TryReadBytes(ptr, nBytes)`	Safe byte read by `BinFilePointer`.
`ReadBytes(addr, nBytes)`	Byte read by address; raises on invalid memory.
`ReadBytes(ptr, nBytes)`	Byte read by pointer; raises on invalid memory.
`TryReadInt(addr, size)` / `TryReadInt(ptr, size)`	Safe signed integer read for 1, 2, 4, or 8 bytes.
`ReadInt(addr, size)` / `ReadInt(ptr, size)`	Signed integer read that raises on invalid memory.
`TryReadUInt(addr, size)` / `TryReadUInt(ptr, size)`	Safe unsigned integer read for 1, 2, 4, or 8 bytes.
`ReadUInt(addr, size)` / `ReadUInt(ptr, size)`	Unsigned integer read that raises on invalid memory.
`ReadASCII(addr)` / `ReadASCII(ptr)`	Read a null-terminated ASCII string.

match hdl.TryReadBytes(0x401000UL, 16) with
| Ok bytes -> printfn "%A" bytes
| Error err -> printfn "read failed: %A" err

let value = hdl.ReadUInt(0x401000UL, 4)

Rebuilding Handles

API	Meaning
`MakeNew(bs)`	Create a new handle with replacement bytes and the same binary settings.
`MakeNew(bs, baseAddr)`	Create a new handle with replacement bytes and a new base address.

Use MakeNew when a script transforms binary bytes and wants to re-run B2R2 front-end logic without manually reconstructing every setting.