Package ghidra.program.model.listing

# Class VariableUtilities

java.lang.Object
ghidra.program.model.listing.VariableUtilities

public class VariableUtilities extends Object

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `VariableUtilities.VariableConflictHandler`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static DataType`
  `checkDataType(DataType dataType, boolean voidOK, int defaultSize, DataTypeManager dtMgr)`
  Check the specified datatype for use as a return, parameter or variable type.
  `static DataType`
  `checkDataType(DataType dataType, boolean voidOK, int defaultSize, Program program)`
  Check the specified datatype for use as a return, parameter or variable type.
  `static DataType`
  `checkDataType(DataType dataType, boolean voidOK, DataTypeManager dtMgr)`
  Check the specified datatype for use as a return, parameter or variable type.
  `static VariableStorage`
  `checkStorage(Function function, VariableStorage storage, DataType dataType, boolean allowSizeMismatch)`
  Perform variable storage checks using the specified datatype.
  `static void`
  `checkStorage(VariableStorage storage, DataType dataType, boolean allowSizeMismatch)`
  Perform variable storage checks using the specified datatype.
  `static void`
  `checkVariableConflict(Function function, Variable var, VariableStorage newStorage, boolean deleteConflictingVariables)`
  Check for variable storage conflict and optionally remove conflicting variables.
  `static void`
  `checkVariableConflict(List<? extends Variable> existingVariables, Variable var, VariableStorage newStorage, VariableUtilities.VariableConflictHandler conflictHandler)`
  Check for variable storage conflict and optionally remove conflicting variables.
  `static int`
  `compare(Variable v1, Variable v2)`
  Compare two variables without using the instance specific compareTo method.
  `static boolean`
  `equivalentVariableArrays(Variable[] vars1, Variable[] vars2)`
  `static boolean`
  `equivalentVariables(Variable var1, Variable var2)`
  `static Structure`
  `findExistingClassStruct(Function func)`
  Find the structure data type which corresponds to the specified function's class namespace within the function's program.
  `static Structure`
  `findExistingClassStruct(GhidraClass classNamespace, DataTypeManager dataTypeManager)`
  Find the structure data type which corresponds to the specified class namespace within the specified data type manager.
  `static Structure`
  `findOrCreateClassStruct(Function function)`
  Find the structure data type which corresponds to the specified function's class namespace within the function's program.
  `static Structure`
  `findOrCreateClassStruct(GhidraClass classNamespace, DataTypeManager dataTypeManager)`
  Find the structure data type which corresponds to the specified class namespace within the specified data type manager.
  `static DataType`
  `getAutoDataType(Function function, DataType returnDataType, VariableStorage storage)`
  Determine the appropriate data type for an automatic parameter
  `static Integer`
  `getBaseStackParamOffset(Function function)`
  Determine the minimum stack offset for parameters
  `static int`
  `getPrecedence(Variable var)`
  Get a precedence value for the specified variable.
  `static ParameterImpl`
  `getThisParameter(Function function, PrototypeModel convention)`
  Deprecated.
  should rely on auto-param instead - try not to use this method which may be eliminated
  `static VariableStorage`
  `resizeStorage(VariableStorage curStorage, DataType dataType, boolean alignStack, Function function)`
  Perform resize variable storage to desired newSize.
  `static boolean`
  `storageMatches(List<? extends Variable> vars, Variable... otherVars)`
  Compare storage varnodes for two lists of variables.
  `static boolean`
  `storageMatches(List<Variable> vars, List<Variable> otherVars)`
  Compare storage varnodes for two lists of variables.

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

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

- ## Method Details

  - ### getPrecedence

    public static int getPrecedence(Variable var)
    Get a precedence value for the specified variable. This value can be used to assist with LocalVariable.compareTo(Variable var)
    Parameters:
      `var` - function variable
    Returns:
      numeric precedence

  - ### storageMatches

    public static boolean storageMatches(List<Variable> vars, List<Variable> otherVars)
    Compare storage varnodes for two lists of variables. No check is done to ensure that storage is considered good/valid (i.e., BAD_STORAGE, UNASSIGNED_STORAGE and VOID_STORAGE all have an empty varnode list and would be considered a match)
    Parameters:
      `vars` - function variables
      `otherVars` - other function variables
    Returns:
      true if the exact sequence of variable storage varnodes matches across two lists of variables.

  - ### storageMatches

    public static boolean storageMatches(List<? extends Variable> vars, Variable... otherVars)
    Compare storage varnodes for two lists of variables. No check is done to ensure that storage is considered good/valid (i.e., BAD_STORAGE, UNASSIGNED_STORAGE and VOID_STORAGE all have an empty varnode list and would be considered a match)
    Parameters:
      `vars` - function variables
      `otherVars` - other function variables
    Returns:
      true if the exact sequence of variable storage varnodes matches across two lists of variables.

  - ### compare

    public static int compare(Variable v1, Variable v2)
    Compare two variables without using the instance specific compareTo method.
    Parameters:
      `v1` - a function variable
      `v2` - another function variable
    Returns:
      a negative value if v1 < v2, 0 if equal, and positive if v1 > v2

  - ### getAutoDataType

    public static DataType getAutoDataType(Function function, DataType returnDataType, VariableStorage storage)
    Determine the appropriate data type for an automatic parameter
    Parameters:
      `function` - function whose auto param datatype is to be determined
      `returnDataType` - function's formal return datatype
      `storage` - variable storage for an auto-parameter (isAutoStorage should be true)
    Returns:
      auto-parameter data type

  - ### checkStorage

    public static void checkStorage(VariableStorage storage, DataType dataType, boolean allowSizeMismatch) throws InvalidInputException
    Perform variable storage checks using the specified datatype.
    Parameters:
      `storage` - variable storage whose size must match the specified data type size
      `dataType` - a datatype checked using `checkDataType(DataType, boolean, int, Program)`
      `allowSizeMismatch` - if true size mismatch will be ignore
    Throws:
      `InvalidInputException` - if specified storage is not suitable for datatype

  - ### checkStorage

    public static VariableStorage checkStorage(Function function, VariableStorage storage, DataType dataType, boolean allowSizeMismatch) throws InvalidInputException
    Perform variable storage checks using the specified datatype.
    Parameters:
      `function` - if specified and variable storage size does not match the data-type size an attempt will be made to resize the specified storage.
      `storage` - variable storage
      `dataType` - a datatype checked using `checkDataType(DataType, boolean, int, Program)`
      `allowSizeMismatch` - if true size mismatch will be ignore
    Returns:
      original storage or resized storage with the correct size.
    Throws:
      `InvalidInputException` - if specified storage is not suitable for datatype

  - ### checkDataType

    public static DataType checkDataType(DataType dataType, boolean voidOK, int defaultSize, DataTypeManager dtMgr) throws InvalidInputException
    Check the specified datatype for use as a return, parameter or variable type. It may not be suitable for other uses. The following datatypes will be mutated into a default pointer datatype:
    - Function definition datatype
    - An unsized/zero-element array
    Parameters:
      `dataType` - datatype to be checked
      `voidOK` - true if checking return datatype and void is allow, else false.
      `defaultSize` - Undefined datatype size to be used if specified datatype is null. A value less than 1 will result in the DEFAULT data type being returned (i.e., "undefined").
      `dtMgr` - target datatype manager (null permitted which will adopt default data organization)
    Returns:
      cloned/mutated datatype suitable for function parameters and variables (including function return data type).
    Throws:
      `InvalidInputException` - if an unacceptable datatype was specified

  - ### checkDataType

    public static DataType checkDataType(DataType dataType, boolean voidOK, int defaultSize, Program program) throws InvalidInputException
    Check the specified datatype for use as a return, parameter or variable type. It may not be suitable for other uses. The following datatypes will be mutated into a default pointer datatype:
    - Function definition datatype
    - An unsized/zero-element array
    Parameters:
      `dataType` - datatype to be checked
      `voidOK` - true if checking return datatype and void is allow, else false.
      `defaultSize` - Undefined datatype size to be used if specified datatype is null. A value less than 1 will result in the DEFAULT data type being returned (i.e., "undefined").
      `program` - target program
    Returns:
      cloned/mutated datatype suitable for function parameters and variables (including function return data type).
    Throws:
      `InvalidInputException` - if an unacceptable datatype was specified

  - ### checkDataType

    public static DataType checkDataType(DataType dataType, boolean voidOK, DataTypeManager dtMgr) throws InvalidInputException
    Check the specified datatype for use as a return, parameter or variable type. It may not be suitable for other uses. The following datatypes will be mutated into a default pointer datatype:
    - Function definition datatype
    - An unsized/zero-element array
    Parameters:
      `dataType` - datatype to be checked. If null is specified the DEFAULT datatype will be returned.
      `voidOK` - true if checking return datatype and void is allow, else false.
      `dtMgr` - target datatype manager (null permitted which will adopt default data organization)
    Returns:
      cloned/mutated datatype suitable for function parameters and variables (including function return data type).
    Throws:
      `InvalidInputException` - if an unacceptable datatype was specified

  - ### resizeStorage

    public static VariableStorage resizeStorage(VariableStorage curStorage, DataType dataType, boolean alignStack, Function function) throws InvalidInputException
    Perform resize variable storage to desired newSize. This method has limited ability to grow storage if current storage does not have a stack component or if other space constraints are exceeded.
    Parameters:
      `curStorage` - current variable storage
      `dataType` - variable datatype
      `alignStack` - if false no attempt is made to align stack usage for big-endian
      `function` - function which corresponds to resized variable storage
    Returns:
      resize storage
    Throws:
      `InvalidInputException` - if unable to resize storage to specified size.

  - ### checkVariableConflict

    public static void checkVariableConflict(Function function, Variable var, VariableStorage newStorage, boolean deleteConflictingVariables) throws VariableSizeException
    Check for variable storage conflict and optionally remove conflicting variables.
    Parameters:
      `function` - function which corresponds to specified variable
      `var` - existing function variable or null for new variable
      `newStorage` - new/updated variable storage
      `deleteConflictingVariables` - if true function's conflicting variables may be deleted
    Throws:
      `VariableSizeException` - if deleteConflictingVariables is false and another variable conflicts

  - ### checkVariableConflict

    public static void checkVariableConflict(List<? extends Variable> existingVariables, Variable var, VariableStorage newStorage, VariableUtilities.VariableConflictHandler conflictHandler) throws VariableSizeException
    Check for variable storage conflict and optionally remove conflicting variables.
    Parameters:
      `existingVariables` - variables to check (may contain null entries)
      `var` - function variable
      `conflictHandler` - variable conflict handler
      `newStorage` - variable storage
    Throws:
      `VariableSizeException` - if another variable conflicts

  - ### getBaseStackParamOffset

    public static Integer getBaseStackParamOffset(Function function)
    Determine the minimum stack offset for parameters
    Parameters:
      `function` - function whose stack use is to be examined
    Returns:
      stack parameter offset or null if it could not be determined

  - ### getThisParameter

    @Deprecated public static ParameterImpl getThisParameter(Function function, PrototypeModel convention)
    Deprecated.
    should rely on auto-param instead - try not to use this method which may be eliminated
    Generate a suitable 'this' parameter for the specified function
    Parameters:
      `function` - function for which a `this` parameter is to be generated
      `convention` - function calling convention
    Returns:
      this parameter or null of calling convention is not a 'thiscall' or some other error prevents it

  - ### findOrCreateClassStruct

    public static Structure findOrCreateClassStruct(GhidraClass classNamespace, DataTypeManager dataTypeManager)
    Find the structure data type which corresponds to the specified class namespace within the specified data type manager. The preferred structure will utilize a namespace-based category path, however, the match criteria can be fuzzy and relies primarily on the class name. A properly named class structure must reside within a category whose trailing path either matches the class namespace or the class-parent's namespace. Preference is given to it residing within the class-parent's namespace. If a match is not found an empty placeholder structure will be instantiated and returned. A newly instantiated structure will not be added to the data type manager and may refer to a non-existing category path which corresponds to the class-parent's namespace. If an unrelated data-type already exists matching the class name and category, null is returned.
    Parameters:
      `classNamespace` - class namespace
      `dataTypeManager` - data type manager which should be searched and whose data organization should be used.
    Returns:
      new or existing structure whose name matches the specified class namespace

  - ### findOrCreateClassStruct

    public static Structure findOrCreateClassStruct(Function function)
    Find the structure data type which corresponds to the specified function's class namespace within the function's program. The preferred structure will utilize a namespace-based category path, however, the match criteria can be fuzzy and relies primarily on the class name. A properly named class structure must reside within a category whose trailing path either matches the class namespace or the class-parent's namespace. Preference is given to it residing within the class-parent's namespace. If a match is not found an empty placeholder structure will be instantiated and returned. A newly instantiated structure will not be added to the data type manager and may refer to a non-existing category path which corresponds to the class-parent's namespace. If the function is not part of a class, or if an unrelated data-type already exists with the class's name and category, null is returned.
    Parameters:
      `function` - function's whose class namespace is the basis for the structure
    Returns:
      new or existing structure whose name matches the function's class namespace or null if function not contained within a class namespace.

  - ### findExistingClassStruct

    public static Structure findExistingClassStruct(GhidraClass classNamespace, DataTypeManager dataTypeManager)
    Find the structure data type which corresponds to the specified class namespace within the specified data type manager. The preferred structure will utilize a namespace-based category path, however, the match criteria can be fuzzy and relies primarily on the class name. A properly named class structure must reside within a category whose trailing path either matches the class namespace or the class-parent's namespace. Preference is given to it residing within the class-parent's namespace.
    Parameters:
      `classNamespace` - class namespace
      `dataTypeManager` - data type manager which should be searched.
    Returns:
      existing structure whose name matches the specified class namespace or null if not found.

  - ### findExistingClassStruct

    public static Structure findExistingClassStruct(Function func)
    Find the structure data type which corresponds to the specified function's class namespace within the function's program. The preferred structure will utilize a namespace-based category path, however, the match criteria can be fuzzy and relies primarily on the class name. A properly named class structure must reside within a category whose trailing path either matches the class namespace or the class-parent's namespace. Preference is given to it residing within the class-parent's namespace.
    Parameters:
      `func` - the function.
    Returns:
      existing structure whose name matches the specified function's class namespace or null if not found.

  - ### equivalentVariableArrays

    public static boolean equivalentVariableArrays(Variable[] vars1, Variable[] vars2)

  - ### equivalentVariables

    public static boolean equivalentVariables(Variable var1, Variable var2)