Package ghidra.program.model.data

# Class FunctionDefinitionDataType

java.lang.Object
ghidra.program.model.data.AbstractDataType
ghidra.program.model.data.DataTypeImpl
ghidra.program.model.data.GenericDataType
ghidra.program.model.data.FunctionDefinitionDataType

All Implemented Interfaces:
  `DataType`, `FunctionDefinition`, `FunctionSignature`

Direct Known Subclasses:
  `FunctionSignatureImpl`

public class FunctionDefinitionDataType extends GenericDataType implements FunctionDefinition
Definition of a function for things like function pointers.

- ## Field Summary

  ### Fields inherited from class ghidra.program.model.data.DataTypeImpl

  `defaultSettings`

  ### Fields inherited from class ghidra.program.model.data.AbstractDataType

  `categoryPath, dataMgr, EMPTY_TYPEDEF_DEFINITIONS, name`

  ### Fields inherited from interface ghidra.program.model.data.DataType

  `CONFLICT_SUFFIX, DEFAULT, NO_LAST_CHANGE_TIME, NO_SOURCE_SYNC_TIME, TYPEDEF_ATTRIBUTE_PREFIX, TYPEDEF_ATTRIBUTE_SUFFIX, VOID`

  ### Fields inherited from interface ghidra.program.model.listing.FunctionSignature

  `NORETURN_DISPLAY_STRING, VAR_ARGS_DISPLAY_STRING, VOID_PARAM_DISPLAY_STRING`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FunctionDefinitionDataType(CategoryPath path, String name)`
  `FunctionDefinitionDataType(CategoryPath path, String name, DataTypeManager dtm)`
  `FunctionDefinitionDataType(CategoryPath path, String name, FunctionSignature sig)`
  `FunctionDefinitionDataType(CategoryPath path, String name, FunctionSignature sig, DataTypeManager dtm)`
  `FunctionDefinitionDataType(CategoryPath path, String name, FunctionSignature sig, UniversalID universalID, SourceArchive sourceArchive, long lastChangeTime, long lastChangeTimeInSourceArchive, DataTypeManager dtm)`
  `FunctionDefinitionDataType(Function function, boolean formalSignature)`
  Create a Function Definition based on a Function
  `FunctionDefinitionDataType(FunctionSignature sig)`
  `FunctionDefinitionDataType(FunctionSignature sig, DataTypeManager dtm)`
  `FunctionDefinitionDataType(String name)`
  `FunctionDefinitionDataType(String name, DataTypeManager dtm)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DataType`
  `clone(DataTypeManager dtm)`
  Returns an instance of this DataType using the specified `DataTypeManager` to allow its use of the corresponding `DataOrganization` while retaining its unique identity (see `DataType.getUniversalID()` and archive association (see `DataType.getSourceArchive()`) if applicable.
  `DataType`
  `copy(DataTypeManager dtm)`
  Returns a new instance (shallow copy) of this DataType with a new identity and no source archive association.
  `void`
  `dataTypeDeleted(DataType dt)`
  Informs this datatype that the given datatype has been deleted.
  `void`
  `dataTypeNameChanged(DataType dt, String oldName)`
  Informs this datatype that its name has changed from the indicated old name.
  `void`
  `dataTypeReplaced(DataType oldDt, DataType newDt)`
  Informs this datatype that the given oldDT has been replaced with newDT
  `void`
  `dataTypeSizeChanged(DataType dt)`
  Notification that the given datatype's size has changed.
  `boolean`
  `dependsOn(DataType dt)`
  Check if this datatype depends on the existence of the given datatype.
  `ParameterDefinition[]`
  `getArguments()`
  Get function signature parameter arguments
  `PrototypeModel`
  `getCallingConvention()`
  Gets the calling convention prototype model for this function if associated with a compiler specificfation.
  `String`
  `getCallingConventionName()`
  Returns the calling convention name associated with this function definition.
  `String`
  `getComment()`
  Get descriptive comment for signature
  `String`
  `getDescription()`
  Get a String briefly describing this DataType.
  `int`
  `getLength()`
  Get the length of this DataType as a number of 8-bit bytes.
  `String`
  `getMnemonic(Settings settings)`
  Get the mnemonic for this DataType.
  `String`
  `getPrototypeString()`
  Get string representation of the function signature without the calling convention specified.
  `String`
  `getPrototypeString(boolean includeCallingConvention)`
  Get string representation of the function signature
  `String`
  `getRepresentation(MemBuffer buf, Settings settings, int length)`
  Get bytes from memory in a printable format for this type.
  `DataType`
  `getReturnType()`
  Get function signature return type
  `Object`
  `getValue(MemBuffer buf, Settings settings, int length)`
  Returns the interpreted data value as an instance of the `advertised value class`.
  `boolean`
  `hasNoReturn()`
  `boolean`
  `hasVarArgs()`
  `boolean`
  `isEquivalent(DataType dt)`
  Check if the given datatype is equivalent to this datatype.
  `boolean`
  `isEquivalentSignature(FunctionSignature signature)`
  Returns true if the given signature is equivalent to this signature.
  `void`
  `replaceArgument(int ordinal, String newName, DataType dt, String newComment, SourceType source)`
  Replace the given argument with another data type
  `void`
  `setArguments(ParameterDefinition... args)`
  Set the arguments to this function.
  `void`
  `setCallingConvention(String conventionName)`
  Set the calling convention associated with this function definition.
  `void`
  `setComment(String comment)`
  Set the function comment
  `void`
  `setGenericCallingConvention(GenericCallingConvention genericCallingConvention)`
  Set the generic calling convention associated with this function definition.
  `void`
  `setNoReturn(boolean hasNoReturn)`
  Set whether or not this function has a return.
  `void`
  `setReturnType(DataType type)`
  Set the return data type for this function
  `void`
  `setVarArgs(boolean hasVarArgs)`
  Set whether parameters can be passed as a VarArg (variable argument list).
  `String`
  `toString()`

  ### Methods inherited from class ghidra.program.model.data.GenericDataType

  `setCategoryPath, setName, setNameAndCategory`

  ### Methods inherited from class ghidra.program.model.data.DataTypeImpl

  `addParent, equals, getAlignedLength, getAlignment, getDefaultSettings, getLastChangeTime, getLastChangeTimeInSourceArchive, getParents, getSettingsDefinitions, getSourceArchive, getUniversalID, getValueClass, hashCode, notifyAlignmentChanged, notifyDeleted, notifyNameChanged, notifyParents, notifyReplaced, notifySizeChanged, removeParent, replaceWith, setDescription, setLastChangeTime, setLastChangeTimeInSourceArchive, setSourceArchive`

  ### Methods inherited from class ghidra.program.model.data.AbstractDataType

  `dataTypeAlignmentChanged, encodeRepresentation, encodeValue, getCategoryPath, getDataOrganization, getDataOrganization, getDataTypeManager, getDataTypePath, getDefaultAbbreviatedLabelPrefix, getDefaultLabelPrefix, getDefaultLabelPrefix, getDefaultOffcutLabelPrefix, getDisplayName, getName, getPathName, getTypeDefSettingsDefinitions, hasLanguageDependantLength, isDeleted, isEncodable, isNotYetDefined, isZeroLength`

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

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

  ### Methods inherited from interface ghidra.program.model.data.DataType

  `addParent, dataTypeAlignmentChanged, encodeRepresentation, encodeValue, getAlignedLength, getAlignment, getCategoryPath, getDataOrganization, getDataTypeManager, getDataTypePath, getDefaultAbbreviatedLabelPrefix, getDefaultLabelPrefix, getDefaultLabelPrefix, getDefaultOffcutLabelPrefix, getDefaultSettings, getDisplayName, getLastChangeTime, getLastChangeTimeInSourceArchive, getName, getParents, getPathName, getSettingsDefinitions, getSourceArchive, getTypeDefSettingsDefinitions, getUniversalID, getValueClass, hasLanguageDependantLength, isDeleted, isEncodable, isNotYetDefined, isZeroLength, removeParent, replaceWith, setCategoryPath, setDescription, setLastChangeTime, setLastChangeTimeInSourceArchive, setName, setNameAndCategory, setSourceArchive`

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

  `getName, hasUnknownCallingConventionName`

- ## Constructor Details

  - ### FunctionDefinitionDataType

    public FunctionDefinitionDataType(String name)

  - ### FunctionDefinitionDataType

    public FunctionDefinitionDataType(String name, DataTypeManager dtm)

  - ### FunctionDefinitionDataType

    public FunctionDefinitionDataType(CategoryPath path, String name)

  - ### FunctionDefinitionDataType

    public FunctionDefinitionDataType(CategoryPath path, String name, DataTypeManager dtm)

  - ### FunctionDefinitionDataType

    public FunctionDefinitionDataType(FunctionSignature sig)

  - ### FunctionDefinitionDataType

    public FunctionDefinitionDataType(FunctionSignature sig, DataTypeManager dtm)

  - ### FunctionDefinitionDataType

    public FunctionDefinitionDataType(CategoryPath path, String name, FunctionSignature sig)

  - ### FunctionDefinitionDataType

    public FunctionDefinitionDataType(CategoryPath path, String name, FunctionSignature sig, DataTypeManager dtm)

  - ### FunctionDefinitionDataType

    public FunctionDefinitionDataType(CategoryPath path, String name, FunctionSignature sig, UniversalID universalID, SourceArchive sourceArchive, long lastChangeTime, long lastChangeTimeInSourceArchive, DataTypeManager dtm)

  - ### FunctionDefinitionDataType

    public FunctionDefinitionDataType(Function function, boolean formalSignature)
    Create a Function Definition based on a Function
    Parameters:
      `function` - the function to use to create a Function Signature.
      `formalSignature` - if true only original formal types will be retained and auto-params discarded (e.g., this, __return_storage_ptr__, etc.). If false, the effective signature will be used where forced indirect and auto-params are reflected in the signature. This option has no affect if the specified function has custom storage enabled.

- ## Method Details

  - ### setArguments

    public void setArguments(ParameterDefinition... args)
    Description copied from interface: `FunctionDefinition`
    Set the arguments to this function.
    Specified by:
      `setArguments` in interface `FunctionDefinition`
    Parameters:
      `args` - array of parameter definitions to be used as arguments to this function

  - ### setReturnType

    public void setReturnType(DataType type)
    Description copied from interface: `FunctionDefinition`
    Set the return data type for this function
    Specified by:
      `setReturnType` in interface `FunctionDefinition`
    Parameters:
      `type` - the return datatype to be set.

  - ### setComment

    public void setComment(String comment)
    Description copied from interface: `FunctionDefinition`
    Set the function comment
    Specified by:
      `setComment` in interface `FunctionDefinition`
    Parameters:
      `comment` - the comment to set.

  - ### setVarArgs

    public void setVarArgs(boolean hasVarArgs)
    Description copied from interface: `FunctionDefinition`
    Set whether parameters can be passed as a VarArg (variable argument list).
    Specified by:
      `setVarArgs` in interface `FunctionDefinition`
    Parameters:
      `hasVarArgs` - true if this function has a variable argument list (ie printf(fmt, ...)).

  - ### setNoReturn

    public void setNoReturn(boolean hasNoReturn)
    Description copied from interface: `FunctionDefinition`
    Set whether or not this function has a return.
    Specified by:
      `setNoReturn` in interface `FunctionDefinition`
    Parameters:
      `hasNoReturn` - true if this function does not return.

  - ### setGenericCallingConvention

    public void setGenericCallingConvention(GenericCallingConvention genericCallingConvention)
    Description copied from interface: `FunctionDefinition`
    Set the generic calling convention associated with this function definition.
    The total number of unique calling convention names used within a given `Program` or `DataTypeManager` may be limited (e.g., 127). When this limit is exceeded an error will be logged and this setting ignored.
    Specified by:
      `setGenericCallingConvention` in interface `FunctionDefinition`
    Parameters:
      `genericCallingConvention` - generic calling convention

  - ### setCallingConvention

    public void setCallingConvention(String conventionName) throws InvalidInputException
    Description copied from interface: `FunctionDefinition`
    Set the calling convention associated with this function definition.
    The total number of unique calling convention names used within a given `Program` or `DataTypeManager` may be limited (e.g., 127). When this limit is exceeded an error will be logged and this setting ignored.
    Specified by:
      `setCallingConvention` in interface `FunctionDefinition`
    Parameters:
      `conventionName` - calling convention name or null. This name is restricted to those defined by `GenericCallingConvention`, the associated compiler specification. The prototype model declaration name form (e.g., "__stdcall") should be specified as it appears in a compiler specification (*.cspec). The special "unknown" and "default" names are also allowed.
    Throws:
      `InvalidInputException` - if specified conventionName is not defined by `GenericCallingConvention` or the associated compiler specification if datatype manager has an associated program architecture.

  - ### getCallingConvention

    public PrototypeModel getCallingConvention()
    Description copied from interface: `FunctionSignature`
    Gets the calling convention prototype model for this function if associated with a compiler specificfation. This method will always return null if signature is not associated with a specific program architecture.
    Specified by:
      `getCallingConvention` in interface `FunctionSignature`
    Returns:
      the prototype model of the function's current calling convention or null.

  - ### getCallingConventionName

    public String getCallingConventionName()
    Description copied from interface: `FunctionSignature`
    Returns the calling convention name associated with this function definition. Reserved names may also be returned: `Function.UNKNOWN_CALLING_CONVENTION_STRING`, `Function.DEFAULT_CALLING_CONVENTION_STRING`. The "unknown" convention must be returned instead of null.
    Specified by:
      `getCallingConventionName` in interface `FunctionSignature`
    Returns:
      calling convention name

  - ### copy

    public DataType copy(DataTypeManager dtm)
    Description copied from interface: `DataType`
    Returns a new instance (shallow copy) of this DataType with a new identity and no source archive association.

    Any reference to other datatypes will use `DataType.clone(DataTypeManager)`.

    Specified by:
      `copy` in interface `DataType`
    Parameters:
      `dtm` - the data-type manager instance whose data-organization should apply.
    Returns:
      new instanceof of this datatype

  - ### clone

    public DataType clone(DataTypeManager dtm)
    Description copied from interface: `DataType`
    Returns an instance of this DataType using the specified `DataTypeManager` to allow its use of the corresponding `DataOrganization` while retaining its unique identity (see `DataType.getUniversalID()` and archive association (see `DataType.getSourceArchive()`) if applicable.

    This instance will be returned if this datatype's DataTypeManager matches the specified dtm. The recursion depth of a clone will stop on any datatype whose `DataTypeManager` matches the specified dtm and simply use the existing datatype instance.

    NOTE: In general, this method should not be used to obtain an instance to be modified. In most cases changes may be made directly to this instance if supported or to a `DataType.copy(DataTypeManager)` of this type.

    Specified by:
      `clone` in interface `DataType`
    Parameters:
      `dtm` - the data-type manager instance whose data-organization should apply.
    Returns:
      cloned instance which may be the same as this instance

  - ### getMnemonic

    public String getMnemonic(Settings settings)
    Description copied from interface: `DataType`
    Get the mnemonic for this DataType.
    Specified by:
      `getMnemonic` in interface `DataType`
    Overrides:
      `getMnemonic` in class `AbstractDataType`
    Parameters:
      `settings` - settings which may influence the result or null
    Returns:
      the mnemonic for this DataType.

  - ### getLength

    public int getLength()
    Description copied from interface: `DataType`
    Get the length of this DataType as a number of 8-bit bytes.

    For primitive datatypes this reflects the smallest varnode which can be used to contain its value (i.e., raw data length).

    Example: For x86 32-bit gcc an 80-bit `long double` `raw data length` of 10-bytes will fit within a floating point register while its `aligned-length` of 12-bytes is used by the gcc compiler for data/array/component allocations to maintain alignment (i.e., `sizeof(long double)` ).

    NOTE: Other than the `VoidDataType`, no datatype should ever return 0, even if `DataType.isZeroLength()`, and only `Dynamic`/`FactoryDataType` datatypes should return -1. If `DataType.isZeroLength()` is true a length of 1 should be returned. Where a zero-length datatype can be handled (e.g., `Composite`) the `DataType.isZeroLength()` method should be used.

    Specified by:
      `getLength` in interface `DataType`
    Returns:
      the length of this DataType

  - ### getDescription

    public String getDescription()
    Description copied from interface: `DataType`
    Get a String briefly describing this DataType.
    Specified by:
      `getDescription` in interface `DataType`
    Returns:
      a one-liner describing this DataType.

  - ### getValue

    public Object getValue(MemBuffer buf, Settings settings, int length)
    Description copied from interface: `DataType`
    Returns the interpreted data value as an instance of the `advertised value class`.

    For instance, `Pointer` data types should return an Address object (or null), or integer data types should return a `Scalar` object.

    Specified by:
      `getValue` in interface `DataType`
    Parameters:
      `buf` - the data buffer
      `settings` - the settings to use.
      `length` - indicates the maximum number of bytes that may be consumed by a `Dynamic` datatype, otherwise this value is ignored. A value of -1 may be specified to allow a Dynamic datatype to determine the length based upon the actual data bytes
    Returns:
      the data object, or null if data is invalid

  - ### getRepresentation

    public String getRepresentation(MemBuffer buf, Settings settings, int length)
    Description copied from interface: `DataType`
    Get bytes from memory in a printable format for this type.
    Specified by:
      `getRepresentation` in interface `DataType`
    Parameters:
      `buf` - the data.
      `settings` - the settings to use for the representation.
      `length` - the number of bytes to represent.
    Returns:
      the representation of the data in this format, never null.

  - ### getPrototypeString

    public String getPrototypeString()
    Description copied from interface: `FunctionSignature`
    Get string representation of the function signature without the calling convention specified.
    Specified by:
      `getPrototypeString` in interface `FunctionSignature`
    Returns:
      function signature string

  - ### getPrototypeString

    public String getPrototypeString(boolean includeCallingConvention)
    Description copied from interface: `FunctionSignature`
    Get string representation of the function signature
    Specified by:
      `getPrototypeString` in interface `FunctionSignature`
    Parameters:
      `includeCallingConvention` - if true prototype will include call convention declaration if known as well as `noreturn` indicator if applicable.
    Returns:
      function signature string

  - ### getArguments

    public ParameterDefinition[] getArguments()
    Description copied from interface: `FunctionSignature`
    Get function signature parameter arguments
    Specified by:
      `getArguments` in interface `FunctionSignature`
    Returns:
      an array of parameters for the function

  - ### getReturnType

    public DataType getReturnType()
    Description copied from interface: `FunctionSignature`
    Get function signature return type
    Specified by:
      `getReturnType` in interface `FunctionSignature`
    Returns:
      the return data type

  - ### getComment

    public String getComment()
    Description copied from interface: `FunctionSignature`
    Get descriptive comment for signature
    Specified by:
      `getComment` in interface `FunctionSignature`
    Returns:
      the comment string

  - ### hasVarArgs

    public boolean hasVarArgs()
    Specified by:
      `hasVarArgs` in interface `FunctionSignature`
    Returns:
      true if this function signature has a variable argument list (VarArgs).

  - ### hasNoReturn

    public boolean hasNoReturn()
    Specified by:
      `hasNoReturn` in interface `FunctionSignature`
    Returns:
      true if this function signature corresponds to a non-returning function.

  - ### isEquivalent

    public boolean isEquivalent(DataType dt)
    Description copied from interface: `DataType`
    Check if the given datatype is equivalent to this datatype.

    The precise meaning of "equivalent" is datatype dependent.
    NOTE: if invoked by a DB object or manager it should be invoked on the DataTypeDB object passing the other datatype as the argument.

    Specified by:
      `isEquivalent` in interface `DataType`
    Parameters:
      `dt` - the datatype being tested for equivalence.
    Returns:
      true if the if the given datatype is equivalent to this datatype.

  - ### isEquivalentSignature

    public boolean isEquivalentSignature(FunctionSignature signature)
    Description copied from interface: `FunctionSignature`
    Returns true if the given signature is equivalent to this signature. The precise meaning of "equivalent" is dependent upon return/parameter dataTypes.
    Specified by:
      `isEquivalentSignature` in interface `FunctionSignature`
    Parameters:
      `signature` - the function signature being tested for equivalence.
    Returns:
      true if the if the given signature is equivalent to this signature.

  - ### dataTypeReplaced

    public void dataTypeReplaced(DataType oldDt, DataType newDt)
    Description copied from interface: `DataType`
    Informs this datatype that the given oldDT has been replaced with newDT

    TODO: This method is reserved for internal DB use.

    Specified by:
      `dataTypeReplaced` in interface `DataType`
    Overrides:
      `dataTypeReplaced` in class `AbstractDataType`
    Parameters:
      `oldDt` - old datatype
      `newDt` - new datatype

  - ### replaceArgument

    public void replaceArgument(int ordinal, String newName, DataType dt, String newComment, SourceType source)
    Description copied from interface: `FunctionDefinition`
    Replace the given argument with another data type
    Specified by:
      `replaceArgument` in interface `FunctionDefinition`
    Parameters:
      `ordinal` - the index of the argument to be replaced, starting from '0'
      `newName` - name of the new argument
      `dt` - data type of the new argument
      `newComment` - comment for the argument
      `source` - the source of this function definition argument: Symbol.DEFAULT, Symbol.ANALYSIS, Symbol.IMPORTED, or Symbol.USER_DEFINED

  - ### dataTypeSizeChanged

    public void dataTypeSizeChanged(DataType dt)
    Description copied from interface: `DataType`
    Notification that the given datatype's size has changed.

    DataTypes may need to make internal changes in response.
    TODO: This method is reserved for internal DB use.

    Specified by:
      `dataTypeSizeChanged` in interface `DataType`
    Overrides:
      `dataTypeSizeChanged` in class `AbstractDataType`
    Parameters:
      `dt` - the datatype that has changed.

  - ### dataTypeDeleted

    public void dataTypeDeleted(DataType dt)
    Description copied from interface: `DataType`
    Informs this datatype that the given datatype has been deleted.

    TODO: This method is reserved for internal DB use.

    Specified by:
      `dataTypeDeleted` in interface `DataType`
    Overrides:
      `dataTypeDeleted` in class `AbstractDataType`
    Parameters:
      `dt` - the datatype that has been deleted.

  - ### dataTypeNameChanged

    public void dataTypeNameChanged(DataType dt, String oldName)
    Description copied from interface: `DataType`
    Informs this datatype that its name has changed from the indicated old name.

    TODO: This method is reserved for internal DB use.

    Specified by:
      `dataTypeNameChanged` in interface `DataType`
    Overrides:
      `dataTypeNameChanged` in class `AbstractDataType`
    Parameters:
      `dt` - the datatype whose name changed
      `oldName` - the datatype's old name

  - ### dependsOn

    public boolean dependsOn(DataType dt)
    Description copied from interface: `DataType`
    Check if this datatype depends on the existence of the given datatype.

    For example byte[] depends on byte. If byte were deleted, then byte[] would also be deleted.

    Specified by:
      `dependsOn` in interface `DataType`
    Overrides:
      `dependsOn` in class `AbstractDataType`
    Parameters:
      `dt` - the datatype to test that this datatype depends on.
    Returns:
      true if the existence of this datatype relies on the existence of the specified datatype dt.

  - ### toString

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