Package ghidra.program.model.pcode

# Class HighFunctionDBUtil

java.lang.Object
ghidra.program.model.pcode.HighFunctionDBUtil

public class HighFunctionDBUtil extends Object
`HighFunctionDBUtil` provides various methods for updating the state of a function contained within a program database. It is important to note that the decompiler result state (e.g., HighFunction, HighParam, HighLocal, etc.) is not altered by any of these methods. A new decompiler result will need to be generated to reflect any changes made to the database. Care must be taken when making incremental changes to multiple elements (e.g., Variables)

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `AUTO_CAT`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `HighFunctionDBUtil()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `commitLocalNamesToDatabase(HighFunction highFunction, SourceType source)`
  Commit local variables from the decompiler's model of the function to the database.
  `static void`
  `commitParamsToDatabase(Function function, String modelName, List<Parameter> params, boolean hasVarArgs, boolean renameConflicts, SourceType source)`
  Commit a specified set of parameters for the given function to the database.
  `static void`
  `commitParamsToDatabase(HighFunction highFunction, boolean useDataTypes, SourceType source)`
  Commit all parameters associated with HighFunction to the underlying database.
  `static void`
  `commitReturnToDatabase(HighFunction highFunction, SourceType source)`
  Commit the decompiler's version of the function return data-type to the database.
  `static Address`
  `getSpacebaseReferenceAddress(AddressFactory addrFactory, PcodeOp op)`
  Get the Address referred to by a spacebase reference.
  `static DataTypeSymbol`
  `readOverride(Symbol sym)`
  Read a call prototype override which corresponds to the specified override code symbol
  `static void`
  `updateDBVariable(HighSymbol highSymbol, String name, DataType dataType, SourceType source)`
  Rename and/or retype the specified variable in the database.
  `static void`
  `writeOverride(Function function, Address callsite, FunctionSignature sig)`
  Commit an overriding prototype for a particular call site to the database.
  `static void`
  `writeUnionFacet(Function function, DataType dt, int fieldNum, Address addr, long hash, SourceType source)`
  Write a union facet to the database (UnionFacetSymbol).

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

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

- ## Field Details

  - ### AUTO_CAT

    public static final String AUTO_CAT
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### HighFunctionDBUtil

    public HighFunctionDBUtil()

- ## Method Details

  - ### commitReturnToDatabase

    public static void commitReturnToDatabase(HighFunction highFunction, SourceType source)
    Commit the decompiler's version of the function return data-type to the database. The decompiler's version of the prototype model is committed as well
    Parameters:
      `highFunction` - is the decompiler's model of the function
      `source` - is the desired SourceType for the commit

  - ### commitParamsToDatabase

    public static void commitParamsToDatabase(HighFunction highFunction, boolean useDataTypes, SourceType source) throws DuplicateNameException, InvalidInputException
    Commit all parameters associated with HighFunction to the underlying database.
    Parameters:
      `highFunction` - is the associated HighFunction
      `useDataTypes` - is true if the HighFunction's parameter data-types should be committed
      `source` - is the signature source type to set
    Throws:
      `DuplicateNameException` - if commit of parameters caused conflict with other local variable/label.
      `InvalidInputException` - if specified storage is invalid

  - ### commitParamsToDatabase

    public static void commitParamsToDatabase(Function function, String modelName, List<Parameter> params, boolean hasVarArgs, boolean renameConflicts, SourceType source) throws DuplicateNameException, InvalidInputException
    Commit a specified set of parameters for the given function to the database. The name, data-type, and storage is committed for each parameter. The parameters are provided along with a formal PrototypeModel. If the parameters fit the model, they are committed using "dynamic" storage. Otherwise, they are committed using "custom" storage.
    Parameters:
      `function` - is the Function being modified
      `modelName` - is the name of the underlying PrototypeModel
      `params` - is the formal list of parameter objects
      `hasVarArgs` - is true if the prototype can take variable arguments
      `renameConflicts` - if true any name conflicts will be resolved by renaming the conflicting local variable/label
      `source` - source type
    Throws:
      `DuplicateNameException` - if commit of parameters caused conflict with other local variable/label. Should not occur if renameConflicts is true.
      `InvalidInputException` - for invalid variable names or for parameter data-types that aren't fixed length
      `DuplicateNameException` - is there are collisions between variable names in the function's scope

  - ### commitLocalNamesToDatabase

    public static void commitLocalNamesToDatabase(HighFunction highFunction, SourceType source)
    Commit local variables from the decompiler's model of the function to the database. This does NOT include formal function parameters.
    Parameters:
      `highFunction` - is the decompiler's model of the function
      `source` - is the desired SourceType for the commit

  - ### updateDBVariable

    public static void updateDBVariable(HighSymbol highSymbol, String name, DataType dataType, SourceType source) throws InvalidInputException, DuplicateNameException
    Rename and/or retype the specified variable in the database. All parameters may be flushed to the database if typed parameter inconsistency detected.
    Parameters:
      `highSymbol` - is the symbol being updated
      `name` - new variable name or null to use retain current variable name
      `dataType` - newly assigned data type or null to retain current variable datatype. Only a fixed-length data type may be specified. If size varies from the current size, an attempt will be made to grow/shrink the storage.
      `source` - source type
    Throws:
      `InvalidInputException` - if suitable data type was not specified, or unable to resize storage, or invalid name specified
      `DuplicateNameException` - if name was specified and conflicts with another variable/label within the function's namespace
      `UnsupportedOperationException` - if unsupported variable type is specified

  - ### writeOverride

    public static void writeOverride(Function function, Address callsite, FunctionSignature sig) throws InvalidInputException
    Commit an overriding prototype for a particular call site to the database. The override only applies to the function(s) containing the actual call site. Calls to the same function from other sites are unaffected. This is used typically either for indirect calls are for calls to a function with a variable number of parameters.
    Parameters:
      `function` - is the Function whose call site is being overridden
      `callsite` - is the address of the calling instruction (the call site)
      `sig` - is the overriding function signature
    Throws:
      `InvalidInputException` - if there are problems committing the override symbol

  - ### readOverride

    public static DataTypeSymbol readOverride(Symbol sym)
    Read a call prototype override which corresponds to the specified override code symbol
    Parameters:
      `sym` - special call override code symbol whose address corresponds to a call site
    Returns:
      call prototype override DataTypeSymbol or null if associated function signature data-type could not be found

  - ### getSpacebaseReferenceAddress

    public static Address getSpacebaseReferenceAddress(AddressFactory addrFactory, PcodeOp op)
    Get the Address referred to by a spacebase reference. Address-of references are encoded in the p-code syntax tree as: `vn = PTRSUB(<spacebase>, #const)`. This decodes the reference and returns the Address
    Parameters:
      `addrFactory` - is the factory used to construct the Address
      `op` - is the PTRSUB op encoding the reference
    Returns:
      the recovered Address (or null if not correct form)

  - ### writeUnionFacet

    public static void writeUnionFacet(Function function, DataType dt, int fieldNum, Address addr, long hash, SourceType source) throws InvalidInputException, DuplicateNameException
    Write a union facet to the database (UnionFacetSymbol). Parameters provide the pieces for building the dynamic LocalVariable. This method clears out any preexisting union facet with the same dynamic hash and firstUseOffset.
    Parameters:
      `function` - is the function affected by the union facet
      `dt` - is the parent data-type; a union, a pointer to a union, or a partial union
      `fieldNum` - is the ordinal of the desired union field
      `addr` - is the first use address of the facet
      `hash` - is the dynamic hash
      `source` - is the SourceType for the LocalVariable
    Throws:
      `InvalidInputException` - if the LocalVariable cannot be created
      `DuplicateNameException` - if the (auto-generated) name is used elsewhere