Package ghidra.app.util.bin.format.dwarf4

# Class DWARFUtil

java.lang.Object
ghidra.app.util.bin.format.dwarf4.DWARFUtil

public class DWARFUtil extends Object

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `DWARFUtil.LengthResult`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DWARFUtil()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `appendComment(Program program, Address address, int commentType, String prefix, String comment, String sep)`
  `static void`
  `appendDescription(DataTypeComponent dtc, String description, String sep)`
  Append a string to a description of a field in a structure.
  `static void`
  `appendDescription(DataType dt, String description, String sep)`
  Append a string to a `DataType`'s description.
  `static List<Varnode>`
  `convertRegisterListToVarnodeStorage(List<Register> registers, int dataTypeSize)`
  `static List<String>`
  `findLinkageNameInChildren(DebugInfoEntry die)`
  Try to find gnu mangled name nesting info in a DIE's children's linkage strings.
  `static String`
  `getAnonNameForMeFromParentContext(DIEAggregate diea)`
  Creates a name for anon types based on their position in their parent's childList.
  `static String`
  `getAnonNameForMeFromParentContext2(DIEAggregate diea)`
  Creates a name for anon types based on the names of sibling entries that are using the anon type.
  `static CodeUnit`
  `getCodeUnitForComment(Program program, Address address)`
  `static String`
  `getContainerTypeName(DIEAggregate diea)`
  Returns a string that describes what kind of object is specified by the `DIEAggregate`.
  `static ResourceFile`
  `getLanguageDefinitionDirectory(Language lang)`
  Returns the base directory of a language definition.
  `static ResourceFile`
  `getLanguageExternalFile(Language lang, String name)`
  Returns a file that has been referenced in the specified `language's` ldefs description via a
  `static String`
  `getLanguageExternalNameValue(Language lang, String name)`
  Returns a value specified in a `Language` definition via a
  `static String`
  `getLexicalBlockName(DIEAggregate diea)`
  Create a name for a lexical block, with "_" separated numbers indicating nesting information of the lexical block.
  `static int`
  `getMyPositionInParent(DebugInfoEntry die)`
  Returns the ordinal position of this `DebugInfoEntry` in it's parent.
  `static DIEAggregate`
  `getReferringTypedef(DIEAggregate diea)`
  Returns the `DIEAggregate` of a typedef that points to the specified datatype.
  `static Field`
  `getStaticFinalFieldWithValue(Class<?> clazz, long value)`
  Searches a Class for a final static variable that has a specific numeric value.
  `static String`
  `getStructLayoutFingerprint(DIEAggregate diea)`
  Creates a fingerprint of the layout of an (anonymous) structure using its size, number of members, and the hashcode of the member field names.
  `static SymbolType`
  `getSymbolTypeFromDIE(DIEAggregate diea)`
  Returns the `SymbolType` that corresponds to the specified `DIEAggregate`.
  `static String`
  `getTemplateBaseName(String name)`
  Determines if a name is a C++ style templated name.
  `static boolean`
  `isEmptyArray(DataType dt)`
  `static boolean`
  `isPointerDataType(DIEAggregate diea)`
  `static boolean`
  `isPointerTo(DIEAggregate targetDIEA, DIEAggregate testDIEA)`
  `static boolean`
  `isStackVarnode(Varnode varnode)`
  `static boolean`
  `isThisParam(DIEAggregate paramDIEA)`
  `static boolean`
  `isVoid(DataType dt)`
  `static boolean`
  `isZeroByteDataType(DataType dt)`
  `static void`
  `packCompositeIfPossible(Composite original, DataTypeManager dtm)`
  `static List<String>`
  `parseMangledNestings(String s)`
  A lightweight attempt to get nesting (ie.
  `static long`
  `readAddressAsLong(BinaryReader reader, byte pointerSize)`
  Reads a variable-sized unsigned 'address' value from a `BinaryReader` and returns it as a 64 bit java long.
  `static DWARFUtil.LengthResult`
  `readLength(BinaryReader reader, Program program)`
  Read a variable-length length value from the stream.
  `static long`
  `readOffsetByDWARFformat(BinaryReader reader, int dwarfFormat)`
  Read an offset value who's size depends on the DWARF format: 32 vs 64.
  `static int`
  `readVarSizedUInt(BinaryReader reader, int size)`
  Read a variable-sized unsigned integer and return it as a java signed int.
  `static long`
  `readVarSizedULong(BinaryReader reader, int pointerSize)`
  Read a variable-sized unsigned integer and return it as a java signed long.
  `static String`
  `toString(Class<?> clazz, int value)`
  Converts a integer value to its corresponding symbolic name from the set of "public static final" member variables in a class.
  `static String`
  `toString(Class<?> clazz, long value)`
  Returns the field name of a final static variable in class `clazz` which holds a specific value.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### DWARFUtil

    public DWARFUtil()

- ## Method Details

  - ### toString

    public static String toString(Class<?> clazz, int value)
    Converts a integer value to its corresponding symbolic name from the set of "public static final" member variables in a class.

    This is a bit of a hack and probably originated from pre-java Enum days.

    Parameters:
      `clazz` - The `Class` to search for the matching static value.
      `value` - the integer value to search for
    Returns:
      the String name of the matching field.

  - ### toString

    public static String toString(Class<?> clazz, long value)
    Returns the field name of a final static variable in class `clazz` which holds a specific value.

    Can be thought of as an enum numeric value to to name lookup.

    Parameters:
      `clazz` -
      `value` -
    Returns:

  - ### getStaticFinalFieldWithValue

    public static Field getStaticFinalFieldWithValue(Class<?> clazz, long value)
    Searches a Class for a final static variable that has a specific numeric value.
    Parameters:
      `clazz` - Class to search.
      `value` - numeric value to search for
    Returns:
      Java reflection `Field` that has the specified value or null

  - ### getContainerTypeName

    public static String getContainerTypeName(DIEAggregate diea)
    Returns a string that describes what kind of object is specified by the `DIEAggregate`.

    Used to create a name for anonymous types.

    Parameters:
      `diea` - `DIEAggregate`
    Returns:
      String describing the type of the DIEA.

  - ### getSymbolTypeFromDIE

    public static SymbolType getSymbolTypeFromDIE(DIEAggregate diea)
    Returns the `SymbolType` that corresponds to the specified `DIEAggregate`.

    The mapping between DIE type and SymbolType is not exact. There is no matching SymbolType for a DWARF static variable, so "LOCAL_VAR" is used currently.

    This mainly is used in constructing a NamespacePath, and the only critical usage there is Namespace vs. Class vs. everything else.

    Parameters:
      `diea` - `DIEAggregate` to query
    Returns:
      `SymbolType`

  - ### parseMangledNestings

    public static List<String> parseMangledNestings(String s)
    A lightweight attempt to get nesting (ie. namespaces and such) information from gnu mangled name strings.

    For example, "_ZN19class1_inline_funcs3fooEv" -> [19 chars]'class1_inline_funcs', [3 chars]'foo'

    Parameters:
      `s` -
    Returns:

  - ### findLinkageNameInChildren

    public static List<String> findLinkageNameInChildren(DebugInfoEntry die)
    Try to find gnu mangled name nesting info in a DIE's children's linkage strings.

    Parameters:
      `die` -
    Returns:
      a list of string of nesting names, ending with what should be the DIE parameter's name.

  - ### getTemplateBaseName

    public static String getTemplateBaseName(String name)
    Determines if a name is a C++ style templated name. If so, returns just the base portion of the name. The name must have a start and end angle bracket: '<' and '>'.

    operator<() and operator<<() are handled so their angle brackets don't trigger the template start/end angle bracket incorrectly.

    Parameters:
      `name` - symbol name with C++ template portions
    Returns:
      base portion of the symbol name without template portion

  - ### getAnonNameForMeFromParentContext

    public static String getAnonNameForMeFromParentContext(DIEAggregate diea)
    Creates a name for anon types based on their position in their parent's childList.

    Parameters:
      `diea` - the die aggregate.
    Returns:
      the anonymous name of the die aggregate.

  - ### getAnonNameForMeFromParentContext2

    public static String getAnonNameForMeFromParentContext2(DIEAggregate diea)
    Creates a name for anon types based on the names of sibling entries that are using the anon type.

    Example: "anon_struct_for_field1_field2"

    Falls back to `getAnonNameForMeFromParentContext(DIEAggregate)` if no siblings found.

    Parameters:
      `diea` - the die aggregate.
    Returns:
      the anonymous name of the die aggregate.

  - ### getStructLayoutFingerprint

    public static String getStructLayoutFingerprint(DIEAggregate diea)
    Creates a fingerprint of the layout of an (anonymous) structure using its size, number of members, and the hashcode of the member field names.
    Parameters:
      `diea` - struct/union/class
    Returns:
      formatted string, example "80_5_73dc6de9" (80 bytes, 5 fields, hex hash of field names)

  - ### getLexicalBlockName

    public static String getLexicalBlockName(DIEAggregate diea)
    Create a name for a lexical block, with "_" separated numbers indicating nesting information of the lexical block.
    Parameters:
      `diea` - `DIEAggregate` pointing to a lexical block entry.
    Returns:
      string, ie. "lexical_block_1_2_3"

  - ### getMyPositionInParent

    public static int getMyPositionInParent(DebugInfoEntry die)
    Returns the ordinal position of this `DebugInfoEntry` in it's parent.
    Parameters:
      `die` - `DebugInfoEntry`
    Returns:
      int index of ourself in our parent, or -1 if not found in parent.

  - ### appendDescription

    public static void appendDescription(DataType dt, String description, String sep)
    Append a string to a `DataType`'s description.
    Parameters:
      `dt` - `DataType`
      `description` - string to append, if null or empty nothing happens.
      `sep` - characters to place after previous description to separate it from the new portion.

  - ### appendDescription

    public static void appendDescription(DataTypeComponent dtc, String description, String sep)
    Append a string to a description of a field in a structure.
    Parameters:
      `dtc` - the `field` in a struct
      `description` - string to append, if null or empty nothing happens.
      `sep` - characters to place after previous description to separate it from the new portion.

  - ### appendComment

    public static void appendComment(Program program, Address address, int commentType, String prefix, String comment, String sep)

  - ### getCodeUnitForComment

    public static CodeUnit getCodeUnitForComment(Program program, Address address)

  - ### readOffsetByDWARFformat

    public static long readOffsetByDWARFformat(BinaryReader reader, int dwarfFormat) throws IOException
    Read an offset value who's size depends on the DWARF format: 32 vs 64.

    Parameters:
      `reader` - BinaryReader pointing to the value to read
      `dwarfFormat` - - See `DWARFCompilationUnit.DWARF_32` and `DWARFCompilationUnit.DWARF_64`.
    Returns:
      the offset value
    Throws:
      `IOException` - if an I/O error occurs or bad dwarfFormat value

  - ### readVarSizedULong

    public static long readVarSizedULong(BinaryReader reader, int pointerSize) throws IOException
    Read a variable-sized unsigned integer and return it as a java signed long.

    Parameters:
      `reader` - `BinaryReader` to read the data from
      `pointerSize` - number of bytes the value is stored in, must be 1, 2, 4, or 8.
    Returns:
      unsigned long integer value.
    Throws:
      `IOException` - if error

  - ### readVarSizedUInt

    public static int readVarSizedUInt(BinaryReader reader, int size) throws IOException
    Read a variable-sized unsigned integer and return it as a java signed int.

    Unsigned 32 bit int values larger than java's signed Integer.MAX_VALUE are not supported and will throw an IOException.

    Parameters:
      `reader` - `BinaryReader` to read the data from
      `size` - number of bytes the integer value is stored in, must be 1, 2 or 4.
    Returns:
      unsigned integer value.
    Throws:
      `IOException` - if error

  - ### readAddressAsLong

    public static long readAddressAsLong(BinaryReader reader, byte pointerSize) throws IOException
    Reads a variable-sized unsigned 'address' value from a `BinaryReader` and returns it as a 64 bit java long.

    The valid pointerSizes are 1, 2, 4, and 8.

    Parameters:
      `reader` - `BinaryReader` to read the data from
      `pointerSize` - number of bytes the value is stored in, must be 1, 2, 4, or 8.
    Returns:
      unsigned long value.
    Throws:
      `IOException` - if error

  - ### isThisParam

    public static boolean isThisParam(DIEAggregate paramDIEA)

  - ### isPointerTo

    public static boolean isPointerTo(DIEAggregate targetDIEA, DIEAggregate testDIEA)

  - ### isPointerDataType

    public static boolean isPointerDataType(DIEAggregate diea)

  - ### getReferringTypedef

    public static DIEAggregate getReferringTypedef(DIEAggregate diea)
    Returns the `DIEAggregate` of a typedef that points to the specified datatype.

    Returns null if there is no typedef pointing to the specified DIEA or if there are multiple.

    Parameters:
      `diea` - `DIEAggregate` of a data type that might be the target of typedefs.
    Returns:
      `DIEAggregate` of the singular typedef that points to the arg, otherwise null if none or multiple found.

  - ### readLength

    public static DWARFUtil.LengthResult readLength(BinaryReader reader, Program program) throws IOException, DWARFException
    Read a variable-length length value from the stream.

    Parameters:
      `reader` - `BinaryReader` stream to read from
      `program` - Ghidra `Program`
    Returns:
      new `DWARFUtil.LengthResult`, never null; length == 0 should be checked for and treated specially
    Throws:
      `IOException` - if io error
      `DWARFException` - if invalid values

  - ### getLanguageExternalFile

    public static ResourceFile getLanguageExternalFile(Language lang, String name) throws IOException
    Returns a file that has been referenced in the specified `language's` ldefs description via a

        <external_name tool="name" name="value"/>

    entry.
    Parameters:
      `lang` - `Language` to query
      `name` - name of the option in the ldefs file
    Returns:
      file pointed to by the specified external_name tool entry
    Throws:
      `IOException`

  - ### getLanguageDefinitionDirectory

    public static ResourceFile getLanguageDefinitionDirectory(Language lang) throws IOException
    Returns the base directory of a language definition.
    Parameters:
      `lang` - `Language` to get base definition directory
    Returns:
      base directory for language definition files
    Throws:
      `IOException`

  - ### getLanguageExternalNameValue

    public static String getLanguageExternalNameValue(Language lang, String name) throws IOException
    Returns a value specified in a `Language` definition via a

        <external_name tool="name" name="value"/>

    entry.

    Parameters:
      `lang` - `Language` to query
      `name` - name of the value
    Returns:
      String value
    Throws:
      `IOException`

  - ### packCompositeIfPossible

    public static void packCompositeIfPossible(Composite original, DataTypeManager dtm)

  - ### convertRegisterListToVarnodeStorage

    public static List<Varnode> convertRegisterListToVarnodeStorage(List<Register> registers, int dataTypeSize)

  - ### isEmptyArray

    public static boolean isEmptyArray(DataType dt)

  - ### isZeroByteDataType

    public static boolean isZeroByteDataType(DataType dt)

  - ### isVoid

    public static boolean isVoid(DataType dt)

  - ### isStackVarnode

    public static boolean isStackVarnode(Varnode varnode)