# package dwarf

`import "debug/dwarf"`

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

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

An AddrType represents a machine address type.

## type ArrayType

An ArrayType represents a fixed size array type.

### func (*ArrayType) Size

### func (*ArrayType) String

## type Attr

An Attr identifies the attribute type in a DWARF Entry's Field.

### func (Attr) GoString

### func (Attr) String

## type BasicType

A BasicType holds fields common to all basic types.

### func (*BasicType) Basic

### func (*BasicType) String

## type BoolType

A BoolType represents a boolean type.

## type CharType

A CharType represents a signed character type.

## type Class

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.

### 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 (*CommonType) Size

## type ComplexType

A ComplexType represents a complex floating point type.

## type Data

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

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

## type DotDotDotType

A DotDotDotType represents the variadic ... function parameter.

### func (*DotDotDotType) 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

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

A FloatType represents a floating point type.

## type FuncType

A FuncType represents a function type.

### func (*FuncType) String

## type IntType

An IntType represents a signed integer type.

## type LineEntry

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

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

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

Reset repositions the line table reader at the beginning of the line table.

### func (*LineReader) Seek

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

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

Tell returns the current position in the line table.

## type LineReaderPos

A LineReaderPos represents a position in a line table.

## type Offset

An Offset represents the location of an Entry within the DWARF info. (See Reader.Seek.)

## type PtrType

A PtrType represents a pointer type.

### func (*PtrType) String

## type QualType

A QualType represents a type that has the C/C++ "const", "restrict", or "volatile" qualifier.

### func (*QualType) Size

### func (*QualType) String

## type Reader

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

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

A StructType represents a struct, union, or C++ class type.

### func (*StructType) Defn

### func (*StructType) String

## type Tag

A Tag is the classification (the type) of an Entry.

### func (Tag) GoString

### func (Tag) String

## type Type

A Type conventionally represents a pointer to any of the specific Type structures (CharType, StructType, etc.).

## type TypedefType

A TypedefType represents a named type.

### func (*TypedefType) Size

### func (*TypedefType) String

## type UcharType

A UcharType represents an unsigned character type.

## type UintType

A UintType represents an unsigned integer type.

## type UnspecifiedType

An UnspecifiedType represents an implicit, unknown, ambiguous or nonexistent type.

## type VoidType

A VoidType represents the C void type.

### func (*VoidType) String