Package ghidra.program.model.listing

Interface Variable

All Superinterfaces:

java.lang.Comparable<Variable>

All Known Subinterfaces:

LocalVariable, Parameter

All Known Implementing Classes:

AutoParameterImpl, LocalVariableDB, LocalVariableImpl, ParameterImpl, ReturnParameterDB, ReturnParameterImpl, VariableDB

public interface Variable
extends java.lang.Comparable<Variable>

Defines an object that stores a value of some specific data type. The variable has a name, type, size, and a comment.

Method Summary

Modifier and Type	Method	Description
java.lang.String	getComment()	Get the Comment for this variable
DataType	getDataType()	Get the Data Type of this variable
Varnode	getFirstStorageVarnode()	Get the first storage varnode for this variable
int	getFirstUseOffset()
Function	getFunction()	Returns the function that contains this Variable.
Varnode	getLastStorageVarnode()	Get the last storage varnode for this variable
int	getLength()	Get the length of this variable
Address	getMinAddress()
java.lang.String	getName()	Get the Name of this variable or null if not assigned or not-applicable
Program	getProgram()	Returns the program that contains this variable or is the intended target
Register	getRegister()
java.util.List<Register>	getRegisters()
SourceType	getSource()	Get the source of this variable
int	getStackOffset()
Symbol	getSymbol()
VariableStorage	getVariableStorage()	Get the variable storage associated with this variable.
boolean	hasAssignedStorage()
boolean	hasStackStorage()
boolean	isCompoundVariable()
boolean	isEquivalent(Variable variable)	Determine is another variable is equivalent to this variable.
boolean	isMemoryVariable()
boolean	isRegisterVariable()
boolean	isStackVariable()
boolean	isUniqueVariable()
boolean	isValid()	Verify that the variable is valid (i.e., storage is valid and size matches variable data type size)
void	setComment(java.lang.String comment)	Set the comment for this variable
void	setDataType(DataType type, boolean alignStack, 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).
void	setName(java.lang.String name, SourceType source)	Set the name of this variable.

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

getDataType

DataType getDataType()

Get the Data Type of this variable

Returns:

the data type of the variable

setDataType

void setDataType(DataType type,
                 VariableStorage storage,
                 boolean force,
                 SourceType source)
          throws InvalidInputException

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.

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

void setDataType(DataType type,
                 SourceType source)
          throws InvalidInputException

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.

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:

setDataType(DataType, boolean, boolean, SourceType)

setDataType

void setDataType(DataType type,
                 boolean alignStack,
                 boolean force,
                 SourceType source)
          throws InvalidInputException

Set the Data Type of this variable. The given dataType must have a fixed length.

Parameters:

type - the data type

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

getName

java.lang.String getName()

Get the Name of this variable or null if not assigned or not-applicable

Returns:

the name of the variable

getLength

int getLength()

Get the length of this variable

Returns:

the length of the variable

isValid

boolean isValid()

Verify that the variable is valid (i.e., storage is valid and size matches variable data type size)

Returns:

true if variable is valid

getFunction

Function getFunction()

Returns the function that contains this Variable. May be null if the variable is not in a function.

Returns:

containing function or null

getProgram

Program getProgram()

Returns the program that contains this variable or is the intended target

Returns:

the program.

getSource

SourceType getSource()

Get the source of this variable

Returns:

the source of this variable

setName

void setName(java.lang.String name,
             SourceType source)
      throws DuplicateNameException,
             InvalidInputException

Set the name of this variable.

Parameters:

name - the name

source - the source of this variable name

Throws:

DuplicateNameException - if the name collides with the name of another variable.

InvalidInputException - if name contains blank characters, is zero length, or is null

getComment

java.lang.String getComment()

Get the Comment for this variable

Returns:

the comment

setComment

void setComment(java.lang.String comment)

Set the comment for this variable

Parameters:

comment - the comment

getVariableStorage

VariableStorage getVariableStorage()

Get the variable storage associated with this variable.

Returns:

the variable storage for this variable

getFirstStorageVarnode

Varnode getFirstStorageVarnode()

Get the first storage varnode for this variable

Returns:

the first storage varnode associated with this variable

See Also:

getVariableStorage()

getLastStorageVarnode

Varnode getLastStorageVarnode()

Get the last storage varnode for this variable

Returns:

the last storage varnode associated with this variable

See Also:

getVariableStorage()

isStackVariable

boolean isStackVariable()

Returns:

true if this is a simple variable consisting of a single stack varnode which will be returned by either the getFirstStorageVarnode() or getLastStorageVarnode() methods. The stack offset can be obtained using:

                getFirstStorageVarnode().getOffset()
  

hasStackStorage

boolean hasStackStorage()

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:

getLastStorageVarnode()

isRegisterVariable

boolean isRegisterVariable()

Returns:

true if this is a simple variable consisting of a single register varnode which will be returned by either the getFirstStorageVarnode() or getLastStorageVarnode() methods. The register can be obtained using the getRegister() method.

getRegister

Register getRegister()

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:

isRegisterVariable()

getRegisters

java.util.List<Register> getRegisters()

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:

isRegisterVariable(), isCompoundVariable()

getMinAddress

Address getMinAddress()

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

int getStackOffset()

Returns:

the stack offset associated with simple stack variable (i.e., isStackVariable() returns true).

Throws:

java.lang.UnsupportedOperationException - if storage is not a simple stack variable

isMemoryVariable

boolean isMemoryVariable()

Returns:

true if this is a simple variable consisting of a single storage memory element which will be returned by either the getFirstStorageVarnode() or getVariableStorage() methods.

isUniqueVariable

boolean isUniqueVariable()

Returns:

true if this is a simple variable consisting of a single storage unique/hash element which will be returned by either the getFirstStorageVarnode() or getVariableStorage() methods. The unique hash can be obtained from the storage address offset corresponding to the single storage element.

isCompoundVariable

boolean isCompoundVariable()

Returns:

true if this variable uses compound storage consisting of two or more storage elements which will be returned by the getVariableStorage() method. Compound variables will always use a register(s) optionally followed by other storage (i.e., stack).

hasAssignedStorage

boolean hasAssignedStorage()

Returns:

true if this variable has been assigned storage. This is equivalent to getVariableStorage() != null

getFirstUseOffset

int getFirstUseOffset()

Returns:

the first use offset relative to the function entry point.

getSymbol

Symbol getSymbol()

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.

isEquivalent

boolean isEquivalent(Variable variable)

Determine is another variable is equivalent to this variable.

Parameters:

variable - other variable

Returns:

true if the specified variable is equivalent to this variable