diff options
Diffstat (limited to 'devdocs/go/debug%2Fdwarf%2Findex.html')
| -rw-r--r-- | devdocs/go/debug%2Fdwarf%2Findex.html | 754 |
1 files changed, 754 insertions, 0 deletions
diff --git a/devdocs/go/debug%2Fdwarf%2Findex.html b/devdocs/go/debug%2Fdwarf%2Findex.html new file mode 100644 index 00000000..312f3c19 --- /dev/null +++ b/devdocs/go/debug%2Fdwarf%2Findex.html @@ -0,0 +1,754 @@ +<h1> Package dwarf </h1> <ul id="short-nav"> +<li><code>import "debug/dwarf"</code></li> +<li><a href="#pkg-overview" class="overviewLink">Overview</a></li> +<li><a href="#pkg-index" class="indexLink">Index</a></li> +</ul> <h2 id="pkg-overview">Overview </h2> <p>Package dwarf provides access to DWARF debugging information loaded from executable files, as defined in the DWARF 2.0 Standard at <a href="http://dwarfstd.org/doc/dwarf-2.0.0.pdf">http://dwarfstd.org/doc/dwarf-2.0.0.pdf</a>. </p> +<h3 id="hdr-Security">Security</h3> <p>This package is not designed to be hardened against adversarial inputs, and is outside the scope of <a href="https://go.dev/security/policy">https://go.dev/security/policy</a>. In particular, only basic validation is done when parsing object files. As such, care should be taken when parsing untrusted inputs, as parsing malformed files may consume significant resources, or cause panics. </p> <h2 id="pkg-index">Index </h2> <ul id="manual-nav"> +<li><a href="#pkg-variables">Variables</a></li> +<li><a href="#AddrType">type AddrType</a></li> +<li><a href="#ArrayType">type ArrayType</a></li> +<li> <a href="#ArrayType.Size">func (t *ArrayType) Size() int64</a> +</li> +<li> <a href="#ArrayType.String">func (t *ArrayType) String() string</a> +</li> +<li><a href="#Attr">type Attr</a></li> +<li> <a href="#Attr.GoString">func (a Attr) GoString() string</a> +</li> +<li> <a href="#Attr.String">func (i Attr) String() string</a> +</li> +<li><a href="#BasicType">type BasicType</a></li> +<li> <a href="#BasicType.Basic">func (b *BasicType) Basic() *BasicType</a> +</li> +<li> <a href="#BasicType.String">func (t *BasicType) String() string</a> +</li> +<li><a href="#BoolType">type BoolType</a></li> +<li><a href="#CharType">type CharType</a></li> +<li><a href="#Class">type Class</a></li> +<li> <a href="#Class.GoString">func (i Class) GoString() string</a> +</li> +<li> <a href="#Class.String">func (i Class) String() string</a> +</li> +<li><a href="#CommonType">type CommonType</a></li> +<li> <a href="#CommonType.Common">func (c *CommonType) Common() *CommonType</a> +</li> +<li> <a href="#CommonType.Size">func (c *CommonType) Size() int64</a> +</li> +<li><a href="#ComplexType">type ComplexType</a></li> +<li><a href="#Data">type Data</a></li> +<li> <a href="#New">func New(abbrev, aranges, frame, info, line, pubnames, ranges, str []byte) (*Data, error)</a> +</li> +<li> <a href="#Data.AddSection">func (d *Data) AddSection(name string, contents []byte) error</a> +</li> +<li> <a href="#Data.AddTypes">func (d *Data) AddTypes(name string, types []byte) error</a> +</li> +<li> <a href="#Data.LineReader">func (d *Data) LineReader(cu *Entry) (*LineReader, error)</a> +</li> +<li> <a href="#Data.Ranges">func (d *Data) Ranges(e *Entry) ([][2]uint64, error)</a> +</li> +<li> <a href="#Data.Reader">func (d *Data) Reader() *Reader</a> +</li> +<li> <a href="#Data.Type">func (d *Data) Type(off Offset) (Type, error)</a> +</li> +<li><a href="#DecodeError">type DecodeError</a></li> +<li> <a href="#DecodeError.Error">func (e DecodeError) Error() string</a> +</li> +<li><a href="#DotDotDotType">type DotDotDotType</a></li> +<li> <a href="#DotDotDotType.String">func (t *DotDotDotType) String() string</a> +</li> +<li><a href="#Entry">type Entry</a></li> +<li> <a href="#Entry.AttrField">func (e *Entry) AttrField(a Attr) *Field</a> +</li> +<li> <a href="#Entry.Val">func (e *Entry) Val(a Attr) any</a> +</li> +<li><a href="#EnumType">type EnumType</a></li> +<li> <a href="#EnumType.String">func (t *EnumType) String() string</a> +</li> +<li><a href="#EnumValue">type EnumValue</a></li> +<li><a href="#Field">type Field</a></li> +<li><a href="#FloatType">type FloatType</a></li> +<li><a href="#FuncType">type FuncType</a></li> +<li> <a href="#FuncType.String">func (t *FuncType) String() string</a> +</li> +<li><a href="#IntType">type IntType</a></li> +<li><a href="#LineEntry">type LineEntry</a></li> +<li><a href="#LineFile">type LineFile</a></li> +<li><a href="#LineReader">type LineReader</a></li> +<li> <a href="#LineReader.Files">func (r *LineReader) Files() []*LineFile</a> +</li> +<li> <a href="#LineReader.Next">func (r *LineReader) Next(entry *LineEntry) error</a> +</li> +<li> <a href="#LineReader.Reset">func (r *LineReader) Reset()</a> +</li> +<li> <a href="#LineReader.Seek">func (r *LineReader) Seek(pos LineReaderPos)</a> +</li> +<li> <a href="#LineReader.SeekPC">func (r *LineReader) SeekPC(pc uint64, entry *LineEntry) error</a> +</li> +<li> <a href="#LineReader.Tell">func (r *LineReader) Tell() LineReaderPos</a> +</li> +<li><a href="#LineReaderPos">type LineReaderPos</a></li> +<li><a href="#Offset">type Offset</a></li> +<li><a href="#PtrType">type PtrType</a></li> +<li> <a href="#PtrType.String">func (t *PtrType) String() string</a> +</li> +<li><a href="#QualType">type QualType</a></li> +<li> <a href="#QualType.Size">func (t *QualType) Size() int64</a> +</li> +<li> <a href="#QualType.String">func (t *QualType) String() string</a> +</li> +<li><a href="#Reader">type Reader</a></li> +<li> <a href="#Reader.AddressSize">func (r *Reader) AddressSize() int</a> +</li> +<li> <a href="#Reader.ByteOrder">func (r *Reader) ByteOrder() binary.ByteOrder</a> +</li> +<li> <a href="#Reader.Next">func (r *Reader) Next() (*Entry, error)</a> +</li> +<li> <a href="#Reader.Seek">func (r *Reader) Seek(off Offset)</a> +</li> +<li> <a href="#Reader.SeekPC">func (r *Reader) SeekPC(pc uint64) (*Entry, error)</a> +</li> +<li> <a href="#Reader.SkipChildren">func (r *Reader) SkipChildren()</a> +</li> +<li><a href="#StructField">type StructField</a></li> +<li><a href="#StructType">type StructType</a></li> +<li> <a href="#StructType.Defn">func (t *StructType) Defn() string</a> +</li> +<li> <a href="#StructType.String">func (t *StructType) String() string</a> +</li> +<li><a href="#Tag">type Tag</a></li> +<li> <a href="#Tag.GoString">func (t Tag) GoString() string</a> +</li> +<li> <a href="#Tag.String">func (i Tag) String() string</a> +</li> +<li><a href="#Type">type Type</a></li> +<li><a href="#TypedefType">type TypedefType</a></li> +<li> <a href="#TypedefType.Size">func (t *TypedefType) Size() int64</a> +</li> +<li> <a href="#TypedefType.String">func (t *TypedefType) String() string</a> +</li> +<li><a href="#UcharType">type UcharType</a></li> +<li><a href="#UintType">type UintType</a></li> +<li><a href="#UnspecifiedType">type UnspecifiedType</a></li> +<li><a href="#UnsupportedType">type UnsupportedType</a></li> +<li> <a href="#UnsupportedType.String">func (t *UnsupportedType) String() string</a> +</li> +<li><a href="#VoidType">type VoidType</a></li> +<li> <a href="#VoidType.String">func (t *VoidType) String() string</a> +</li> +</ul> <h3>Package files</h3> <p> <span>attr_string.go</span> <span>buf.go</span> <span>class_string.go</span> <span>const.go</span> <span>entry.go</span> <span>line.go</span> <span>open.go</span> <span>tag_string.go</span> <span>type.go</span> <span>typeunit.go</span> <span>unit.go</span> </p> <h2 id="pkg-variables">Variables</h2> <p>ErrUnknownPC is the error returned by LineReader.ScanPC when the seek PC is not covered by any entry in the line table. </p> +<pre data-language="go">var ErrUnknownPC = errors.New("ErrUnknownPC")</pre> <h2 id="AddrType">type <span>AddrType</span> </h2> <p>An AddrType represents a machine address type. </p> +<pre data-language="go">type AddrType struct { + BasicType +} +</pre> <h2 id="ArrayType">type <span>ArrayType</span> </h2> <p>An ArrayType represents a fixed size array type. </p> +<pre data-language="go">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[]. +} +</pre> <h3 id="ArrayType.Size">func (*ArrayType) <span>Size</span> </h3> <pre data-language="go">func (t *ArrayType) Size() int64</pre> <h3 id="ArrayType.String">func (*ArrayType) <span>String</span> </h3> <pre data-language="go">func (t *ArrayType) String() string</pre> <h2 id="Attr">type <span>Attr</span> </h2> <p>An Attr identifies the attribute type in a DWARF [Entry.Field]. </p> +<pre data-language="go">type Attr uint32</pre> <pre data-language="go">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 + // The following are new in DWARF 3. + 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 + AttrBinaryScale Attr = 0x5B + AttrDecimalScale Attr = 0x5C + AttrSmall Attr = 0x5D + AttrDecimalSign Attr = 0x5E + AttrDigitCount Attr = 0x5F + AttrPictureString Attr = 0x60 + AttrMutable Attr = 0x61 + AttrThreadsScaled Attr = 0x62 + AttrExplicit Attr = 0x63 + AttrObjectPointer Attr = 0x64 + AttrEndianity Attr = 0x65 + AttrElemental Attr = 0x66 + AttrPure Attr = 0x67 + AttrRecursive Attr = 0x68 + // The following are new in DWARF 4. + AttrSignature Attr = 0x69 + AttrMainSubprogram Attr = 0x6A + AttrDataBitOffset Attr = 0x6B + AttrConstExpr Attr = 0x6C + AttrEnumClass Attr = 0x6D + AttrLinkageName Attr = 0x6E + // The following are new in DWARF 5. + AttrStringLengthBitSize Attr = 0x6F + AttrStringLengthByteSize Attr = 0x70 + AttrRank Attr = 0x71 + AttrStrOffsetsBase Attr = 0x72 + AttrAddrBase Attr = 0x73 + AttrRnglistsBase Attr = 0x74 + AttrDwoName Attr = 0x76 + AttrReference Attr = 0x77 + AttrRvalueReference Attr = 0x78 + AttrMacros Attr = 0x79 + AttrCallAllCalls Attr = 0x7A + AttrCallAllSourceCalls Attr = 0x7B + AttrCallAllTailCalls Attr = 0x7C + AttrCallReturnPC Attr = 0x7D + AttrCallValue Attr = 0x7E + AttrCallOrigin Attr = 0x7F + AttrCallParameter Attr = 0x80 + AttrCallPC Attr = 0x81 + AttrCallTailCall Attr = 0x82 + AttrCallTarget Attr = 0x83 + AttrCallTargetClobbered Attr = 0x84 + AttrCallDataLocation Attr = 0x85 + AttrCallDataValue Attr = 0x86 + AttrNoreturn Attr = 0x87 + AttrAlignment Attr = 0x88 + AttrExportSymbols Attr = 0x89 + AttrDeleted Attr = 0x8A + AttrDefaulted Attr = 0x8B + AttrLoclistsBase Attr = 0x8C +)</pre> <h3 id="Attr.GoString">func (Attr) <span>GoString</span> </h3> <pre data-language="go">func (a Attr) GoString() string</pre> <h3 id="Attr.String">func (Attr) <span>String</span> </h3> <pre data-language="go">func (i Attr) String() string</pre> <h2 id="BasicType">type <span>BasicType</span> </h2> <p>A BasicType holds fields common to all basic types. </p> +<p>See the documentation for <a href="#StructField">StructField</a> for more info on the interpretation of the BitSize/BitOffset/DataBitOffset fields. </p> +<pre data-language="go">type BasicType struct { + CommonType + BitSize int64 + BitOffset int64 + DataBitOffset int64 // Go 1.18 +} +</pre> <h3 id="BasicType.Basic">func (*BasicType) <span>Basic</span> </h3> <pre data-language="go">func (b *BasicType) Basic() *BasicType</pre> <h3 id="BasicType.String">func (*BasicType) <span>String</span> </h3> <pre data-language="go">func (t *BasicType) String() string</pre> <h2 id="BoolType">type <span>BoolType</span> </h2> <p>A BoolType represents a boolean type. </p> +<pre data-language="go">type BoolType struct { + BasicType +} +</pre> <h2 id="CharType">type <span>CharType</span> </h2> <p>A CharType represents a signed character type. </p> +<pre data-language="go">type CharType struct { + BasicType +} +</pre> <h2 id="Class">type <span>Class</span> <span title="Added in Go 1.5">1.5</span> </h2> <p>A Class is the DWARF 4 class of an attribute value. </p> +<p>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. </p> +<p>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. </p> +<pre data-language="go">type Class int</pre> <pre data-language="go">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 + + // ClassRangeListPtr 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 + + // ClassAddrPtr represents values that are an int64 offset + // into the "addr" section. + ClassAddrPtr + + // ClassLocList represents values that are an int64 offset + // into the "loclists" section. + ClassLocList + + // ClassRngList represents values that are a uint64 offset + // from the base of the "rnglists" section. + ClassRngList + + // ClassRngListsPtr represents values that are an int64 offset + // into the "rnglists" section. These are used as the base for + // ClassRngList values. + ClassRngListsPtr + + // ClassStrOffsetsPtr represents values that are an int64 + // offset into the "str_offsets" section. + ClassStrOffsetsPtr +)</pre> <h3 id="Class.GoString">func (Class) <span>GoString</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func (i Class) GoString() string</pre> <h3 id="Class.String">func (Class) <span>String</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func (i Class) String() string</pre> <h2 id="CommonType">type <span>CommonType</span> </h2> <p>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. </p> +<pre data-language="go">type CommonType struct { + ByteSize int64 // size of value of this type, in bytes + Name string // name that can be used to refer to type +} +</pre> <h3 id="CommonType.Common">func (*CommonType) <span>Common</span> </h3> <pre data-language="go">func (c *CommonType) Common() *CommonType</pre> <h3 id="CommonType.Size">func (*CommonType) <span>Size</span> </h3> <pre data-language="go">func (c *CommonType) Size() int64</pre> <h2 id="ComplexType">type <span>ComplexType</span> </h2> <p>A ComplexType represents a complex floating point type. </p> +<pre data-language="go">type ComplexType struct { + BasicType +} +</pre> <h2 id="Data">type <span>Data</span> </h2> <p>Data represents the DWARF debugging information loaded from an executable file (for example, an ELF or Mach-O executable). </p> +<pre data-language="go">type Data struct { + // contains filtered or unexported fields +} +</pre> <h3 id="New">func <span>New</span> </h3> <pre data-language="go">func New(abbrev, aranges, frame, info, line, pubnames, ranges, str []byte) (*Data, error)</pre> <p>New returns a new <a href="#Data">Data</a> 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 <span>debug/elf</span>, <span>debug/macho</span>, or <span>debug/pe</span>. </p> +<p>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. </p> +<h3 id="Data.AddSection">func (*Data) <span>AddSection</span> <span title="Added in Go 1.14">1.14</span> </h3> <pre data-language="go">func (d *Data) AddSection(name string, contents []byte) error</pre> <p>AddSection adds another DWARF section by name. The name should be a DWARF section name such as ".debug_addr", ".debug_str_offsets", and so forth. This approach is used for new DWARF sections added in DWARF 5 and later. </p> +<h3 id="Data.AddTypes">func (*Data) <span>AddTypes</span> <span title="Added in Go 1.3">1.3</span> </h3> <pre data-language="go">func (d *Data) AddTypes(name string, types []byte) error</pre> <p>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. </p> +<h3 id="Data.LineReader">func (*Data) <span>LineReader</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func (d *Data) LineReader(cu *Entry) (*LineReader, error)</pre> <p>LineReader returns a new reader for the line table of compilation unit cu, which must be an <a href="#Entry">Entry</a> with tag <a href="#TagCompileUnit">TagCompileUnit</a>. </p> +<p>If this compilation unit has no line table, it returns nil, nil. </p> +<h3 id="Data.Ranges">func (*Data) <span>Ranges</span> <span title="Added in Go 1.7">1.7</span> </h3> <pre data-language="go">func (d *Data) Ranges(e *Entry) ([][2]uint64, error)</pre> <p>Ranges returns the PC ranges covered by e, a slice of [low,high) pairs. Only some entry types, such as <a href="#TagCompileUnit">TagCompileUnit</a> or <a href="#TagSubprogram">TagSubprogram</a>, have PC ranges; for others, this will return nil with no error. </p> +<h3 id="Data.Reader">func (*Data) <span>Reader</span> </h3> <pre data-language="go">func (d *Data) Reader() *Reader</pre> <p>Reader returns a new Reader for <a href="#Data">Data</a>. The reader is positioned at byte offset 0 in the DWARF “info” section. </p> +<h3 id="Data.Type">func (*Data) <span>Type</span> </h3> <pre data-language="go">func (d *Data) Type(off Offset) (Type, error)</pre> <p>Type reads the type at off in the DWARF “info” section. </p> +<h2 id="DecodeError">type <span>DecodeError</span> </h2> <pre data-language="go">type DecodeError struct { + Name string + Offset Offset + Err string +} +</pre> <h3 id="DecodeError.Error">func (DecodeError) <span>Error</span> </h3> <pre data-language="go">func (e DecodeError) Error() string</pre> <h2 id="DotDotDotType">type <span>DotDotDotType</span> </h2> <p>A DotDotDotType represents the variadic ... function parameter. </p> +<pre data-language="go">type DotDotDotType struct { + CommonType +} +</pre> <h3 id="DotDotDotType.String">func (*DotDotDotType) <span>String</span> </h3> <pre data-language="go">func (t *DotDotDotType) String() string</pre> <h2 id="Entry">type <span>Entry</span> </h2> <p>An entry is a sequence of attribute/value pairs. </p> +<pre data-language="go">type Entry struct { + Offset Offset // offset of Entry in DWARF info + Tag Tag // tag (kind of Entry) + Children bool // whether Entry is followed by children + Field []Field +} +</pre> <h3 id="Entry.AttrField">func (*Entry) <span>AttrField</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func (e *Entry) AttrField(a Attr) *Field</pre> <p>AttrField returns the <a href="#Field">Field</a> associated with attribute <a href="#Attr">Attr</a> in <a href="#Entry">Entry</a>, or nil if there is no such attribute. </p> +<h3 id="Entry.Val">func (*Entry) <span>Val</span> </h3> <pre data-language="go">func (e *Entry) Val(a Attr) any</pre> <p>Val returns the value associated with attribute <a href="#Attr">Attr</a> in <a href="#Entry">Entry</a>, or nil if there is no such attribute. </p> +<p>A common idiom is to merge the check for nil return with the check that the value has the expected dynamic type, as in: </p> +<pre data-language="go">v, ok := e.Val(AttrSibling).(int64) +</pre> <h2 id="EnumType">type <span>EnumType</span> </h2> <p>An EnumType represents an enumerated type. The only indication of its native integer type is its ByteSize (inside <a href="#CommonType">CommonType</a>). </p> +<pre data-language="go">type EnumType struct { + CommonType + EnumName string + Val []*EnumValue +} +</pre> <h3 id="EnumType.String">func (*EnumType) <span>String</span> </h3> <pre data-language="go">func (t *EnumType) String() string</pre> <h2 id="EnumValue">type <span>EnumValue</span> </h2> <p>An EnumValue represents a single enumeration value. </p> +<pre data-language="go">type EnumValue struct { + Name string + Val int64 +} +</pre> <h2 id="Field">type <span>Field</span> </h2> <p>A Field is a single attribute/value pair in an <a href="#Entry">Entry</a>. </p> +<p>A value can be one of several "attribute classes" defined by DWARF. The Go types corresponding to each class are: </p> +<pre data-language="go">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 +</pre> <p>For unrecognized or vendor-defined attributes, <a href="#Class">Class</a> may be <a href="#ClassUnknown">ClassUnknown</a>. </p> +<pre data-language="go">type Field struct { + Attr Attr + Val any + Class Class // Go 1.5 +} +</pre> <h2 id="FloatType">type <span>FloatType</span> </h2> <p>A FloatType represents a floating point type. </p> +<pre data-language="go">type FloatType struct { + BasicType +} +</pre> <h2 id="FuncType">type <span>FuncType</span> </h2> <p>A FuncType represents a function type. </p> +<pre data-language="go">type FuncType struct { + CommonType + ReturnType Type + ParamType []Type +} +</pre> <h3 id="FuncType.String">func (*FuncType) <span>String</span> </h3> <pre data-language="go">func (t *FuncType) String() string</pre> <h2 id="IntType">type <span>IntType</span> </h2> <p>An IntType represents a signed integer type. </p> +<pre data-language="go">type IntType struct { + BasicType +} +</pre> <h2 id="LineEntry">type <span>LineEntry</span> <span title="Added in Go 1.5">1.5</span> </h2> <p>A LineEntry is a row in a DWARF line table. </p> +<pre data-language="go">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 +} +</pre> <h2 id="LineFile">type <span>LineFile</span> <span title="Added in Go 1.5">1.5</span> </h2> <p>A LineFile is a source file referenced by a DWARF line table entry. </p> +<pre data-language="go">type LineFile struct { + Name string + Mtime uint64 // Implementation defined modification time, or 0 if unknown + Length int // File length, or 0 if unknown +} +</pre> <h2 id="LineReader">type <span>LineReader</span> <span title="Added in Go 1.5">1.5</span> </h2> <p>A LineReader reads a sequence of <a href="#LineEntry">LineEntry</a> structures from a DWARF "line" section for a single compilation unit. LineEntries occur in order of increasing PC and each <a href="#LineEntry">LineEntry</a> gives metadata for the instructions from that <a href="#LineEntry">LineEntry</a>'s PC to just before the next <a href="#LineEntry">LineEntry</a>'s PC. The last entry will have the [LineEntry.EndSequence] field set. </p> +<pre data-language="go">type LineReader struct { + // contains filtered or unexported fields +} +</pre> <h3 id="LineReader.Files">func (*LineReader) <span>Files</span> <span title="Added in Go 1.14">1.14</span> </h3> <pre data-language="go">func (r *LineReader) Files() []*LineFile</pre> <p>Files returns the file name table of this compilation unit as of the current position in the line table. The file name table may be referenced from attributes in this compilation unit such as <a href="#AttrDeclFile">AttrDeclFile</a>. </p> +<p>Entry 0 is always nil, since file index 0 represents "no file". </p> +<p>The file name table of a compilation unit is not fixed. Files returns the file table as of the current position in the line table. This may contain more entries than the file table at an earlier position in the line table, though existing entries never change. </p> +<h3 id="LineReader.Next">func (*LineReader) <span>Next</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func (r *LineReader) Next(entry *LineEntry) error</pre> <p>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 <span>io.EOF</span>. </p> +<p>Rows are always in order of increasing entry.Address, but entry.Line may go forward or backward. </p> +<h3 id="LineReader.Reset">func (*LineReader) <span>Reset</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func (r *LineReader) Reset()</pre> <p>Reset repositions the line table reader at the beginning of the line table. </p> +<h3 id="LineReader.Seek">func (*LineReader) <span>Seek</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func (r *LineReader) Seek(pos LineReaderPos)</pre> <p>Seek restores the line table reader to a position returned by <a href="#LineReader.Tell">LineReader.Tell</a>. </p> +<p>The argument pos must have been returned by a call to <a href="#LineReader.Tell">LineReader.Tell</a> on this line table. </p> +<h3 id="LineReader.SeekPC">func (*LineReader) <span>SeekPC</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func (r *LineReader) SeekPC(pc uint64, entry *LineEntry) error</pre> <p>SeekPC sets *entry to the <a href="#LineEntry">LineEntry</a> that includes pc and positions the reader on the next entry in the line table. If necessary, this will seek backwards to find pc. </p> +<p>If pc is not covered by any entry in this line table, SeekPC returns <a href="#ErrUnknownPC">ErrUnknownPC</a>. In this case, *entry and the final seek position are unspecified. </p> +<p>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. </p> +<h3 id="LineReader.Tell">func (*LineReader) <span>Tell</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func (r *LineReader) Tell() LineReaderPos</pre> <p>Tell returns the current position in the line table. </p> +<h2 id="LineReaderPos">type <span>LineReaderPos</span> <span title="Added in Go 1.5">1.5</span> </h2> <p>A LineReaderPos represents a position in a line table. </p> +<pre data-language="go">type LineReaderPos struct { + // contains filtered or unexported fields +} +</pre> <h2 id="Offset">type <span>Offset</span> </h2> <p>An Offset represents the location of an <a href="#Entry">Entry</a> within the DWARF info. (See <a href="#Reader.Seek">Reader.Seek</a>.) </p> +<pre data-language="go">type Offset uint32</pre> <h2 id="PtrType">type <span>PtrType</span> </h2> <p>A PtrType represents a pointer type. </p> +<pre data-language="go">type PtrType struct { + CommonType + Type Type +} +</pre> <h3 id="PtrType.String">func (*PtrType) <span>String</span> </h3> <pre data-language="go">func (t *PtrType) String() string</pre> <h2 id="QualType">type <span>QualType</span> </h2> <p>A QualType represents a type that has the C/C++ "const", "restrict", or "volatile" qualifier. </p> +<pre data-language="go">type QualType struct { + CommonType + Qual string + Type Type +} +</pre> <h3 id="QualType.Size">func (*QualType) <span>Size</span> </h3> <pre data-language="go">func (t *QualType) Size() int64</pre> <h3 id="QualType.String">func (*QualType) <span>String</span> </h3> <pre data-language="go">func (t *QualType) String() string</pre> <h2 id="Reader">type <span>Reader</span> </h2> <p>A Reader allows reading <a href="#Entry">Entry</a> structures from a DWARF “info” section. The <a href="#Entry">Entry</a> structures are arranged in a tree. The <a href="#Reader.Next">Reader.Next</a> 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 <a href="#Entry">Entry</a> with <a href="#Tag">Tag</a> 0. </p> +<pre data-language="go">type Reader struct { + // contains filtered or unexported fields +} +</pre> <h3 id="Reader.AddressSize">func (*Reader) <span>AddressSize</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func (r *Reader) AddressSize() int</pre> <p>AddressSize returns the size in bytes of addresses in the current compilation unit. </p> +<h3 id="Reader.ByteOrder">func (*Reader) <span>ByteOrder</span> <span title="Added in Go 1.14">1.14</span> </h3> <pre data-language="go">func (r *Reader) ByteOrder() binary.ByteOrder</pre> <p>ByteOrder returns the byte order in the current compilation unit. </p> +<h3 id="Reader.Next">func (*Reader) <span>Next</span> </h3> <pre data-language="go">func (r *Reader) Next() (*Entry, error)</pre> <p>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 <a href="#Entry">Entry</a>. </p> +<h3 id="Reader.Seek">func (*Reader) <span>Seek</span> </h3> <pre data-language="go">func (r *Reader) Seek(off Offset)</pre> <p>Seek positions the <a href="#Reader">Reader</a> at offset off in the encoded entry stream. Offset 0 can be used to denote the first entry. </p> +<h3 id="Reader.SeekPC">func (*Reader) <span>SeekPC</span> <span title="Added in Go 1.7">1.7</span> </h3> <pre data-language="go">func (r *Reader) SeekPC(pc uint64) (*Entry, error)</pre> <p>SeekPC returns the <a href="#Entry">Entry</a> 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 <a href="#ErrUnknownPC">ErrUnknownPC</a> and the position of the reader is undefined. </p> +<p>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. </p> +<h3 id="Reader.SkipChildren">func (*Reader) <span>SkipChildren</span> </h3> <pre data-language="go">func (r *Reader) SkipChildren()</pre> <p>SkipChildren skips over the child entries associated with the last <a href="#Entry">Entry</a> returned by <a href="#Reader.Next">Reader.Next</a>. If that <a href="#Entry">Entry</a> did not have children or <a href="#Reader.Next">Reader.Next</a> has not been called, SkipChildren is a no-op. </p> +<h2 id="StructField">type <span>StructField</span> </h2> <p>A StructField represents a field in a struct, union, or C++ class type. </p> +<h3 id="hdr-Bit_Fields">Bit Fields</h3> <p>The BitSize, BitOffset, and DataBitOffset fields describe the bit size and offset of data members declared as bit fields in C/C++ struct/union/class types. </p> +<p>BitSize is the number of bits in the bit field. </p> +<p>DataBitOffset, if non-zero, is the number of bits from the start of the enclosing entity (e.g. containing struct/class/union) to the start of the bit field. This corresponds to the DW_AT_data_bit_offset DWARF attribute that was introduced in DWARF 4. </p> +<p>BitOffset, if non-zero, is the number of bits between the most significant bit of the storage unit holding the bit field to the most significant bit of the bit field. Here "storage unit" is the type name before the bit field (for a field "unsigned x:17", the storage unit is "unsigned"). BitOffset values can vary depending on the endianness of the system. BitOffset corresponds to the DW_AT_bit_offset DWARF attribute that was deprecated in DWARF 4 and removed in DWARF 5. </p> +<p>At most one of DataBitOffset and BitOffset will be non-zero; DataBitOffset/BitOffset will only be non-zero if BitSize is non-zero. Whether a C compiler uses one or the other will depend on compiler vintage and command line options. </p> +<p>Here is an example of C/C++ bit field use, along with what to expect in terms of DWARF bit offset info. Consider this code: </p> +<pre data-language="go">struct S { + int q; + int j:5; + int k:6; + int m:5; + int n:8; +} s; +</pre> <p>For the code above, one would expect to see the following for DW_AT_bit_offset values (using GCC 8): </p> +<pre data-language="go"> Little | Big + Endian | Endian + | +"j": 27 | 0 +"k": 21 | 5 +"m": 16 | 11 +"n": 8 | 16 +</pre> <p>Note that in the above the offsets are purely with respect to the containing storage unit for j/k/m/n -- these values won't vary based on the size of prior data members in the containing struct. </p> +<p>If the compiler emits DW_AT_data_bit_offset, the expected values would be: </p> +<pre data-language="go">"j": 32 +"k": 37 +"m": 43 +"n": 48 +</pre> <p>Here the value 32 for "j" reflects the fact that the bit field is preceded by other data members (recall that DW_AT_data_bit_offset values are relative to the start of the containing struct). Hence DW_AT_data_bit_offset values can be quite large for structs with many fields. </p> +<p>DWARF also allow for the possibility of base types that have non-zero bit size and bit offset, so this information is also captured for base types, but it is worth noting that it is not possible to trigger this behavior using mainstream languages. </p> +<pre data-language="go">type StructField struct { + Name string + Type Type + ByteOffset int64 + ByteSize int64 // usually zero; use Type.Size() for normal fields + BitOffset int64 + DataBitOffset int64 // Go 1.18 + BitSize int64 // zero if not a bit field +} +</pre> <h2 id="StructType">type <span>StructType</span> </h2> <p>A StructType represents a struct, union, or C++ class type. </p> +<pre data-language="go">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 +} +</pre> <h3 id="StructType.Defn">func (*StructType) <span>Defn</span> </h3> <pre data-language="go">func (t *StructType) Defn() string</pre> <h3 id="StructType.String">func (*StructType) <span>String</span> </h3> <pre data-language="go">func (t *StructType) String() string</pre> <h2 id="Tag">type <span>Tag</span> </h2> <p>A Tag is the classification (the type) of an <a href="#Entry">Entry</a>. </p> +<pre data-language="go">type Tag uint32</pre> <pre data-language="go">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 + TagSharedType Tag = 0x40 + // The following are new in DWARF 4. + TagTypeUnit Tag = 0x41 + TagRvalueReferenceType Tag = 0x42 + TagTemplateAlias Tag = 0x43 + // The following are new in DWARF 5. + TagCoarrayType Tag = 0x44 + TagGenericSubrange Tag = 0x45 + TagDynamicType Tag = 0x46 + TagAtomicType Tag = 0x47 + TagCallSite Tag = 0x48 + TagCallSiteParameter Tag = 0x49 + TagSkeletonUnit Tag = 0x4A + TagImmutableType Tag = 0x4B +)</pre> <h3 id="Tag.GoString">func (Tag) <span>GoString</span> </h3> <pre data-language="go">func (t Tag) GoString() string</pre> <h3 id="Tag.String">func (Tag) <span>String</span> </h3> <pre data-language="go">func (i Tag) String() string</pre> <h2 id="Type">type <span>Type</span> </h2> <p>A Type conventionally represents a pointer to any of the specific Type structures (<a href="#CharType">CharType</a>, <a href="#StructType">StructType</a>, etc.). </p> +<pre data-language="go">type Type interface { + Common() *CommonType + String() string + Size() int64 +}</pre> <h2 id="TypedefType">type <span>TypedefType</span> </h2> <p>A TypedefType represents a named type. </p> +<pre data-language="go">type TypedefType struct { + CommonType + Type Type +} +</pre> <h3 id="TypedefType.Size">func (*TypedefType) <span>Size</span> </h3> <pre data-language="go">func (t *TypedefType) Size() int64</pre> <h3 id="TypedefType.String">func (*TypedefType) <span>String</span> </h3> <pre data-language="go">func (t *TypedefType) String() string</pre> <h2 id="UcharType">type <span>UcharType</span> </h2> <p>A UcharType represents an unsigned character type. </p> +<pre data-language="go">type UcharType struct { + BasicType +} +</pre> <h2 id="UintType">type <span>UintType</span> </h2> <p>A UintType represents an unsigned integer type. </p> +<pre data-language="go">type UintType struct { + BasicType +} +</pre> <h2 id="UnspecifiedType">type <span>UnspecifiedType</span> <span title="Added in Go 1.4">1.4</span> </h2> <p>An UnspecifiedType represents an implicit, unknown, ambiguous or nonexistent type. </p> +<pre data-language="go">type UnspecifiedType struct { + BasicType +} +</pre> <h2 id="UnsupportedType">type <span>UnsupportedType</span> <span title="Added in Go 1.13">1.13</span> </h2> <p>An UnsupportedType is a placeholder returned in situations where we encounter a type that isn't supported. </p> +<pre data-language="go">type UnsupportedType struct { + CommonType + Tag Tag +} +</pre> <h3 id="UnsupportedType.String">func (*UnsupportedType) <span>String</span> <span title="Added in Go 1.13">1.13</span> </h3> <pre data-language="go">func (t *UnsupportedType) String() string</pre> <h2 id="VoidType">type <span>VoidType</span> </h2> <p>A VoidType represents the C void type. </p> +<pre data-language="go">type VoidType struct { + CommonType +} +</pre> <h3 id="VoidType.String">func (*VoidType) <span>String</span> </h3> <pre data-language="go">func (t *VoidType) String() string</pre><div class="_attribution"> + <p class="_attribution-p"> + © Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br> + <a href="http://golang.org/pkg/debug/dwarf/" class="_attribution-link">http://golang.org/pkg/debug/dwarf/</a> + </p> +</div> |
