version: 1.10
package dwarf
import "debug/dwarf"
Overview
Package dwarf provides access to DWARF debugging information loaded from
executable files, as defined in the DWARF 2.0 Standard at
http://dwarfstd.org/doc/dwarf-2.0.0.pdf
Index
- Variables
- type AddrType
- type ArrayType
- type Attr
- type BasicType
- type BoolType
- type CharType
- type Class
- type CommonType
- type ComplexType
- type Data
- func New(abbrev, aranges, frame, info, line, pubnames, ranges, str []byte) (*Data, error)
- func (d *Data) AddTypes(name string, types []byte) error
- func (d Data) LineReader(cu Entry) (*LineReader, error)
- func (d Data) Ranges(e Entry) ([][2]uint64, error)
- func (d Data) Reader() Reader
- func (d *Data) Type(off Offset) (Type, error)
- type DecodeError
- type DotDotDotType
- type Entry
- type EnumType
- type EnumValue
- type Field
- type FloatType
- type FuncType
- type IntType
- type LineEntry
- type LineFile
- type LineReader
- type LineReaderPos
- type Offset
- type PtrType
- type QualType
- type Reader
- type StructField
- type StructType
- type Tag
- type Type
- type TypedefType
- type UcharType
- type UintType
- type UnspecifiedType
- type VoidType
Package files
buf.go class_string.go const.go entry.go line.go open.go type.go typeunit.go unit.go
Variables
ErrUnknownPC is the error returned by LineReader.ScanPC when the seek PC is not
covered by any entry in the line table.
type AddrType
¶
- type AddrType struct {
- BasicType
- }
An AddrType represents a machine address type.
type ArrayType
¶
- type ArrayType struct {
- CommonType
- Type Type
- StrideBitSize int64 // if > 0, number of bits to hold each element
- Count int64 // if == -1, an incomplete array, like char x[].
- }
An ArrayType represents a fixed size array type.
func (*ArrayType) Size
¶
func (*ArrayType) String
¶
type Attr
¶
- type Attr uint32
An Attr identifies the attribute type in a DWARF Entry’s Field.
- const (
- AttrSibling Attr = 0x01
- AttrLocation Attr = 0x02
- AttrName Attr = 0x03
- AttrOrdering Attr = 0x09
- AttrByteSize Attr = 0x0B
- AttrBitOffset Attr = 0x0C
- AttrBitSize Attr = 0x0D
- AttrStmtList Attr = 0x10
- AttrLowpc Attr = 0x11
- AttrHighpc Attr = 0x12
- AttrLanguage Attr = 0x13
- AttrDiscr Attr = 0x15
- AttrDiscrValue Attr = 0x16
- AttrVisibility Attr = 0x17
- AttrImport Attr = 0x18
- AttrStringLength Attr = 0x19
- AttrCommonRef Attr = 0x1A
- AttrCompDir Attr = 0x1B
- AttrConstValue Attr = 0x1C
- AttrContainingType Attr = 0x1D
- AttrDefaultValue Attr = 0x1E
- AttrInline Attr = 0x20
- AttrIsOptional Attr = 0x21
- AttrLowerBound Attr = 0x22
- AttrProducer Attr = 0x25
- AttrPrototyped Attr = 0x27
- AttrReturnAddr Attr = 0x2A
- AttrStartScope Attr = 0x2C
- AttrStrideSize Attr = 0x2E
- AttrUpperBound Attr = 0x2F
- AttrAbstractOrigin Attr = 0x31
- AttrAccessibility Attr = 0x32
- AttrAddrClass Attr = 0x33
- AttrArtificial Attr = 0x34
- AttrBaseTypes Attr = 0x35
- AttrCalling Attr = 0x36
- AttrCount Attr = 0x37
- AttrDataMemberLoc Attr = 0x38
- AttrDeclColumn Attr = 0x39
- AttrDeclFile Attr = 0x3A
- AttrDeclLine Attr = 0x3B
- AttrDeclaration Attr = 0x3C
- AttrDiscrList Attr = 0x3D
- AttrEncoding Attr = 0x3E
- AttrExternal Attr = 0x3F
- AttrFrameBase Attr = 0x40
- AttrFriend Attr = 0x41
- AttrIdentifierCase Attr = 0x42
- AttrMacroInfo Attr = 0x43
- AttrNamelistItem Attr = 0x44
- AttrPriority Attr = 0x45
- AttrSegment Attr = 0x46
- AttrSpecification Attr = 0x47
- AttrStaticLink Attr = 0x48
- AttrType Attr = 0x49
- AttrUseLocation Attr = 0x4A
- AttrVarParam Attr = 0x4B
- AttrVirtuality Attr = 0x4C
- AttrVtableElemLoc Attr = 0x4D
- AttrAllocated Attr = 0x4E
- AttrAssociated Attr = 0x4F
- AttrDataLocation Attr = 0x50
- AttrStride Attr = 0x51
- AttrEntrypc Attr = 0x52
- AttrUseUTF8 Attr = 0x53
- AttrExtension Attr = 0x54
- AttrRanges Attr = 0x55
- AttrTrampoline Attr = 0x56
- AttrCallColumn Attr = 0x57
- AttrCallFile Attr = 0x58
- AttrCallLine Attr = 0x59
- AttrDescription Attr = 0x5A
- )
func (Attr) GoString
¶
func (Attr) String
¶
type BasicType
¶
- type BasicType struct {
- CommonType
- BitSize int64
- BitOffset int64
- }
A BasicType holds fields common to all basic types.
func (*BasicType) Basic
¶
func (*BasicType) String
¶
type BoolType
¶
- type BoolType struct {
- BasicType
- }
A BoolType represents a boolean type.
type CharType
¶
- type CharType struct {
- BasicType
- }
A CharType represents a signed character type.
type Class
¶
- type Class int
A Class is the DWARF 4 class of an attribute value.
In general, a given attribute’s value may take on one of several possible
classes defined by DWARF, each of which leads to a slightly different
interpretation of the attribute.
DWARF version 4 distinguishes attribute value classes more finely than previous
versions of DWARF. The reader will disambiguate coarser classes from earlier
versions of DWARF into the appropriate DWARF 4 class. For example, DWARF 2 uses
“constant” for constants as well as all types of section offsets, but the reader
will canonicalize attributes in DWARF 2 files that refer to section offsets to
one of the Class*Ptr classes, even though these classes were only defined in
DWARF 3.
- const (
- // ClassUnknown represents values of unknown DWARF class.
- ClassUnknown Class = iota
- // ClassAddress represents values of type uint64 that are
- // addresses on the target machine.
- ClassAddress
- // ClassBlock represents values of type []byte whose
- // interpretation depends on the attribute.
- ClassBlock
- // ClassConstant represents values of type int64 that are
- // constants. The interpretation of this constant depends on
- // the attribute.
- ClassConstant
- // ClassExprLoc represents values of type []byte that contain
- // an encoded DWARF expression or location description.
- ClassExprLoc
- // ClassFlag represents values of type bool.
- ClassFlag
- // ClassLinePtr represents values that are an int64 offset
- // into the "line" section.
- ClassLinePtr
- // ClassLocListPtr represents values that are an int64 offset
- // into the "loclist" section.
- ClassLocListPtr
- // ClassMacPtr represents values that are an int64 offset into
- // the "mac" section.
- ClassMacPtr
- // ClassMacPtr represents values that are an int64 offset into
- // the "rangelist" section.
- ClassRangeListPtr
- // ClassReference represents values that are an Offset offset
- // of an Entry in the info section (for use with Reader.Seek).
- // The DWARF specification combines ClassReference and
- // ClassReferenceSig into class "reference".
- ClassReference
- // ClassReferenceSig represents values that are a uint64 type
- // signature referencing a type Entry.
- ClassReferenceSig
- // ClassString represents values that are strings. If the
- // compilation unit specifies the AttrUseUTF8 flag (strongly
- // recommended), the string value will be encoded in UTF-8.
- // Otherwise, the encoding is unspecified.
- ClassString
- // ClassReferenceAlt represents values of type int64 that are
- // an offset into the DWARF "info" section of an alternate
- // object file.
- ClassReferenceAlt
- // ClassStringAlt represents values of type int64 that are an
- // offset into the DWARF string section of an alternate object
- // file.
- ClassStringAlt
- )
func (Class) GoString
¶
func (Class) String
¶
type CommonType
¶
A CommonType holds fields common to multiple types. If a field is not known or
not applicable for a given type, the zero value is used.
func (*CommonType) Common
¶
- func (c *CommonType) Common() *CommonType
func (*CommonType) Size
¶
- func (c *CommonType) Size() int64
type ComplexType
¶
- type ComplexType struct {
- BasicType
- }
A ComplexType represents a complex floating point type.
type Data
¶
- type Data struct {
- // contains filtered or unexported fields
- }
Data represents the DWARF debugging information loaded from an executable file
(for example, an ELF or Mach-O executable).
func New
¶
New returns a new Data object initialized from the given parameters. Rather than
calling this function directly, clients should typically use the DWARF method of
the File type of the appropriate package debug/elf, debug/macho, or debug/pe.
The []byte arguments are the data from the corresponding debug section in the
object file; for example, for an ELF object, abbrev is the contents of the
“.debug_abbrev” section.
func (*Data) AddTypes
¶
AddTypes will add one .debug_types section to the DWARF data. A typical object
with DWARF version 4 debug info will have multiple .debug_types sections. The
name is used for error reporting only, and serves to distinguish one
.debug_types section from another.
func (*Data) LineReader
¶
- func (d *Data) LineReader(cu *Entry) (*LineReader, error)
LineReader returns a new reader for the line table of compilation unit cu, which
must be an Entry with tag TagCompileUnit.
If this compilation unit has no line table, it returns nil, nil.
func (*Data) Ranges
¶
Ranges returns the PC ranges covered by e, a slice of [low,high) pairs. Only
some entry types, such as TagCompileUnit or TagSubprogram, have PC ranges; for
others, this will return nil with no error.
func (*Data) Reader
¶
Reader returns a new Reader for Data. The reader is positioned at byte offset 0
in the DWARF ``info’’ section.
func (*Data) Type
¶
Type reads the type at off in the DWARF ``info’’ section.
type DecodeError
¶
func (DecodeError) Error
¶
- func (e DecodeError) Error() string
type DotDotDotType
¶
- type DotDotDotType struct {
- CommonType
- }
A DotDotDotType represents the variadic … function parameter.
func (*DotDotDotType) String
¶
- func (t *DotDotDotType) String() string
type Entry
¶
An entry is a sequence of attribute/value pairs.
func (*Entry) AttrField
¶
AttrField returns the Field associated with attribute Attr in Entry, or nil if
there is no such attribute.
func (*Entry) Val
¶
Val returns the value associated with attribute Attr in Entry, or nil if there
is no such attribute.
A common idiom is to merge the check for nil return with the check that the
value has the expected dynamic type, as in:
v, ok := e.Val(AttrSibling).(int64)
type EnumType
¶
- type EnumType struct {
- CommonType
- EnumName string
- Val []*EnumValue
- }
An EnumType represents an enumerated type. The only indication of its native
integer type is its ByteSize (inside CommonType).
func (*EnumType) String
¶
type EnumValue
¶
An EnumValue represents a single enumeration value.
type Field
¶
A Field is a single attribute/value pair in an Entry.
A value can be one of several “attribute classes” defined by DWARF. The Go types
corresponding to each class are:
DWARF class Go type Class
----------- ------- -----
address uint64 ClassAddress
block []byte ClassBlock
constant int64 ClassConstant
flag bool ClassFlag
reference
to info dwarf.Offset ClassReference
to type unit uint64 ClassReferenceSig
string string ClassString
exprloc []byte ClassExprLoc
lineptr int64 ClassLinePtr
loclistptr int64 ClassLocListPtr
macptr int64 ClassMacPtr
rangelistptr int64 ClassRangeListPtr
For unrecognized or vendor-defined attributes, Class may be ClassUnknown.
type FloatType
¶
- type FloatType struct {
- BasicType
- }
A FloatType represents a floating point type.
type FuncType
¶
- type FuncType struct {
- CommonType
- ReturnType Type
- ParamType []Type
- }
A FuncType represents a function type.
func (*FuncType) String
¶
type IntType
¶
- type IntType struct {
- BasicType
- }
An IntType represents a signed integer type.
type LineEntry
¶
- type LineEntry struct {
- // Address is the program-counter value of a machine
- // instruction generated by the compiler. This LineEntry
- // applies to each instruction from Address to just before the
- // Address of the next LineEntry.
- Address uint64
- // OpIndex is the index of an operation within a VLIW
- // instruction. The index of the first operation is 0. For
- // non-VLIW architectures, it will always be 0. Address and
- // OpIndex together form an operation pointer that can
- // reference any individual operation within the instruction
- // stream.
- OpIndex int
- // File is the source file corresponding to these
- // instructions.
- File *LineFile
- // Line is the source code line number corresponding to these
- // instructions. Lines are numbered beginning at 1. It may be
- // 0 if these instructions cannot be attributed to any source
- // line.
- Line int
- // Column is the column number within the source line of these
- // instructions. Columns are numbered beginning at 1. It may
- // be 0 to indicate the "left edge" of the line.
- Column int
- // IsStmt indicates that Address is a recommended breakpoint
- // location, such as the beginning of a line, statement, or a
- // distinct subpart of a statement.
- IsStmt bool
- // BasicBlock indicates that Address is the beginning of a
- // basic block.
- BasicBlock bool
- // PrologueEnd indicates that Address is one (of possibly
- // many) PCs where execution should be suspended for a
- // breakpoint on entry to the containing function.
- //
- // Added in DWARF 3.
- PrologueEnd bool
- // EpilogueBegin indicates that Address is one (of possibly
- // many) PCs where execution should be suspended for a
- // breakpoint on exit from this function.
- //
- // Added in DWARF 3.
- EpilogueBegin bool
- // ISA is the instruction set architecture for these
- // instructions. Possible ISA values should be defined by the
- // applicable ABI specification.
- //
- // Added in DWARF 3.
- ISA int
- // Discriminator is an arbitrary integer indicating the block
- // to which these instructions belong. It serves to
- // distinguish among multiple blocks that may all have with
- // the same source file, line, and column. Where only one
- // block exists for a given source position, it should be 0.
- //
- // Added in DWARF 3.
- Discriminator int
- // EndSequence indicates that Address is the first byte after
- // the end of a sequence of target machine instructions. If it
- // is set, only this and the Address field are meaningful. A
- // line number table may contain information for multiple
- // potentially disjoint instruction sequences. The last entry
- // in a line table should always have EndSequence set.
- EndSequence bool
- }
A LineEntry is a row in a DWARF line table.
type LineFile
¶
A LineFile is a source file referenced by a DWARF line table entry.
type LineReader
¶
- type LineReader struct {
- // contains filtered or unexported fields
- }
A LineReader reads a sequence of LineEntry structures from a DWARF “line”
section for a single compilation unit. LineEntries occur in order of increasing
PC and each LineEntry gives metadata for the instructions from that LineEntry’s
PC to just before the next LineEntry’s PC. The last entry will have its
EndSequence field set.
func (*LineReader) Next
¶
- func (r *LineReader) Next(entry *LineEntry) error
Next sets *entry to the next row in this line table and moves to the next row.
If there are no more entries and the line table is properly terminated, it
returns io.EOF.
Rows are always in order of increasing entry.Address, but entry.Line may go
forward or backward.
func (*LineReader) Reset
¶
- func (r *LineReader) Reset()
Reset repositions the line table reader at the beginning of the line table.
func (*LineReader) Seek
¶
- func (r *LineReader) Seek(pos LineReaderPos)
Seek restores the line table reader to a position returned by Tell.
The argument pos must have been returned by a call to Tell on this line table.
func (*LineReader) SeekPC
¶
- func (r *LineReader) SeekPC(pc uint64, entry *LineEntry) error
SeekPC sets *entry to the LineEntry that includes pc and positions the reader on
the next entry in the line table. If necessary, this will seek backwards to find
pc.
If pc is not covered by any entry in this line table, SeekPC returns
ErrUnknownPC. In this case, *entry and the final seek position are unspecified.
Note that DWARF line tables only permit sequential, forward scans. Hence, in the
worst case, this takes time linear in the size of the line table. If the caller
wishes to do repeated fast PC lookups, it should build an appropriate index of
the line table.
func (*LineReader) Tell
¶
- func (r *LineReader) Tell() LineReaderPos
Tell returns the current position in the line table.
type LineReaderPos
¶
- type LineReaderPos struct {
- // contains filtered or unexported fields
- }
A LineReaderPos represents a position in a line table.
type Offset
¶
- type Offset uint32
An Offset represents the location of an Entry within the DWARF info. (See
Reader.Seek.)
type PtrType
¶
- type PtrType struct {
- CommonType
- Type Type
- }
A PtrType represents a pointer type.
func (*PtrType) String
¶
type QualType
¶
- type QualType struct {
- CommonType
- Qual string
- Type Type
- }
A QualType represents a type that has the C/C++ “const”, “restrict”, or
“volatile” qualifier.
func (*QualType) Size
¶
func (*QualType) String
¶
type Reader
¶
- type Reader struct {
- // contains filtered or unexported fields
- }
A Reader allows reading Entry structures from a DWARF ``info’’ section. The
Entry structures are arranged in a tree. The Reader’s Next function return
successive entries from a pre-order traversal of the tree. If an entry has
children, its Children field will be true, and the children follow, terminated
by an Entry with Tag 0.
func (*Reader) AddressSize
¶
AddressSize returns the size in bytes of addresses in the current compilation
unit.
func (*Reader) Next
¶
Next reads the next entry from the encoded entry stream. It returns nil, nil
when it reaches the end of the section. It returns an error if the current
offset is invalid or the data at the offset cannot be decoded as a valid Entry.
func (*Reader) Seek
¶
Seek positions the Reader at offset off in the encoded entry stream. Offset 0
can be used to denote the first entry.
func (*Reader) SeekPC
¶
SeekPC returns the Entry for the compilation unit that includes pc, and
positions the reader to read the children of that unit. If pc is not covered by
any unit, SeekPC returns ErrUnknownPC and the position of the reader is
undefined.
Because compilation units can describe multiple regions of the executable, in
the worst case SeekPC must search through all the ranges in all the compilation
units. Each call to SeekPC starts the search at the compilation unit of the last
call, so in general looking up a series of PCs will be faster if they are
sorted. If the caller wishes to do repeated fast PC lookups, it should build an
appropriate index using the Ranges method.
func (*Reader) SkipChildren
¶
- func (r *Reader) SkipChildren()
SkipChildren skips over the child entries associated with the last Entry
returned by Next. If that Entry did not have children or Next has not been
called, SkipChildren is a no-op.
type StructField
¶
A StructField represents a field in a struct, union, or C++ class type.
type StructType
¶
- type StructType struct {
- CommonType
- StructName string
- Kind string // "struct", "union", or "class".
- Field []*StructField
- Incomplete bool // if true, struct, union, class is declared but not defined
- }
A StructType represents a struct, union, or C++ class type.
func (*StructType) Defn
¶
- func (t *StructType) Defn() string
func (*StructType) String
¶
- func (t *StructType) String() string
type Tag
¶
- type Tag uint32
A Tag is the classification (the type) of an Entry.
- const (
- TagArrayType Tag = 0x01
- TagClassType Tag = 0x02
- TagEntryPoint Tag = 0x03
- TagEnumerationType Tag = 0x04
- TagFormalParameter Tag = 0x05
- TagImportedDeclaration Tag = 0x08
- TagLabel Tag = 0x0A
- TagLexDwarfBlock Tag = 0x0B
- TagMember Tag = 0x0D
- TagPointerType Tag = 0x0F
- TagReferenceType Tag = 0x10
- TagCompileUnit Tag = 0x11
- TagStringType Tag = 0x12
- TagStructType Tag = 0x13
- TagSubroutineType Tag = 0x15
- TagTypedef Tag = 0x16
- TagUnionType Tag = 0x17
- TagUnspecifiedParameters Tag = 0x18
- TagVariant Tag = 0x19
- TagCommonDwarfBlock Tag = 0x1A
- TagCommonInclusion Tag = 0x1B
- TagInheritance Tag = 0x1C
- TagInlinedSubroutine Tag = 0x1D
- TagModule Tag = 0x1E
- TagPtrToMemberType Tag = 0x1F
- TagSetType Tag = 0x20
- TagSubrangeType Tag = 0x21
- TagWithStmt Tag = 0x22
- TagAccessDeclaration Tag = 0x23
- TagBaseType Tag = 0x24
- TagCatchDwarfBlock Tag = 0x25
- TagConstType Tag = 0x26
- TagConstant Tag = 0x27
- TagEnumerator Tag = 0x28
- TagFileType Tag = 0x29
- TagFriend Tag = 0x2A
- TagNamelist Tag = 0x2B
- TagNamelistItem Tag = 0x2C
- TagPackedType Tag = 0x2D
- TagSubprogram Tag = 0x2E
- TagTemplateTypeParameter Tag = 0x2F
- TagTemplateValueParameter Tag = 0x30
- TagThrownType Tag = 0x31
- TagTryDwarfBlock Tag = 0x32
- TagVariantPart Tag = 0x33
- TagVariable Tag = 0x34
- TagVolatileType Tag = 0x35
- // The following are new in DWARF 3.
- TagDwarfProcedure Tag = 0x36
- TagRestrictType Tag = 0x37
- TagInterfaceType Tag = 0x38
- TagNamespace Tag = 0x39
- TagImportedModule Tag = 0x3A
- TagUnspecifiedType Tag = 0x3B
- TagPartialUnit Tag = 0x3C
- TagImportedUnit Tag = 0x3D
- TagMutableType Tag = 0x3E // Later removed from DWARF.
- TagCondition Tag = 0x3F
- Tag = 0x40
- // The following are new in DWARF 4.
- TagTypeUnit Tag = 0x41
- TagRvalueReferenceType Tag = 0x42
- TagTemplateAlias Tag = 0x43
- )
func (Tag) GoString
¶
func (Tag) String
¶
type Type
¶
- type Type interface {
- Common() *CommonType
- String() string
- Size() int64
- }
A Type conventionally represents a pointer to any of the specific Type
structures (CharType, StructType, etc.).
type TypedefType
¶
- type TypedefType struct {
- CommonType
- Type Type
- }
A TypedefType represents a named type.
func (*TypedefType) Size
¶
- func (t *TypedefType) Size() int64
func (*TypedefType) String
¶
- func (t *TypedefType) String() string
type UcharType
¶
- type UcharType struct {
- BasicType
- }
A UcharType represents an unsigned character type.
type UintType
¶
- type UintType struct {
- BasicType
- }
A UintType represents an unsigned integer type.
type UnspecifiedType
¶
- type UnspecifiedType struct {
- BasicType
- }
An UnspecifiedType represents an implicit, unknown, ambiguous or nonexistent
type.
type VoidType
¶
- type VoidType struct {
- CommonType
- }
A VoidType represents the C void type.