Package ghidra.program.model.listing

# Class LocalVariableImpl

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

All Implemented Interfaces:
  `LocalVariable`, `Variable`, `Comparable<Variable>`

public class LocalVariableImpl extends Object implements LocalVariable

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `LocalVariableImpl(String name, int firstUseOffset, DataType dataType, Address storageAddr, Program program)`
  Construct a variable with a single storage element at the specified address.
  `LocalVariableImpl(String name, int firstUseOffset, DataType dataType, Address storageAddr, Program program, SourceType sourceType)`
  Construct a variable with a single storage element at the specified address.
  `LocalVariableImpl(String name, int firstUseOffset, DataType dataType, Register register, Program program)`
  Construct a register variable with the specified register storage.
  `LocalVariableImpl(String name, int firstUseOffset, DataType dataType, Register register, Program program, SourceType sourceType)`
  Construct a variable with one or more associated storage elements.
  `LocalVariableImpl(String name, int firstUseOffset, DataType dataType, VariableStorage storage, boolean force, Program program)`
  Construct a variable with one or more associated storage elements.
  `LocalVariableImpl(String name, int firstUseOffset, DataType dataType, VariableStorage storage, boolean force, Program program, SourceType sourceType)`
  Construct a variable with one or more associated storage elements.
  `LocalVariableImpl(String name, int firstUseOffset, DataType dataType, VariableStorage storage, Program program)`
  Construct a variable with one or more associated storage elements.
  `LocalVariableImpl(String name, DataType dataType, int stackOffset, Program program)`
  Construct a stack variable at the specified stack offset with a first-use offset of 0.
  `LocalVariableImpl(String name, DataType dataType, int stackOffset, Program program, SourceType sourceType)`
  Construct a stack variable at the specified stack offset with a first-use offset of 0.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final int`
  `compareTo(Variable otherVar)`
  `final boolean`
  `equals(Object obj)`
  `final String`
  `getComment()`
  Get the Comment for this variable
  `DataType`
  `getDataType()`
  Get the Data Type of this variable
  `final Varnode`
  `getFirstStorageVarnode()`
  Get the first storage varnode for this variable
  `int`
  `getFirstUseOffset()`
  `Function`
  `getFunction()`
  Returns the function that contains this Variable.
  `final Varnode`
  `getLastStorageVarnode()`
  Get the last storage varnode for this variable
  `final int`
  `getLength()`
  Get the length of this variable
  `final Address`
  `getMinAddress()`
  `final String`
  `getName()`
  Get the Name of this variable or null if not assigned or not-applicable
  `final Program`
  `getProgram()`
  Returns the program that contains this variable or is the intended target
  `final Register`
  `getRegister()`
  `final List<Register>`
  `getRegisters()`
  `final SourceType`
  `getSource()`
  Get the source of this variable
  `final int`
  `getStackOffset()`
  `final Symbol`
  `getSymbol()`
  `final VariableStorage`
  `getVariableStorage()`
  Get the variable storage associated with this variable.
  `final boolean`
  `hasAssignedStorage()`
  `protected boolean`
  `hasDefaultName()`
  Determine if current name is a default name.
  `int`
  `hashCode()`
  `final boolean`
  `hasStackStorage()`
  `final boolean`
  `isCompoundVariable()`
  `final boolean`
  `isEquivalent(Variable otherVar)`
  Determine is another variable is equivalent to this variable.
  `final boolean`
  `isMemoryVariable()`
  `final boolean`
  `isRegisterVariable()`
  `final boolean`
  `isStackVariable()`
  `final boolean`
  `isUniqueVariable()`
  `final boolean`
  `isValid()`
  Verify that the variable is valid (i.e., storage is valid and size matches variable data type size)
  `protected boolean`
  `isVoidAllowed()`
  `void`
  `setComment(String comment)`
  Set the comment for this variable
  `final void`
  `setDataType(DataType type, boolean align, boolean force, SourceType source)`
  Set the Data Type of this variable.
  `void`
  `setDataType(DataType type, VariableStorage storage, boolean force, SourceType source)`
  Set the Data Type of this variable and the associated storage whose size matches the data type length.
  `void`
  `setDataType(DataType type, SourceType source)`
  Set the Data Type of this variable using the default alignment behavior (implementation specific).
  `boolean`
  `setFirstUseOffset(int firstUseOffset)`
  Set the first use offset.
  `void`
  `setName(String name, SourceType source)`
  Set the name of this variable.
  `String`
  `toString()`

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

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface java.lang.Comparable

  `compareTo`

  ### Methods inherited from interface ghidra.program.model.listing.Variable

  `getComment, getDataType, getFirstStorageVarnode, getFunction, getLastStorageVarnode, getLength, getMinAddress, getName, getProgram, getRegister, getRegisters, getSource, getStackOffset, getSymbol, getVariableStorage, hasAssignedStorage, hasStackStorage, isCompoundVariable, isEquivalent, isMemoryVariable, isRegisterVariable, isStackVariable, isUniqueVariable, isValid, setComment, setDataType, setDataType, setDataType, setName`

- ## Constructor Details

  - ### LocalVariableImpl

    public LocalVariableImpl(String name, DataType dataType, int stackOffset, Program program) throws InvalidInputException
    Construct a stack variable at the specified stack offset with a first-use offset of 0.
    Parameters:
      `name` - variable name or null for default naming
      `dataType` - a fixed-length datatype. (NOTE: Should be cloned to program datatype manager prior to determining storage elements since their length may change)
      `stackOffset` - signed stack offset
      `program` - target program
    Throws:
      `InvalidInputException` - if dataType restrictions are violated, an invalid storage address is specified, or unable to resolve storage element for specified datatype
      `AddressOutOfBoundsException` - if invalid stack offset specified

  - ### LocalVariableImpl

    public LocalVariableImpl(String name, DataType dataType, int stackOffset, Program program, SourceType sourceType) throws InvalidInputException
    Construct a stack variable at the specified stack offset with a first-use offset of 0.
    Parameters:
      `name` - variable name
      `dataType` - a fixed-length datatype. (NOTE: Should be cloned to program datatype manager prior to determining storage elements since their length may change)
      `stackOffset` -
      `program` - target program
      `sourceType` - name source type
    Throws:
      `InvalidInputException` - if dataType restrictions are violated, an invalid storage address is specified, or unable to resolve storage element for specified datatype
      `AddressOutOfBoundsException` - if invalid stack offset specified

  - ### LocalVariableImpl

    public LocalVariableImpl(String name, int firstUseOffset, DataType dataType, Register register, Program program) throws InvalidInputException
    Construct a register variable with the specified register storage.
    Parameters:
      `name` - variable name or null for default naming
      `firstUseOffset` - first use function-relative offset (i.e., start of scope).
      `dataType` - a fixed-length datatype. (NOTE: Should be cloned to program datatype manager prior to determining storage elements since their length may change)
      `register` - the register used for the storage.
      `program` - target program
    Throws:
      `InvalidInputException` - if dataType restrictions are violated, an invalid storage element is specified, or error while resolving storage element for specified datatype

  - ### LocalVariableImpl

    public LocalVariableImpl(String name, int firstUseOffset, DataType dataType, Register register, Program program, SourceType sourceType) throws InvalidInputException
    Construct a variable with one or more associated storage elements. Storage elements may get slightly modified to adjust for the resolved datatype size.
    Parameters:
      `name` - variable name
      `firstUseOffset` - first use function-relative offset (i.e., start of scope).
      `dataType` - a fixed-length datatype. (NOTE: Should be cloned to program datatype manager prior to determining storage elements since their length may change)
      `register` - the register used for the storage.
      `program` - target program
      `sourceType` - name source type
    Throws:
      `InvalidInputException` - if dataType restrictions are violated, an invalid storage element is specified, or error while resolving storage element for specified datatype

  - ### LocalVariableImpl

    public LocalVariableImpl(String name, int firstUseOffset, DataType dataType, Address storageAddr, Program program) throws InvalidInputException
    Construct a variable with a single storage element at the specified address. If address is contained within a register it may get realigned to the register based upon the resolved datatype length. Variable storage will be aligned to the least-significant portion of the register.
    Parameters:
      `name` - variable name or null for default naming
      `firstUseOffset` - first use function-relative offset (i.e., start of scope).
      `dataType` - a fixed-length datatype. (NOTE: Should be cloned to program datatype manager prior to determining storage elements since their length may change)
      `storageAddr` - storage address or null if no storage has been identified
      `program` - target program
    Throws:
      `InvalidInputException` - if dataType restrictions are violated, an invalid storage address is specified, or unable to resolve storage element for specified datatype

  - ### LocalVariableImpl

    public LocalVariableImpl(String name, int firstUseOffset, DataType dataType, Address storageAddr, Program program, SourceType sourceType) throws InvalidInputException
    Construct a variable with a single storage element at the specified address. If address is contained within a register it may get realigned to the register based upon the resolved datatype length. Variable storage will be aligned to the least-significant portion of the register.
    Parameters:
      `name` - variable name
      `firstUseOffset` - first use function-relative offset (i.e., start of scope).
      `dataType` - a fixed-length datatype. (NOTE: Should be cloned to program datatype manager prior to determining storage elements since their length may change)
      `storageAddr` - storage address or null if no storage has been identified
      `program` - target program
      `sourceType` - name source type
    Throws:
      `InvalidInputException` - if dataType restrictions are violated, an invalid storage address is specified, or unable to resolve storage element for specified datatype

  - ### LocalVariableImpl

    public LocalVariableImpl(String name, int firstUseOffset, DataType dataType, VariableStorage storage, Program program) throws InvalidInputException
    Construct a variable with one or more associated storage elements. Storage elements may get slightly modified to adjust for the resolved datatype size.
    Parameters:
      `name` - variable name or null for default naming
      `firstUseOffset` - first use function-relative offset (i.e., start of scope).
      `dataType` - a fixed-length datatype. (NOTE: Should be cloned to program datatype manager prior to determining storage elements since their length may change)
      `storage` - variable storage (may not be null)
      `program` - target program
    Throws:
      `InvalidInputException` - if dataType restrictions are violated, an invalid storage element is specified, or error while resolving storage element for specified datatype

  - ### LocalVariableImpl

    public LocalVariableImpl(String name, int firstUseOffset, DataType dataType, VariableStorage storage, boolean force, Program program) throws InvalidInputException
    Construct a variable with one or more associated storage elements. Storage elements may get slightly modified to adjust for the resolved datatype size.
    Parameters:
      `name` - variable name or null for default naming
      `firstUseOffset` - first use function-relative offset (i.e., start of scope).
      `dataType` - a fixed-length datatype. (NOTE: Should be cloned to program datatype manager prior to determining storage elements since their length may change)
      `storage` - variable storage (may not be null)
      `force` - if true storage will be forced even if incorrect size
      `program` - target program
    Throws:
      `InvalidInputException` - if dataType restrictions are violated, an invalid storage element is specified, or error while resolving storage element for specified datatype

  - ### LocalVariableImpl

    public LocalVariableImpl(String name, int firstUseOffset, DataType dataType, VariableStorage storage, boolean force, Program program, SourceType sourceType) throws InvalidInputException
    Construct a variable with one or more associated storage elements. Storage elements may get slightly modified to adjust for the resolved datatype size.
    Parameters:
      `name` - variable name
      `firstUseOffset` - first use function-relative offset (i.e., start of scope).
      `dataType` - a fixed-length datatype. (NOTE: Should be cloned to program datatype manager prior to determining storage elements since their length may change)
      `storage` - variable storage (may not be null)
      `force` - if true storage will be forced even if incorrect size
      `program` - target program
      `sourceType` - name source type
    Throws:
      `InvalidInputException` - if dataType restrictions are violated, an invalid storage element is specified, or error while resolving storage element for specified datatype

- ## Method Details

  - ### getFirstUseOffset

    public int getFirstUseOffset()
    Specified by:
      `getFirstUseOffset` in interface `Variable`
    Returns:
      the first use offset relative to the function entry point.

  - ### setFirstUseOffset

    public boolean setFirstUseOffset(int firstUseOffset)
    Description copied from interface: `LocalVariable`
    Set the first use offset.
    Specified by:
      `setFirstUseOffset` in interface `LocalVariable`
    Returns:
      true if successful, else false

  - ### hasDefaultName

    protected boolean hasDefaultName()
    Determine if current name is a default name. This is more important for parameters so always returning false for locals is OK.
    Returns:
      true if name is reserved as a default name

  - ### isVoidAllowed

    protected boolean isVoidAllowed()
    Returns:
      true if a zero-sized void type is permitted

  - ### isValid

    public final boolean isValid()
    Description copied from interface: `Variable`
    Verify that the variable is valid (i.e., storage is valid and size matches variable data type size)
    Specified by:
      `isValid` in interface `Variable`
    Returns:
      true if variable is valid

  - ### getComment

    public final String getComment()
    Description copied from interface: `Variable`
    Get the Comment for this variable
    Specified by:
      `getComment` in interface `Variable`
    Returns:
      the comment

  - ### getDataType

    public DataType getDataType()
    Description copied from interface: `Variable`
    Get the Data Type of this variable
    Specified by:
      `getDataType` in interface `Variable`
    Returns:
      the data type of the variable

  - ### setDataType

    public void setDataType(DataType type, VariableStorage storage, boolean force, SourceType source) throws InvalidInputException
    Description copied from interface: `Variable`
    Set the Data Type of this variable and the associated storage whose size matches the data type length.

    NOTE: The storage and source are ignored if the function does not have custom storage enabled.

    Specified by:
      `setDataType` in interface `Variable`
    Parameters:
      `type` - the data type
      `storage` - properly sized storage for the new data type
      `force` - overwrite conflicting variables
      `source` - variable storage source (used only for function parameters and return)
    Throws:
      `InvalidInputException` - if data type is not a fixed length or violates storage constraints.
      `VariableSizeException` - if force is false and data type size causes a conflict with other variables

  - ### setDataType

    public final void setDataType(DataType type, boolean align, boolean force, SourceType source) throws InvalidInputException
    Description copied from interface: `Variable`
    Set the Data Type of this variable. The given dataType must have a fixed length.
    Specified by:
      `setDataType` in interface `Variable`
    Parameters:
      `type` - the data type
      `align` - maintain proper stack alignment/justification if supported by implementation. If false and this is a stack variable, the current stack address/offset will not change. If true, the affect is implementation dependent since alignment can not be performed without access to a compiler specification.
      `force` - overwrite conflicting variables
      `source` - signature source
    Throws:
      `InvalidInputException` - if data type is not a fixed length or violates storage constraints.
      `VariableSizeException` - if force is false and data type size causes a conflict with other variables

  - ### setDataType

    public void setDataType(DataType type, SourceType source) throws InvalidInputException
    Description copied from interface: `Variable`
    Set the Data Type of this variable using the default alignment behavior (implementation specific). The given dataType must have a fixed length. If contained within a stack-frame, data-type size will be constrained by existing variables (e.g., equivalent to force=false) Note: stack offset will be maintained for stack variables.
    Specified by:
      `setDataType` in interface `Variable`
    Parameters:
      `type` - the data type
      `source` - signature source
    Throws:
      `InvalidInputException` - if data type is not a fixed length or violates storage constraints.
      `VariableSizeException` - if data type size causes a conflict with other variables
    See Also:
      - `Variable.setDataType(DataType, boolean, boolean, SourceType)`

  - ### getFunction

    public Function getFunction()
    Description copied from interface: `Variable`
    Returns the function that contains this Variable. May be null if the variable is not in a function.
    Specified by:
      `getFunction` in interface `Variable`
    Returns:
      containing function or null

  - ### getProgram

    public final Program getProgram()
    Description copied from interface: `Variable`
    Returns the program that contains this variable or is the intended target
    Specified by:
      `getProgram` in interface `Variable`
    Returns:
      the program.

  - ### getLength

    public final int getLength()
    Description copied from interface: `Variable`
    Get the length of this variable
    Specified by:
      `getLength` in interface `Variable`
    Returns:
      the length of the variable

  - ### getName

    public final String getName()
    Description copied from interface: `Variable`
    Get the Name of this variable or null if not assigned or not-applicable
    Specified by:
      `getName` in interface `Variable`
    Returns:
      the name of the variable

  - ### getSource

    public final SourceType getSource()
    Description copied from interface: `Variable`
    Get the source of this variable
    Specified by:
      `getSource` in interface `Variable`
    Returns:
      the source of this variable

  - ### getSymbol

    public final Symbol getSymbol()
    Specified by:
      `getSymbol` in interface `Variable`
    Returns:
      the symbol associated with this variable or null if no symbol associated. Certain dynamic variables such as auto-parameters do not have a symbol and will return null.

  - ### setComment

    public void setComment(String comment)
    Description copied from interface: `Variable`
    Set the comment for this variable
    Specified by:
      `setComment` in interface `Variable`
    Parameters:
      `comment` - the comment

  - ### setName

    public void setName(String name, SourceType source) throws InvalidInputException
    Description copied from interface: `Variable`
    Set the name of this variable.
    Specified by:
      `setName` in interface `Variable`
    Parameters:
      `name` - the name
      `source` - the source of this variable name
    Throws:
      `InvalidInputException` - if name contains blank characters, is zero length, or is null

  - ### hasAssignedStorage

    public final boolean hasAssignedStorage()
    Specified by:
      `hasAssignedStorage` in interface `Variable`
    Returns:
      true if this variable has been assigned storage. This is equivalent to `Variable.getVariableStorage()` != null

  - ### getVariableStorage

    public final VariableStorage getVariableStorage()
    Description copied from interface: `Variable`
    Get the variable storage associated with this variable.
    Specified by:
      `getVariableStorage` in interface `Variable`
    Returns:
      the variable storage for this variable

  - ### getFirstStorageVarnode

    public final Varnode getFirstStorageVarnode()
    Description copied from interface: `Variable`
    Get the first storage varnode for this variable
    Specified by:
      `getFirstStorageVarnode` in interface `Variable`
    Returns:
      the first storage varnode associated with this variable
    See Also:
      - `Variable.getVariableStorage()`

  - ### getLastStorageVarnode

    public final Varnode getLastStorageVarnode()
    Description copied from interface: `Variable`
    Get the last storage varnode for this variable
    Specified by:
      `getLastStorageVarnode` in interface `Variable`
    Returns:
      the last storage varnode associated with this variable
    See Also:
      - `Variable.getVariableStorage()`

  - ### isStackVariable

    public final boolean isStackVariable()
    Specified by:
      `isStackVariable` in interface `Variable`
    Returns:
      true if this is a simple variable consisting of a single stack varnode which will be returned by either the `Variable.getFirstStorageVarnode()` or `Variable.getLastStorageVarnode()` methods. The stack offset can be obtained using:

                          getFirstStorageVarnode().getOffset()

  - ### hasStackStorage

    public final boolean hasStackStorage()
    Specified by:
      `hasStackStorage` in interface `Variable`
    Returns:
      true if this variable uses simple or compound storage which contains a stack element. If true, the last storage varnode will always be the stack element.
    See Also:
      - `Variable.getLastStorageVarnode()`

  - ### isRegisterVariable

    public final boolean isRegisterVariable()
    Specified by:
      `isRegisterVariable` in interface `Variable`
    Returns:
      true if this is a simple variable consisting of a single register varnode which will be returned by either the `Variable.getFirstStorageVarnode()` or `Variable.getLastStorageVarnode()` methods. The register can be obtained using the `Variable.getRegister()` method.

  - ### getRegister

    public final Register getRegister()
    Specified by:
      `getRegister` in interface `Variable`
    Returns:
      first storage register associated with this variable, else null is returned. A variable with compound storage may have more than one register or other storage in addition to the register returned by this method.
    See Also:
      - `Variable.isRegisterVariable()`

  - ### getRegisters

    public final List<Register> getRegisters()
    Specified by:
      `getRegisters` in interface `Variable`
    Returns:
      all storage register(s) associated with this variable, else null is returned if no registers are used. A variable with compound storage may have more than one register or other storage in addition to the register(s) returned by this method.
    See Also:
      - `Variable.isRegisterVariable()`
      - `Variable.isCompoundVariable()`

  - ### getMinAddress

    public final Address getMinAddress()
    Specified by:
      `getMinAddress` in interface `Variable`
    Returns:
      the minimum address corresponding to the first varnode of this storage or null if this is a special empty storage: `VariableStorage.BAD_STORAGE`, `VariableStorage.UNASSIGNED_STORAGE`, `VariableStorage.VOID_STORAGE`

  - ### getStackOffset

    public final int getStackOffset()
    Specified by:
      `getStackOffset` in interface `Variable`
    Returns:
      the stack offset associated with simple stack variable (i.e., `Variable.isStackVariable()` returns true).

  - ### isMemoryVariable

    public final boolean isMemoryVariable()
    Specified by:
      `isMemoryVariable` in interface `Variable`
    Returns:
      true if this is a simple variable consisting of a single storage memory element which will be returned by either the `Variable.getFirstStorageVarnode()` or `Variable.getVariableStorage()` methods.

  - ### isUniqueVariable

    public final boolean isUniqueVariable()
    Specified by:
      `isUniqueVariable` in interface `Variable`
    Returns:
      true if this is a simple variable consisting of a single storage unique/hash element which will be returned by either the `Variable.getFirstStorageVarnode()` or `Variable.getVariableStorage()` methods. The unique hash can be obtained from the storage address offset corresponding to the single storage element.

  - ### isCompoundVariable

    public final boolean isCompoundVariable()
    Specified by:
      `isCompoundVariable` in interface `Variable`
    Returns:
      true if this variable uses compound storage consisting of two or more storage elements which will be returned by the `Variable.getVariableStorage()` method. Compound variables will always use a register(s) optionally followed by other storage (i.e., stack).

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### equals

    public final boolean equals(Object obj)
    Overrides:
      `equals` in class `Object`

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### compareTo

    public final int compareTo(Variable otherVar)
    Specified by:
      `compareTo` in interface `Comparable<Variable>`

  - ### isEquivalent

    public final boolean isEquivalent(Variable otherVar)
    Description copied from interface: `Variable`
    Determine is another variable is equivalent to this variable.
    Specified by:
      `isEquivalent` in interface `Variable`
    Parameters:
      `otherVar` - other variable
    Returns:
      true if the specified variable is equivalent to this variable