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)

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `HighFunctionDBUtil.ReturnCommitOption`

- ## 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(HighFunction highFunction, boolean useDataTypes, HighFunctionDBUtil.ReturnCommitOption returnCommit, SourceType source)`
  Commit all parameters, including optional return, associated with HighFunction to the underlying database.
  `static int`
  `getFirstVarArg(Program program, Address addr)`
  If there is a call to a function at the given address, and the function takes variable arguments, return the index of the first variable argument.
  `static Variable`
  `getFunctionVariable(HighSymbol highSymbol)`
  `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

  - ### commitParamsToDatabase

    public static void commitParamsToDatabase(HighFunction highFunction, boolean useDataTypes, HighFunctionDBUtil.ReturnCommitOption returnCommit, SourceType source) throws DuplicateNameException, InvalidInputException
    Commit all parameters, including optional return, 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
      `returnCommit` - controls optional commit of return parameter
      `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

  - ### 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

  - ### getFunctionVariable

    public static Variable getFunctionVariable(HighSymbol highSymbol)

  - ### 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

  - ### getFirstVarArg

    public static int getFirstVarArg(Program program, Address addr)
    If there is a call to a function at the given address, and the function takes variable arguments, return the index of the first variable argument. Return -1 otherwise.
    Parameters:
      `program` - is the Program
      `addr` - is the given address of the call
    Returns:
      the index of the first variable argument or -1

  - ### 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