objfile

Documentation

Overview

Package objfile loads executables into a format-independent representation: the architecture, the functions with their machine code, symbol lookups, source positions from the Go pclntab or DWARF, and a disassembler for the code.

A binary is memory-mapped, and Open reads only its headers and symbol tables; line tables are parsed per compilation unit on first use. All methods are safe for concurrent use after Open.

Index

• func Demangle(name string) string
• type Binary
  • func Open(path string) (*Binary, error)
  • func Parse(data []byte) (*Binary, error)
  • func (b *Binary) Close() error
  • func (b *Binary) Contains(addr uint64) bool
  • func (b *Binary) DataSym(addr uint64) (name string, base, size uint64)
  • func (b *Binary) Disassemble(fn *Func) ([]Inst, error)
  • func (b *Binary) Func(name string) *Func
  • func (b *Binary) FuncFile(addr uint64) string
  • func (b *Binary) Lookup(addr uint64) (name string, base uint64)
  • func (b *Binary) PCToLine(pc uint64) (file string, line int)
• type Func
  • func (f *Func) Code() []byte
• type Inst

Functions

func Demangle

func Demangle(name string) string

Demangle turns a C++ or Rust symbol into the name it had in the source, signature and all, so that overloads stay apart. Anything that isn't a mangled name, which is every Go and C symbol, is returned unchanged. Rust has two schemes: the older one looks like C++ ("_ZN4prog8sum_ints 17h<hash>E"), the current one has its own prefix.

Types

type Binary

type Binary struct {
	Arch string // GOARCH name, e.g. "amd64"
	// Funcs are the functions inside the text section, sorted by
	// address, then name. Names are not unique: a Go ABI wrapper shares
	// the name of the function it wraps.
	Funcs []Func
	// NoLayout reports that function addresses are deterministic
	// pseudo-addresses (file offsets in a Go compile archive) rather
	// than a memory layout: gaps between functions are not padding.
	NoLayout bool
	// contains filtered or unexported fields
}

Binary is a loaded executable, backed by a read-only memory mapping of the file. Close releases the mapping; Func.Code slices become invalid afterwards.

func Open

func Open(path string) (*Binary, error)

Open maps the binary at path and parses it, detecting ELF, Mach-O, PE, WebAssembly and Go compile archives from the magic bytes.

func Parse

func Parse(data []byte) (*Binary, error)

Parse reads a binary held in memory. The Binary aliases data, which must not change while it is in use; Close does nothing.

func (*Binary) Close

func (b *Binary) Close() error

Close releases the file mapping.

func (*Binary) Contains

func (b *Binary) Contains(addr uint64) bool

Contains reports whether addr falls inside any loadable section of the binary.

func (*Binary) DataSym

func (b *Binary) DataSym(addr uint64) (name string, base, size uint64)

DataSym resolves addr to the name, base address, and size of the data symbol containing it, or zero values when unknown.

func (*Binary) Disassemble

func (b *Binary) Disassemble(fn *Func) ([]Inst, error)

Disassemble decodes the machine code of fn. Undecodable bytes become BYTE pseudo-instructions so padding or data inside a function does not abort decoding.

func (*Binary) Func

func (b *Binary) Func(name string) *Func

Func returns the function called name, or nil. When several share the name it returns the lowest-addressed one.

func (*Binary) FuncFile

func (b *Binary) FuncFile(addr uint64) string

FuncFile returns the file a function starting at addr was written in, from the debug info; empty when it isn't recorded.

func (*Binary) Lookup

func (b *Binary) Lookup(addr uint64) (name string, base uint64)

Lookup resolves addr to the name and base of the symbol containing it, text or data, matching the contract of the x/arch GoSyntax symname functions.

func (*Binary) PCToLine

func (b *Binary) PCToLine(pc uint64) (file string, line int)

PCToLine maps a pc to its source location using the Go pclntab, or DWARF when there is none; zero values when unknown.

type Func

type Func struct {
	Name string
	Addr uint64
	Size uint64
	// contains filtered or unexported fields
}

Func is a single function inside a binary.

func (*Func) Code

func (f *Func) Code() []byte

Code returns the machine code of the function, or nil when it lies outside every text section. The slice aliases the file mapping and must not be modified.

type Inst

type Inst struct {
	Addr uint64
	Len  int
	// Op is the canonical decoder mnemonic, e.g. "LD1" where the Go
	// syntax spells it "VLD1"; empty for undecodable bytes.
	Op string
	// Text is the Go assembler syntax and GNU the native syntax, with
	// the symbol at a resolved address appended objdump style ("<f>").
	// Thumb, AVR and Xtensa have no Go syntax: Text is the native text
	// and GNU equals it.
	Text, GNU string
	// Ref is the absolute address the instruction refers to, when it
	// has one inside the binary: the target of a branch or call, or the
	// data a pc-relative load or lea addresses. Zero for none.
	Ref uint64
	// RefKnown is always true; it predates Ref being set on every arch.
	RefKnown bool
	// Call reports a call instruction; Ref is zero when the callee is
	// in a register.
	Call bool
}

Inst is a single decoded instruction.