Package ghidra.program.model.listing

Class VariableUtilities

java.lang.Object
ghidra.program.model.listing.VariableUtilities
public class VariableUtilities extends Object

  • 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)