gosym

Documentation

Overview

Copyright 2009 The Go Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file. Package gosym implements access to the Go symbol and line number tables embedded in Go binaries generated by the gc compilers.

Index

• func Compare(v, w string) int
• func FuncSymName(goVersion string) string
• func GetFuncSymName() string
• func GoTagToSemver(tag string) string
• func MajorMinor(v string) string
• func ProgContaining(elfFile *elf.File, addr uint64) *elf.Prog
• func SegmentContaining(exe *macho.File, addr uint64) *macho.Segment
• type DecodingError
  • func (e *DecodingError) Error() string
• type Func
• type InlinedCall
• type LineTable
  • func NewLineTable(data []byte, text uint64) *LineTable
  • func (t *LineTable) InlineTree(f *Func, goFuncValue, baseAddr uint64, progReader io.ReaderAt) ([]InlinedCall, error)
  • func (t *LineTable) LineToPC(line int, maxpc uint64) uint64
  • func (t *LineTable) PCToLine(pc uint64) int
• type Obj
• type Sym
  • func (s *Sym) BaseName() string
  • func (s *Sym) PackageName() string
  • func (s *Sym) ReceiverName() string
  • func (s *Sym) Static() bool
• type Table
  • func NewTable(symtab []byte, pcln *LineTable) (*Table, error)
  • func (T *Table) GetInlineTree(f *Func, goFuncVal, baseaddr uint64, progReader io.ReaderAt) ([]InlinedCall, error)
  • func (t *Table) LineToPC(file string, line int) (pc uint64, fn *Func, err error)
  • func (t *Table) LookupFunc(name string) *Func
  • func (t *Table) LookupSym(name string) *Sym
  • func (t *Table) PCToFunc(pc uint64) *Func
  • func (t *Table) PCToLine(pc uint64) (file string, line int, fn *Func)
  • func (t *Table) SymByAddr(addr uint64) *Sym
• type UnknownFileError
  • func (e UnknownFileError) Error() string
• type UnknownLineError
  • func (e *UnknownLineError) Error() string

Functions

func Compare

func Compare(v, w string) int

Compare returns an integer comparing two versions according to semantic version precedence. The result will be 0 if v == w, -1 if v < w, or +1 if v > w.

An invalid semantic version string is considered less than a valid one. All invalid semantic version strings compare equal to each other.

func FuncSymName

func FuncSymName(goVersion string) string

FuncSymName returns symbol name for Go functions used in binaries based on Go version. Supported Go versions are 1.18 and greater. If the go version is unreadable it assumes that it is a newer version and returns the symbol name for go version 1.20 or greater.

func GetFuncSymName

func GetFuncSymName() string

func GoTagToSemver

func GoTagToSemver(tag string) string

GoTagToSemver is a modified copy of pkgsite/internal/stdlib:VersionForTag.

func MajorMinor

func MajorMinor(v string) string

MajorMinor returns the major.minor version prefix of the semantic version v. For example, MajorMinor("v2.1.0") == "v2.1". If v is an invalid semantic version string, MajorMinor returns the empty string.

func ProgContaining

func ProgContaining(elfFile *elf.File, addr uint64) *elf.Prog

func SegmentContaining

func SegmentContaining(exe *macho.File, addr uint64) *macho.Segment

Types

type DecodingError

type DecodingError struct {
	// contains filtered or unexported fields
}

DecodingError represents an error during the decoding of the symbol table.

func (*DecodingError) Error

func (e *DecodingError) Error() string

type Func

type Func struct {
	Entry uint64
	*Sym
	End       uint64
	Params    []*Sym // nil for Go 1.3 and later binaries
	Locals    []*Sym // nil for Go 1.3 and later binaries
	FrameSize int
	LineTable *LineTable
	Obj       *Obj
	// contains filtered or unexported fields
}

A Func collects information about a single function.

type InlinedCall

type InlinedCall struct {
	FuncID   uint8  // type of the called function
	Name     string // name of called function
	ParentPC int32  // position of an instruction whose source position is the call site (offset from entry)
}

InlinedCall describes a call to an inlined function.

type LineTable

type LineTable struct {
	Data []byte
	PC   uint64
	Line int
	// contains filtered or unexported fields
}

A LineTable is a data structure mapping program counters to line numbers.

In Go 1.1 and earlier, each function (represented by a Func) had its own LineTable, and the line number corresponded to a numbering of all source lines in the program, across all files. That absolute line number would then have to be converted separately to a file name and line number within the file.

In Go 1.2, the format of the data changed so that there is a single LineTable for the entire program, shared by all Funcs, and there are no absolute line numbers, just line numbers within specific files.

For the most part, LineTable's methods should be treated as an internal detail of the package; callers should use the methods on Table instead.

func NewLineTable

func NewLineTable(data []byte, text uint64) *LineTable

NewLineTable returns a new PC/line table corresponding to the encoded data. Text must be the start address of the corresponding text segment.

func (*LineTable) InlineTree

func (t *LineTable) InlineTree(f *Func, goFuncValue, baseAddr uint64, progReader io.ReaderAt) ([]InlinedCall, error)

InlineTree returns the inline tree for Func f as a sequence of InlinedCalls. goFuncValue is the value of the gosym.FuncSymName symbol. baseAddr is the address of the memory region (ELF Prog) containing goFuncValue. progReader is a ReaderAt positioned at the start of that region.

func (*LineTable) LineToPC

func (t *LineTable) LineToPC(line int, maxpc uint64) uint64

LineToPC returns the program counter for the given line number, considering only program counters before maxpc.

Deprecated: Use Table's LineToPC method instead.

func (*LineTable) PCToLine

func (t *LineTable) PCToLine(pc uint64) int

PCToLine returns the line number for the given program counter.

Deprecated: Use Table's PCToLine method instead.

type Obj

type Obj struct {
	// Funcs is a list of functions in the Obj.
	Funcs []Func
	// In Go 1.1 and earlier, Paths is a list of symbols corresponding
	// to the source file names that produced the Obj.
	// In Go 1.2, Paths is nil.
	// Use the keys of Table.Files to obtain a list of source files.
	Paths []Sym // meta
}

An Obj represents a collection of functions in a symbol table.

The exact method of division of a binary into separate Objs is an internal detail of the symbol table format.

In early versions of Go each source file became a different Obj.

In Go 1 and Go 1.1, each package produced one Obj for all Go sources and one Obj per C source file.

In Go 1.2, there is a single Obj for the entire program.

type Sym

type Sym struct {
	Value  uint64
	Type   byte
	Name   string
	GoType uint64
	// If this symbol is a function symbol, the corresponding Func
	Func *Func
	// contains filtered or unexported fields
}

Sym represents a single symbol table entry.

func (*Sym) BaseName

func (s *Sym) BaseName() string

BaseName returns the symbol name without the package or receiver name.

func (*Sym) PackageName

func (s *Sym) PackageName() string

PackageName returns the package part of the symbol name, or the empty string if there is none.

func (*Sym) ReceiverName

func (s *Sym) ReceiverName() string

ReceiverName returns the receiver type name of this symbol, or the empty string if there is none. A receiver name is only detected in the case that s.Name is fully-specified with a package name.

func (*Sym) Static

func (s *Sym) Static() bool

Static reports whether this symbol is static (not visible outside its file).

type Table

type Table struct {
	Syms  []Sym // nil for Go 1.3 and later binaries
	Funcs []Func
	Files map[string]*Obj // for Go 1.2 and later all files map to one Obj
	Objs  []Obj           // for Go 1.2 and later only one Obj in slice
	// contains filtered or unexported fields
}

Table represents a Go symbol table. It stores all of the symbols decoded from the program and provides methods to translate between symbols, names, and addresses.

func NewTable

func NewTable(symtab []byte, pcln *LineTable) (*Table, error)

NewTable decodes the Go symbol table (the ".gosymtab" section in ELF), returning an in-memory representation. Starting with Go 1.3, the Go symbol table no longer includes symbol data.

func (*Table) GetInlineTree

func (T *Table) GetInlineTree(f *Func, goFuncVal, baseaddr uint64, progReader io.ReaderAt) ([]InlinedCall, error)

func (*Table) LineToPC

func (t *Table) LineToPC(file string, line int) (pc uint64, fn *Func, err error)

LineToPC looks up the first program counter on the given line in the named file. It returns UnknownPathError or UnknownLineError if there is an error looking up this line.

func (*Table) LookupFunc

func (t *Table) LookupFunc(name string) *Func

LookupFunc returns the text, data, or bss symbol with the given name, or nil if no such symbol is found.

func (*Table) LookupSym

func (t *Table) LookupSym(name string) *Sym

LookupSym returns the text, data, or bss symbol with the given name, or nil if no such symbol is found.

func (*Table) PCToFunc

func (t *Table) PCToFunc(pc uint64) *Func

PCToFunc returns the function containing the program counter pc, or nil if there is no such function.

func (*Table) PCToLine

func (t *Table) PCToLine(pc uint64) (file string, line int, fn *Func)

PCToLine looks up line number information for a program counter. If there is no information, it returns fn == nil.

func (*Table) SymByAddr

func (t *Table) SymByAddr(addr uint64) *Sym

SymByAddr returns the text, data, or bss symbol starting at the given address.

type UnknownFileError

type UnknownFileError string

UnknownFileError represents a failure to find the specific file in the symbol table.

func (UnknownFileError) Error

func (e UnknownFileError) Error() string

type UnknownLineError

type UnknownLineError struct {
	File string
	Line int
}

UnknownLineError represents a failure to map a line to a program counter, either because the line is beyond the bounds of the file or because there is no code on the given line.

func (*UnknownLineError) Error

func (e *UnknownLineError) Error() string