Package ghidra.util

Class UndefinedFunction

  • All Implemented Interfaces:
    Function, Namespace
    public class UndefinedFunction
extends java.lang.Object
implements Function

    • Constructor Detail

      • UndefinedFunction

        public UndefinedFunction​(Program p,
                         Address entry)
        Undefined Function constructor. Function will adopt the default calling convention prototype defined by the program's compiler specification. The associated stack frame will also follow this default convention.
        Parameters:
        p - program containing the function
        entry - function entry point

    • Method Detail

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • isExternal

        public boolean isExternal()
        Specified by:
        isExternal in interface Function
        Specified by:
        isExternal in interface Namespace
        Returns:
        true if this function is external (i.e., entry point is in EXTERNAL address space)

      • getExternalLocation

        public ExternalLocation getExternalLocation()
        Specified by:
        getExternalLocation in interface Function
        Returns:
        if this is an external function return the associated external location object.

      • addParameter

        public Parameter addParameter​(Variable var,
                              SourceType source)
                       throws DuplicateNameException
        Description copied from interface: Function
        Adds the given variable to the end of the parameters list. The variable storage specified for the new parameter will be ignored if custom storage mode is not enabled. The VariableUtilities.checkVariableConflict(Function, Variable, VariableStorage, boolean) method may be used to check and remove conflicting variables which already exist in the function.
        Specified by:
        addParameter in interface Function
        Parameters:
        var - the variable to add as a new parameter.
        source - the source of this parameter which will be applied to the parameter symbol and overall function signature source. If parameter has a null or default name a SourceType of DEFAULT will be applied to the parameter symbol.
        Returns:
        the Parameter object created.
        Throws:
        DuplicateNameException - if another variable(parameter or local) already exists in the function with that name.

      • moveParameter

        public Parameter moveParameter​(int fromOrdinal,
                               int toOrdinal)
        Description copied from interface: Function
        Move the parameter which occupies the fromOrdinal position to the toOrdinal position. Parameters will be renumbered to reflect the new ordering. Auto-parameters may not be moved but must be accounted for in the specified ordinals.
        Specified by:
        moveParameter in interface Function
        Parameters:
        fromOrdinal - from ordinal position using the current numbering
        toOrdinal - the final position of the specified parameter

      • getCallingConvention

        public PrototypeModel getCallingConvention()
        Description copied from interface: Function
        Gets the calling convention prototype model for this function.
        Specified by:
        getCallingConvention in interface Function
        Returns:
        the prototype model of the function's current calling convention or null.

      • getCallingConventionName

        public java.lang.String getCallingConventionName()
        Description copied from interface: Function
        Gets the calling convention's name for this function.
        Specified by:
        getCallingConventionName in interface Function
        Returns:
        the name of the calling convention or Function.DEFAULT_CALLING_CONVENTION_STRING (i.e. "default", if the calling convention has been set to the default for this function) or Function.UNKNOWN_CALLING_CONVENTION_STRING (i.e. "unknown", if no calling convention is specified for this function).

      • getComment

        public java.lang.String getComment()
        Description copied from interface: Function
        Get the comment for this function.
        Specified by:
        getComment in interface Function
        Returns:
        the comment for this function

      • getCommentAsArray

        public java.lang.String[] getCommentAsArray()
        Description copied from interface: Function
        Returns the function (same as plate) comment as an array of strings where each item in the array is a line of text in the comment.
        Specified by:
        getCommentAsArray in interface Function

      • getDefaultCallingConventionName

        public java.lang.String getDefaultCallingConventionName()
        Description copied from interface: Function
        Gets the name of the default calling convention.
        Note: The name in the PrototypeModel of the default calling convention may be null.
        Specified by:
        getDefaultCallingConventionName in interface Function
        Returns:
        the name of the default calling convention.

      • getEntryPoint

        public Address getEntryPoint()
        Description copied from interface: Function
        Get the entry point for this function. Functions may only have ONE entry point.
        Specified by:
        getEntryPoint in interface Function
        Returns:
        the entry point

      • getLocalVariables

        public Variable[] getLocalVariables()
        Description copied from interface: Function
        Get all local function variables
        Specified by:
        getLocalVariables in interface Function
        Returns:
        all local function variables

      • getName

        public java.lang.String getName()
        Description copied from interface: Function
        Get the name of this function.
        Specified by:
        getName in interface Function
        Specified by:
        getName in interface Namespace
        Returns:
        the functions name

      • getParameter

        public Parameter getParameter​(int ordinal)
        Description copied from interface: Function
        Returns the specified parameter including an auto-param at the specified ordinal.
        Specified by:
        getParameter in interface Function
        Parameters:
        ordinal - the index of the parameter to return.
        Returns:
        parameter or null if ordinal is out of range

      • getParameterCount

        public int getParameterCount()
        Description copied from interface: Function
        Gets the total number of parameters for this function. This number also includes any auto-parameters which may have been injected when dynamic parameter storage is used.
        Specified by:
        getParameterCount in interface Function
        Returns:
        the total number of parameters

      • getAutoParameterCount

        public int getAutoParameterCount()
        Description copied from interface: Function
        Gets the number of auto-parameters for this function also included in the total count provided by Function.getParameterCount(). This number will always be 0 when custom parameter storage is used.
        Specified by:
        getAutoParameterCount in interface Function
        Returns:
        the number of auto-parameters

      • getParameters

        public Parameter[] getParameters()
        Description copied from interface: Function
        Get all function parameters
        Specified by:
        getParameters in interface Function
        Returns:
        all function parameters

      • getProgram

        public Program getProgram()
        Description copied from interface: Function
        Get the program containing this function.
        Specified by:
        getProgram in interface Function
        Returns:
        the program

      • getParameters

        public Parameter[] getParameters​(VariableFilter filter)
        Description copied from interface: Function
        Get all function parameters which satisfy the specified filter
        Specified by:
        getParameters in interface Function
        Parameters:
        filter - variable filter or null for all parameters to be returned
        Returns:
        all function parameters which satisfy the specified filter

      • getLocalVariables

        public Variable[] getLocalVariables​(VariableFilter filter)
        Description copied from interface: Function
        Get all local function variables which satisfy the specified filter
        Specified by:
        getLocalVariables in interface Function
        Parameters:
        filter - variable filter or null for all local variables to be returned
        Returns:
        all function variables which satisfy the specified filter

      • getVariables

        public Variable[] getVariables​(VariableFilter filter)
        Description copied from interface: Function
        Get all function variables which satisfy the specified filter
        Specified by:
        getVariables in interface Function
        Parameters:
        filter - variable filter or null for all variables to be returned
        Returns:
        all function variables which satisfy the specified filter

      • hasCustomVariableStorage

        public boolean hasCustomVariableStorage()
        Specified by:
        hasCustomVariableStorage in interface Function
        Returns:
        true if function parameters utilize custom variable storage.

      • setCustomVariableStorage

        public void setCustomVariableStorage​(boolean hasCustomVariableStorage)
        Description copied from interface: Function
        Set whether or not this function uses custom variable storage
        Specified by:
        setCustomVariableStorage in interface Function

      • getAllVariables

        public Variable[] getAllVariables()
        Description copied from interface: Function
        Returns an array of all local and parameter variables
        Specified by:
        getAllVariables in interface Function
        Returns:

      • getRepeatableComment

        public java.lang.String getRepeatableComment()
        Description copied from interface: Function
        Returns the repeatable comment for this function. A repeatable comment is a comment that will appear at locations that 'call' this function.
        Specified by:
        getRepeatableComment in interface Function
        Returns:
        the repeatable comment for this function

      • getRepeatableCommentAsArray

        public java.lang.String[] getRepeatableCommentAsArray()
        Description copied from interface: Function
        Returns the repeatable comment as an array of strings.
        Specified by:
        getRepeatableCommentAsArray in interface Function
        Returns:
        the repeatable comment as an array of strings

      • getReturnType

        public DataType getReturnType()
        Description copied from interface: Function
        Get the Function's return type. A null return value indicates the functions return type has never been set.
        Specified by:
        getReturnType in interface Function
        Returns:
        the DataType that this function returns.

      • getReturn

        public Parameter getReturn()
        Description copied from interface: Function
        Get the Function's return type/storage represented by a Parameter object. The parameter's ordinal value will be equal to Parameter.RETURN_ORIDINAL.
        Specified by:
        getReturn in interface Function
        Returns:
        return data-type/storage

      • setReturn

        public void setReturn​(DataType type,
                      VariableStorage storage,
                      SourceType source)
               throws InvalidInputException
        Description copied from interface: Function
        Set the return data-type and storage.

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

        Specified by:
        setReturn in interface Function
        source - source to be combined with the overall signature source.
        Throws:
        InvalidInputException - if data type is not a fixed length or storage is improperly sized

      • getSignature

        public FunctionSignature getSignature()
        Description copied from interface: Function
        Get the function's effective signature. This is equivalent to invoking getSignature(false) where auto-params and forced-indirect types will be reflected in the signature if present.

        WARNING! It is important to note that the calling convention may not be properly retained by the returned signature object if a non-generic calling convention is used by this function as defined by the program's compiler specification.
        Specified by:
        getSignature in interface Function
        Returns:
        the function's signature

      • getSignature

        public FunctionSignature getSignature​(boolean formalSignature)
        Description copied from interface: Function
        Get the function's signature.

        WARNING! It is important to note that the calling convention may not be properly retained by the returned signature object if a non-generic calling convention is used by this function as defined by the program's compiler specification.
        Specified by:
        getSignature in interface Function
        Parameters:
        formalSignature - if true only original raw types will be retained and auto-params discarded (e.g., this, __return_storage_ptr__, etc.) within the returned signature. If false, the effective signature will be returned where forced indirect and auto-params are reflected in the signature. This option has no affect if the specified function has custom storage enabled.
        Returns:
        the function's signature

      • getPrototypeString

        public java.lang.String getPrototypeString​(boolean formalSignature,
                                           boolean includeCallingConvention)
        Description copied from interface: Function
        Return a string representation of the function signature
        Specified by:
        getPrototypeString in interface Function
        Parameters:
        formalSignature - if true only original raw return/parameter types will be retained and auto-params discarded (e.g., this, __return_storage_ptr__, etc.) within the returned signature. If false, the effective signature will be returned where forced indirect and auto-params are reflected in the signature. This option has no affect if the specified function has custom storage enabled.
        includeCallingConvention - if true prototype will include call convention declaration if known.

      • getSignatureSource

        public SourceType getSignatureSource()
        Description copied from interface: Function
        Returns the source type for the overall signature excluding function name and parameter names whose source is carried by the corresponding symbol.
        Specified by:
        getSignatureSource in interface Function
        Returns:
        the overall SourceType of the function signature;

      • setSignatureSource

        public void setSignatureSource​(SourceType signatureSource)
        Description copied from interface: Function
        Set the source type for the overall signature excluding function name and parameter names whose source is carried by the corresponding symbol.
        Specified by:
        setSignatureSource in interface Function
        Parameters:
        signatureSource - function signature source type

      • getStackFrame

        public StackFrame getStackFrame()
        Description copied from interface: Function
        Get the stack frame for this function. NOTE: Use of the stack frame must be avoided during upgrade activity since the compiler spec may not be known (i.e., due to language upgrade process).
        Specified by:
        getStackFrame in interface Function
        Returns:
        this functions stack frame

      • getStackPurgeSize

        public int getStackPurgeSize()
        Description copied from interface: Function
        Get the change in the stack pointer resulting from calling this function.
        Specified by:
        getStackPurgeSize in interface Function
        Returns:
        int the change in bytes to the stack pointer

      • hasNoReturn

        public boolean hasNoReturn()
        Specified by:
        hasNoReturn in interface Function
        Returns:
        true if this function does not return.

      • hasVarArgs

        public boolean hasVarArgs()
        Description copied from interface: Function
        Returns true if this function has a variable argument list (VarArgs).
        Specified by:
        hasVarArgs in interface Function

      • insertParameter

        public Parameter insertParameter​(int ordinal,
                                 Variable var,
                                 SourceType source)
                          throws DuplicateNameException
        Description copied from interface: Function
        Inserts the given variable into the parameters list. The variable storage specified for the new parameter will be ignored if custom storage mode is not enabled. The VariableUtilities.checkVariableConflict(Function, Variable, VariableStorage, boolean) method may be used to check and remove conflicting variables which already exist in the function.
        Specified by:
        insertParameter in interface Function
        Parameters:
        ordinal - the position with the parameters to insert to. This ordinal must factor in the presence of auto-parameters which may be injected dynamically based upon calling convention and return data type. Parameters may not be inserted befor an auto-parameter.
        var - the variable to add as a new parameter.
        source - the source of this parameter which will be applied to the parameter symbol and overall function signature source. If parameter has a null or default name a SourceType of DEFAULT will be applied to the parameter symbol.
        Returns:
        the Parameter object created.
        Throws:
        DuplicateNameException - if another variable(parameter or local) already exists in the function with that name.

      • replaceParameters

        public void replaceParameters​(java.util.List<? extends Variable> params,
                              Function.FunctionUpdateType updateType,
                              boolean force,
                              SourceType source)
                       throws DuplicateNameException,
                              InvalidInputException
        Description copied from interface: Function
        Replace all current parameters with the given list of parameters. The VariableUtilities.checkVariableConflict(Function, Variable, VariableStorage, boolean) method may be used to check and remove conflicting variables which already exist in the function.
        Specified by:
        replaceParameters in interface Function
        Parameters:
        params - the new set of parameters for the function.
        updateType - function update type
        force - if true any conflicting local parameters will be removed
        source - the source of these parameters which will be applied to the parameter symbols and overall function signature source. If parameter names are null or a default name a SourceType of DEFAULT will be applied to the corresponding parameter symbol.
        Throws:
        DuplicateNameException - if another variable(parameter or local) already exists in the function with that name.
        InvalidInputException - if a parameter data type is not a fixed length or variable name is invalid.
        VariableSizeException - if a parameter data type size is too large based upon storage constraints or conflicts with another variable.

      • updateFunction

        public void updateFunction​(java.lang.String callingConvention,
                           Variable returnValue,
                           Function.FunctionUpdateType updateType,
                           boolean force,
                           SourceType source,
                           Variable... newParams)
                    throws DuplicateNameException,
                           InvalidInputException
        Description copied from interface: Function
        Replace all current parameters with the given list of parameters and optionally change the calling convention and function return. The VariableUtilities.checkVariableConflict(Function, Variable, VariableStorage, boolean) method may be used to check and remove conflicting variables which already exist in the function.
        Specified by:
        updateFunction in interface Function
        Parameters:
        callingConvention - updated calling convention name or null if no change is required
        updateType - function update type
        force - if true any conflicting local parameters will be removed
        source - the source of these parameters which will be applied to the parameter symbols and overall function signature source. If parameter names are null or a default name a SourceType of DEFAULT will be applied to the corresponding parameter symbol.
        Throws:
        DuplicateNameException - if another variable(parameter or local) already exists in the function with that name.
        InvalidInputException - if a parameter data type is not a fixed length or variable name is invalid.
        VariableSizeException - if a parameter data type size is too large based upon storage constraints or conflicts with another variable.

      • updateFunction

        public void updateFunction​(java.lang.String callingConvention,
                           Variable returnVar,
                           java.util.List<? extends Variable> newParams,
                           Function.FunctionUpdateType updateType,
                           boolean force,
                           SourceType source)
                    throws DuplicateNameException,
                           InvalidInputException
        Description copied from interface: Function
        Replace all current parameters with the given list of parameters and optionally change the calling convention and function return. The VariableUtilities.checkVariableConflict(Function, Variable, VariableStorage, boolean) method may be used to check and remove conflicting variables which already exist in the function.
        Specified by:
        updateFunction in interface Function
        Parameters:
        callingConvention - updated calling convention name or null if no change is required
        returnVar - return variable or null if no change required
        updateType - function update type
        force - if true any conflicting local parameters will be removed
        source - the source of these parameters which will be applied to the parameter symbols and overall function signature source. If parameter names are null or a default name a SourceType of DEFAULT will be applied to the corresponding parameter symbol.
        Throws:
        DuplicateNameException - if another variable(parameter or local) already exists in the function with that name.
        InvalidInputException - if a parameter data type is not a fixed length or variable name is invalid.
        VariableSizeException - if a parameter data type size is too large based upon storage constraints or conflicts with another variable.

      • isInline

        public boolean isInline()
        Specified by:
        isInline in interface Function
        Returns:
        true if this is an inline function.

      • isStackPurgeSizeValid

        public boolean isStackPurgeSizeValid()
        Description copied from interface: Function
        check if stack purge size is valid.
        Specified by:
        isStackPurgeSizeValid in interface Function
        Returns:
        true if the stack depth is valid

      • removeParameter

        public void removeParameter​(int ordinal)
        Description copied from interface: Function
        Remove the specified parameter. Auto-parameters may not be removed but must be accounted for in the specified ordinal.
        Specified by:
        removeParameter in interface Function
        Parameters:
        ordinal - the index of the parameter to be removed.

      • removeVariable

        public void removeVariable​(Variable var)
        Description copied from interface: Function
        Removes the given variable from the function.
        Specified by:
        removeVariable in interface Function
        Parameters:
        var - the variable to remove.

      • setBody

        public void setBody​(AddressSetView newBody)
        Description copied from interface: Function
        Set the new body for this function. The entry point must be contained in the new body.
        Specified by:
        setBody in interface Function
        Parameters:
        newBody - address set to use as the body of this function

      • setCallingConvention

        public void setCallingConvention​(java.lang.String name)
                          throws InvalidInputException
        Description copied from interface: Function
        Sets the calling convention for this function to the named calling convention.
        Specified by:
        setCallingConvention in interface Function
        Parameters:
        name - the name of the calling convention. "unknown" and "default" are reserved names that can also be used here.
        Null or Function.UNKNOWN_CALLING_CONVENTION_STRING sets this function to not have a calling convention (i.e. unknown).
        Function.DEFAULT_CALLING_CONVENTION_STRING sets this function to use the default calling convention. (i.e. default)
        Throws:
        InvalidInputException - if the specified name is not a recognized calling convention name.

      • setComment

        public void setComment​(java.lang.String comment)
        Description copied from interface: Function
        Set the comment for this function.
        Specified by:
        setComment in interface Function
        Parameters:
        comment - the string to set as the comment.

      • setInline

        public void setInline​(boolean isInline)
        Description copied from interface: Function
        Sets whether or not this function is inline.
        Specified by:
        setInline in interface Function
        Parameters:
        isInline - true if this is an inline function.

      • setNoReturn

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

      • setRepeatableComment

        public void setRepeatableComment​(java.lang.String comment)
        Description copied from interface: Function
        Set the repeatable comment for this function.
        Specified by:
        setRepeatableComment in interface Function
        Parameters:
        comment - the string to set as the repeatable comment.

      • setReturnType

        public void setReturnType​(DataType type,
                          SourceType source)
        Description copied from interface: Function
        Set the function's return type.
        Specified by:
        setReturnType in interface Function
        Parameters:
        type - the dataType that will define this functions return type.
        source - TODO

      • setStackPurgeSize

        public void setStackPurgeSize​(int purgeSize)
        Description copied from interface: Function
        Set the change in the stack pointer resulting from calling this function.
        Specified by:
        setStackPurgeSize in interface Function
        Parameters:
        purgeSize - the change in bytes to the stack pointer

      • setVarArgs

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

      • getBody

        public AddressSetView getBody()
        Description copied from interface: Namespace
        Get the address set for this namespace. Note: The body of a namespace (currently only used by the function namespace) is restricted it Integer.MAX_VALUE.
        Specified by:
        getBody in interface Namespace

      • getID

        public long getID()
        Description copied from interface: Namespace
        Return the namespace id;
        Specified by:
        getID in interface Namespace

      • getName

        public java.lang.String getName​(boolean includeNamespacePath)
        Description copied from interface: Namespace
        Returns the fully qualified name.
        Specified by:
        getName in interface Namespace

      • getParentNamespace

        public Namespace getParentNamespace()
        Description copied from interface: Namespace
        Get the parent scope.
        Specified by:
        getParentNamespace in interface Namespace
        Returns:
        null if this scope is the global scope.

      • getSymbol

        public Symbol getSymbol()
        Description copied from interface: Namespace
        Get the symbol for this namespace; Note: The global namespace will return null
        Specified by:
        getSymbol in interface Namespace

      • getCallFixup

        public java.lang.String getCallFixup()
        Description copied from interface: Function
        Returns the current call-fixup name set on this instruction or null if one has not been set.
        Specified by:
        getCallFixup in interface Function

      • setCallFixup

        public void setCallFixup​(java.lang.String name)
        Description copied from interface: Function
        Set the named call-fixup for this function.
        Specified by:
        setCallFixup in interface Function
        Parameters:
        name - name of call-fixup specified by compiler spec. A null value will clear the current setting.

      • getThunkedFunction

        public Function getThunkedFunction​(boolean recursive)
        Description copied from interface: Function
        If this function is a Thunk, this method returns the referenced function.
        Specified by:
        getThunkedFunction in interface Function
        Parameters:
        recursive - if true and the thunked-function is a thunk itself, the returned thunked-function will be the final thunked-function which will never be a thunk.
        Returns:
        function referenced by this Thunk Function or null if this is not a Thunk function

      • setThunkedFunction

        public void setThunkedFunction​(Function thunkedFunction)
        Description copied from interface: Function
        Set the currently Thunked Function or null to convert to a normal function
        Specified by:
        setThunkedFunction in interface Function
        Parameters:
        thunkedFunction - the thunked function or null to convert this thunked function to a normal function.

      • getFunctionThunkAddresses

        public Address[] getFunctionThunkAddresses()
        Description copied from interface: Function
        If this function is "Thunked", an array of Thunk Function entry points is returned
        Specified by:
        getFunctionThunkAddresses in interface Function
        Returns:
        associated thunk function entry points or null if this is not a "Thunked" function.

      • getCallingFunctions

        public java.util.Set<Function> getCallingFunctions​(TaskMonitor monitor)
        Description copied from interface: Function
        Returns a set of functions that call this function.
        Specified by:
        getCallingFunctions in interface Function
        Parameters:
        monitor - The monitor that is used to report progress and allow for canceling of the search. May be null.
        Returns:
        a set of functions that call this function.

      • getCalledFunctions

        public java.util.Set<Function> getCalledFunctions​(TaskMonitor monitor)
        Description copied from interface: Function
        Returns a set of functions that this function calls.
        Specified by:
        getCalledFunctions in interface Function
        Parameters:
        monitor - The monitor that is used to report progress and allow for canceling of the search. May be null.
        Returns:
        a set of functions that this function calls.

      • removeTag

        public void removeTag​(java.lang.String tagName)
        Description copied from interface: Function
        Removes the given tag from this function.
        Specified by:
        removeTag in interface Function
        Parameters:
        tagName - the tag name to be removed.

      • getTags

        public java.util.Set<FunctionTag> getTags()
        Description copied from interface: Function
        Return all FunctionTag objects associated with this function.
        Specified by:
        getTags in interface Function
        Returns:
        set of tag names

      • addTag

        public boolean addTag​(java.lang.String tagName)
        Description copied from interface: Function
        Adds the tag with the given name to this function; if one does not exist, one is created.
        Specified by:
        addTag in interface Function
        Parameters:
        tagName - the tag name to add
        Returns:
        true if the tag was successfully added

      • promoteLocalUserLabelsToGlobal

        public void promoteLocalUserLabelsToGlobal()
        Description copied from interface: Function
        Changes all local user-defined labels for this function to global symbols. If a global code symbol already exists with the same name at the symbols address the symbol will be removed.
        Specified by:
        promoteLocalUserLabelsToGlobal in interface Function