Documentation
¶
Overview ¶
Package dump renders a binary's views as plain, non-interactive text for stdout (the `-o` flag), turning exex into a scriptable readelf/nm/objdump-lite. It shares the function-disassembly formatter with the TUI's "copy function" so the two stay identical.
Index ¶
- Variables
- func AlignAsm(text string) string
- func CPUFeatures(f *binfile.File) (string, error)
- func ClassifySyscallSite(inst disasm.Inst, symAt func(uint64) (binfile.Symbol, bool)) (site bool, vdso bool)
- func DisasmTo(w io.Writer, f *binfile.File, all bool) error
- func Function(f *binfile.File, target string) (string, error)
- func FunctionInsts(f *binfile.File, svc *explorer.DisasmService, sym binfile.Symbol) []disasm.Inst
- func FunctionText(sym binfile.Symbol, insts []disasm.Inst, addrW int) string
- func Info(f *binfile.File) string
- func IsDisasm(name string) (disasm, all bool)
- func IsVDSOName(name string) bool
- func IsView(name string) bool
- func Libs(f *binfile.File) string
- func Relocs(f *binfile.File) string
- func ResolveSyscallNum(prev []disasm.Inst, a disasm.Arch) (int64, bool)
- func Sections(f *binfile.File) string
- func Segments(f *binfile.File) string
- func Sources(f *binfile.File) string
- func StreamView(w io.Writer, f *binfile.File, name string) (handled bool, err error)
- func Strings(f *binfile.File) string
- func StringsTo(w io.Writer, f *binfile.File) error
- func Symbols(f *binfile.File) string
- func SymbolsTo(w io.Writer, f *binfile.File) error
- func SyscallName(f *binfile.File, num int64) (string, bool)
- func Syscalls(f *binfile.File, full bool) string
- func SyscallsArchive(members []binfile.ArchiveMember, full bool) string
- func SyscallsFull(f *binfile.File) string
- func VDSOSymAt(f *binfile.File) func(uint64) (binfile.Symbol, bool)
- func View(f *binfile.File, name string) (string, error)
- func ViewNeedsDemangle(name string) bool
- func ViewNeedsLayoutOnly(name string) bool
- type CPUFeatureSet
- type SyscallSite
Constants ¶
This section is empty.
Variables ¶
var ViewNames = []string{"info", "sections", "segments", "symbols", "strings", "libs", "sources", "relocs", "syscalls", "syscalls-all", "cpu-features", "disasm", "disasm-all"}
ViewNames lists the canonical view keywords for help/usage text.
Functions ¶
func AlignAsm ¶
AlignAsm renders an instruction's text objdump-style: the mnemonic right-aligned in asmMnemWidth, operands left-aligned after a single space (so the mnemonic/operand boundary is a single vertical seam). A mnemonic longer than the field simply overflows it (no truncation). Hex immediates are already produced by the decoder (see disasm.hexImmediates); this only handles layout, so the dump and the TUI disasm view stay identical.
func CPUFeatures ¶
CPUFeatures renders the CPU-feature report for the `-o cpu-features` dump.
func ClassifySyscallSite ¶
func ClassifySyscallSite(inst disasm.Inst, symAt func(uint64) (binfile.Symbol, bool)) (site bool, vdso bool)
ClassifySyscallSite reports whether inst is a syscall site and, if so, whether it is a vDSO call. The symAt lookup resolves an instruction's branch target to a symbol for the vDSO heuristic; it may be nil to disable that heuristic.
func DisasmTo ¶
DisasmTo streams the disassembly objdump-style to w: a "Disassembly of section <name>:" header per section and a "<addr> <symbol>:" label wherever a symbol begins. When all is false only executable sections are emitted (objdump -d); when true every section with file bytes is (objdump -D).
It streams per instruction (no whole-binary buffer) and demangles labels lazily, so output starts immediately on large binaries and `| head` / `| less` stops early instead of waiting for the entire image to decode. A write error (e.g. the reader closed the pipe) ends the dump cleanly.
func Function ¶
Function resolves target (a symbol name or address) to a function and returns its disassembly as plain text.
func FunctionInsts ¶
FunctionInsts decodes the instructions making up sym's extent, fresh from the executable image. Shared with the TUI's "copy function" so both cover the whole function regardless of any visible decode window.
func FunctionText ¶
FunctionText renders a function's instructions as plain, copy-friendly "addr: bytes text" lines under a header naming the symbol and its range.
func IsDisasm ¶
IsDisasm reports whether name selects a (streaming) disassembly dump, and whether it is the all-sections variant. The CLI routes these to DisasmTo rather than View so output streams instead of buffering.
func IsVDSOName ¶
IsVDSOName reports whether a symbol name is a vDSO / kernel-helper entry point, i.e. a userspace call that services what would otherwise be a system call.
func IsView ¶
IsView reports whether name is a known view keyword for `-o`. The CLI uses this to tell `-o sections` (a view) from a bare `-o` whose target is the positional symbol/address — so a symbol literally named "sections" can still be disassembled (as the positional), without colliding with the view.
func ResolveSyscallNum ¶
ResolveSyscallNum recovers the system-call number for the site at prev[len-1]'s successor by scanning the preceding instructions (oldest..newest) for the last immediate written to the architecture's syscall-number register. prev must end just before the syscall instruction. It is best-effort: a number set in a register, computed, or out of the scan window stays unresolved.
func Sections ¶
Sections dumps the section table. An LMA (load/physical address) column is added only when some section's load address differs from its virtual address.
func Segments ¶
Segments dumps the segment (memory-region) table. A PAddr column is added only when some segment's physical address differs from its virtual address.
func StreamView ¶
StreamView writes a view straight to w when it has a streaming form (the large symbol/string tables), returning whether it handled the view. The CLI uses it so those dumps never buffer the whole output; other views fall back to View.
func Strings ¶
Strings dumps the printable strings to a string (with address or file offset). The CLI streams it via StringsTo; this buffered form is for tests.
func StringsTo ¶
StringsTo streams the printable strings to w, one per line. The per-line prefix is formatted into one reused buffer and the text is written straight from the file image (StringBytes is zero-copy), so neither a per-line copy nor a whole- output buffer is allocated. A write error ends the dump cleanly.
func Symbols ¶
Symbols dumps the symbol table to a string (nm-like: addr, size, bind, type, name). The CLI streams it via SymbolsTo; this buffered form is for callers that want the whole text (tests).
func SymbolsTo ¶
SymbolsTo streams the symbol table to w (one row per symbol), so a table with hundreds of thousands of symbols never buffers the whole output. Each row's fixed columns are formatted into one reused buffer (no boxed Fprintf per row). A write error (e.g. a closed pipe) ends the dump cleanly.
func SyscallName ¶
SyscallName resolves a syscall number to its name for f's os/arch, consulting any loaded override tables. Exposed so the TUI's syscall modal resolves names the same way the dump does.
func Syscalls ¶
Syscalls dumps the binary's syscall usage. By default it summarises the *unique* system calls invoked (one row per distinct number, with a count and an example location); with full=true it lists every site with its address, like `objdump`-style output.
func SyscallsArchive ¶
func SyscallsArchive(members []binfile.ArchiveMember, full bool) string
SyscallsArchive summarises the system calls provided by a static-library (ar) archive, scanning every object member and tagging each syscall with the member it came from. With full=false it prints the merged unique list; with full=true it lists every site (its member as the symbol column).
func SyscallsFull ¶
SyscallsFull summarises the system calls of the binary *and its directly linked libraries* — the real syscall surface of a dynamically linked program, whose own code often makes no direct syscalls (they live in libc). The output is one merged unique list, each row tagged with the originating object(s).
func VDSOSymAt ¶
VDSOSymAt returns f.SymbolAt only when the binary actually has vDSO/__kernel_ symbols; otherwise nil, so a scan can skip the per-call-instruction symbol lookup the vDSO heuristic would otherwise do on every call in the image. Exported so the TUI scan can apply the same optimisation.
func ViewNeedsDemangle ¶
ViewNeedsDemangle reports whether a view actually displays symbol names, so the CLI can skip the whole-table demangle pass for views that don't (sections, segments, strings, libs, sources, info) — that pass allocates 1+ GB on a large C++/Swift binary and is pure waste for them.
func ViewNeedsLayoutOnly ¶
ViewNeedsLayoutOnly reports whether a view can be rendered from the cheap layout model (sections/segments/raw bytes) without symbols, imports, relocs, DWARF, or computed overview fields.
Types ¶
type CPUFeatureSet ¶
type CPUFeatureSet struct {
Counts map[string]int // feature → number of instructions using it
FirstUse map[string]uint64 // feature → address of the first instruction using it
Total int // instructions scanned
Baseline string // implied x86-64 microarch level (x86 only), or ""
}
CPUFeatureSet is the result of a feature scan.
func ScanCPUFeatures ¶
func ScanCPUFeatures(f *binfile.File) (CPUFeatureSet, error)
ScanCPUFeatures decodes the executable sections — in parallel chunks across all cores, the same way the syscall scan does — and classifies every instruction into the CPU-feature families it requires. Each chunk decodes a small lead of preceding bytes to re-synchronise the (variable-length x86) decoder, then only counts instructions at or past the chunk's real start so the overlap isn't double-counted.
func ScanCPUFeaturesCancel ¶
func ScanCPUFeaturesCancel(f *binfile.File, done <-chan struct{}) (CPUFeatureSet, error)
ScanCPUFeaturesCancel is ScanCPUFeatures with an optional cancellation channel. When done is closed, workers stop decoding as soon as they observe it. The UI still guards stale results by sequence number; cancellation is to stop wasting CPU after the user dismisses/supersedes the scan.
func (CPUFeatureSet) SortedFeatures ¶
func (s CPUFeatureSet) SortedFeatures() []string
SortedFeatures returns the used features in display order (then by count).
type SyscallSite ¶
type SyscallSite struct {
Addr uint64 // address of the instruction
Text string // its trimmed assembly text
Sym string // enclosing symbol's display name, or ""
VDSO bool // true for a vDSO/__kernel_ call rather than a real syscall insn
Num int64 // resolved syscall number, when recoverable
HasNum bool // whether Num was recovered
Name string // resolved syscall name (os/arch table), when known
Origin string // object the site came from (full scan), e.g. "libc.so.6"; "" = this binary
}
SyscallSite is one located system-call (or vDSO) site.
func CollectSyscallsFull ¶
func CollectSyscallsFull(f *binfile.File) (sites []SyscallSite, objects int, notes []string)
CollectSyscallsFull scans the binary and its directly linked libraries for syscall sites, tagging each with the object it came from. It returns the sites, the number of objects scanned, and notes about libraries that couldn't be scanned. Shared by the `syscalls-full` dump and the TUI's full scope.
func CollectSyscallsFullCancel ¶
func CollectSyscallsFullCancel(f *binfile.File, done <-chan struct{}) (sites []SyscallSite, objects int, notes []string)
CollectSyscallsFullCancel is CollectSyscallsFull with cooperative cancellation. When done is closed it stops scheduling new library/object work and asks active decode workers to exit early. Partial results may be returned; UI callers guard cancelled results by sequence/file identity.
Source Files