Package ghidra.program.model.listing

Interface Function

    • Field Detail

      • DEFAULT_PARAM_PREFIX

        static final java.lang.String DEFAULT_PARAM_PREFIX
        See Also:
        Constant Field Values

      • THIS_PARAM_NAME

        static final java.lang.String THIS_PARAM_NAME

      • RETURN_PTR_PARAM_NAME

        static final java.lang.String RETURN_PTR_PARAM_NAME

      • DEFAULT_PARAM_PREFIX_LEN

        static final int DEFAULT_PARAM_PREFIX_LEN

      • DEFAULT_LOCAL_PREFIX

        static final java.lang.String DEFAULT_LOCAL_PREFIX
        See Also:
        Constant Field Values

      • DEFAULT_LOCAL_RESERVED_PREFIX

        static final java.lang.String DEFAULT_LOCAL_RESERVED_PREFIX
        See Also:
        Constant Field Values

      • DEFAULT_LOCAL_TEMP_PREFIX

        static final java.lang.String DEFAULT_LOCAL_TEMP_PREFIX
        See Also:
        Constant Field Values

      • DEFAULT_LOCAL_PREFIX_LEN

        static final int DEFAULT_LOCAL_PREFIX_LEN

      • UNKNOWN_CALLING_CONVENTION_STRING

        static final java.lang.String UNKNOWN_CALLING_CONVENTION_STRING
        See Also:
        Constant Field Values

      • DEFAULT_CALLING_CONVENTION_STRING

        static final java.lang.String DEFAULT_CALLING_CONVENTION_STRING
        See Also:
        Constant Field Values

      • UNKNOWN_STACK_DEPTH_CHANGE

        static final int UNKNOWN_STACK_DEPTH_CHANGE
        Default Stack depth for a function.
        See Also:
        Constant Field Values

      • INVALID_STACK_DEPTH_CHANGE

        static final int INVALID_STACK_DEPTH_CHANGE
        See Also:
        Constant Field Values

    • Method Detail

      • getName

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

      • setCallFixup

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

      • getCallFixup

        java.lang.String getCallFixup()
        Returns the current call-fixup name set on this instruction or null if one has not been set.

      • getProgram

        Program getProgram()
        Get the program containing this function.
        Returns:
        the program

      • getComment

        java.lang.String getComment()
        Get the comment for this function.
        Returns:
        the comment for this function

      • getCommentAsArray

        java.lang.String[] getCommentAsArray()
        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.

      • setComment

        void setComment​(java.lang.String comment)
        Set the comment for this function.
        Parameters:
        comment - the string to set as the comment.

      • getRepeatableComment

        java.lang.String getRepeatableComment()
        Returns the repeatable comment for this function. A repeatable comment is a comment that will appear at locations that 'call' this function.
        Returns:
        the repeatable comment for this function

      • getRepeatableCommentAsArray

        java.lang.String[] getRepeatableCommentAsArray()
        Returns the repeatable comment as an array of strings.
        Returns:
        the repeatable comment as an array of strings

      • setRepeatableComment

        void setRepeatableComment​(java.lang.String comment)
        Set the repeatable comment for this function.
        Parameters:
        comment - the string to set as the repeatable comment.

      • getEntryPoint

        Address getEntryPoint()
        Get the entry point for this function. Functions may only have ONE entry point.
        Returns:
        the entry point

      • getReturnType

        DataType getReturnType()
        Get the Function's return type. A null return value indicates the functions return type has never been set.
        Returns:
        the DataType that this function returns.

      • getReturn

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

      • setReturn

        void setReturn​(DataType type,
               VariableStorage storage,
               SourceType source)
        throws InvalidInputException
        Set the return data-type and storage.

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

        Parameters:
        type -
        storage -
        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

        FunctionSignature getSignature()
        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.
        Returns:
        the function's signature

      • getSignature

        FunctionSignature getSignature​(boolean formalSignature)
        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.
        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

        java.lang.String getPrototypeString​(boolean formalSignature,
                                    boolean includeCallingConvention)
        Return a string representation of the function signature
        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

        SourceType getSignatureSource()
        Returns the source type for the overall signature excluding function name and parameter names whose source is carried by the corresponding symbol.
        Returns:
        the overall SourceType of the function signature;

      • setSignatureSource

        void setSignatureSource​(SourceType signatureSource)
        Set the source type for the overall signature excluding function name and parameter names whose source is carried by the corresponding symbol.
        Parameters:
        signatureSource - function signature source type

      • getStackFrame

        StackFrame getStackFrame()
        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).
        Returns:
        this functions stack frame

      • getStackPurgeSize

        int getStackPurgeSize()
        Get the change in the stack pointer resulting from calling this function.
        Returns:
        int the change in bytes to the stack pointer

      • getTags

        java.util.Set<FunctionTag> getTags()
        Return all FunctionTag objects associated with this function.
        Returns:
        set of tag names

      • addTag

        boolean addTag​(java.lang.String name)
        Adds the tag with the given name to this function; if one does not exist, one is created.
        Parameters:
        name - the tag name to add
        Returns:
        true if the tag was successfully added

      • removeTag

        void removeTag​(java.lang.String name)
        Removes the given tag from this function.
        Parameters:
        name - the tag name to be removed.

      • setStackPurgeSize

        void setStackPurgeSize​(int purgeSize)
        Set the change in the stack pointer resulting from calling this function.
        Parameters:
        purgeSize - the change in bytes to the stack pointer

      • isStackPurgeSizeValid

        boolean isStackPurgeSizeValid()
        check if stack purge size is valid.
        Returns:
        true if the stack depth is valid

      • insertParameter

        @Deprecated
Parameter insertParameter​(int ordinal,
                          Variable var,
                          SourceType source)
                   throws DuplicateNameException,
                          InvalidInputException
        Deprecated.
        The use of this method is discouraged due to the potential injection of auto-parameters which are easily overlooked when considering parameter ordinal. The function signature should generally be adjusted with a single call to updateFunction(String, Variable, List, FunctionUpdateType, boolean, SourceType)
        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.
        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.
        InvalidInputException - if data type is not a fixed length or variable name is invalid.
        VariableSizeException - if data type size is too large based upon storage constraints.

      • replaceParameters

        void replaceParameters​(java.util.List<? extends Variable> params,
                       Function.FunctionUpdateType updateType,
                       boolean force,
                       SourceType source)
                throws DuplicateNameException,
                       InvalidInputException
        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.
        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.

      • replaceParameters

        void replaceParameters​(Function.FunctionUpdateType updateType,
                       boolean force,
                       SourceType source,
                       Variable... params)
                throws DuplicateNameException,
                       InvalidInputException
        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.
        Parameters:
        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.
        params - the new parameters for the function.
        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

        void updateFunction​(java.lang.String callingConvention,
                    Variable returnValue,
                    Function.FunctionUpdateType updateType,
                    boolean force,
                    SourceType source,
                    Variable... newParams)
             throws DuplicateNameException,
                    InvalidInputException
        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.
        Parameters:
        callingConvention - updated calling convention name or null if no change is required
        returnVar - return variable or null if no change required
        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

        void updateFunction​(java.lang.String callingConvention,
                    Variable returnVar,
                    java.util.List<? extends Variable> newParams,
                    Function.FunctionUpdateType updateType,
                    boolean force,
                    SourceType source)
             throws DuplicateNameException,
                    InvalidInputException
        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.
        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.
        params - the new parameters for the function (required).
        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.

      • getParameter

        Parameter getParameter​(int ordinal)
        Returns the specified parameter including an auto-param at the specified ordinal.
        Parameters:
        ordinal - the index of the parameter to return.
        Returns:
        parameter or null if ordinal is out of range

      • removeParameter

        @Deprecated
void removeParameter​(int ordinal)
        Deprecated.
        The use of this method is discouraged. The function signature should generally be adjusted with a single call to updateFunction(String, Variable, List, FunctionUpdateType, boolean, SourceType)
        Remove the specified parameter. Auto-parameters may not be removed but must be accounted for in the specified ordinal.
        Parameters:
        ordinal - the index of the parameter to be removed.

      • moveParameter

        @Deprecated
Parameter moveParameter​(int fromOrdinal,
                        int toOrdinal)
                 throws InvalidInputException
        Deprecated.
        The use of this method is discouraged. The function signature should generally be adjusted with a single call to updateFunction(String, Variable, List, FunctionUpdateType, boolean, SourceType)
        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.
        Parameters:
        fromOrdinal - from ordinal position using the current numbering
        toOrdinal - the final position of the specified parameter
        Throws:
        InvalidInputException

      • getParameterCount

        int getParameterCount()
        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.
        Returns:
        the total number of parameters

      • getAutoParameterCount

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

      • getParameters

        Parameter[] getParameters()
        Get all function parameters
        Returns:
        all function parameters

      • getParameters

        Parameter[] getParameters​(VariableFilter filter)
        Get all function parameters which satisfy the specified filter
        Parameters:
        filter - variable filter or null for all parameters to be returned
        Returns:
        all function parameters which satisfy the specified filter

      • getLocalVariables

        Variable[] getLocalVariables()
        Get all local function variables
        Returns:
        all local function variables

      • getLocalVariables

        Variable[] getLocalVariables​(VariableFilter filter)
        Get all local function variables which satisfy the specified filter
        Parameters:
        filter - variable filter or null for all local variables to be returned
        Returns:
        all function variables which satisfy the specified filter

      • getVariables

        Variable[] getVariables​(VariableFilter filter)
        Get all function variables which satisfy the specified filter
        Parameters:
        filter - variable filter or null for all variables to be returned
        Returns:
        all function variables which satisfy the specified filter

      • getAllVariables

        Variable[] getAllVariables()
        Returns an array of all local and parameter variables
        Returns:

      • removeVariable

        void removeVariable​(Variable var)
        Removes the given variable from the function.
        Parameters:
        var - the variable to remove.

      • hasVarArgs

        boolean hasVarArgs()
        Returns true if this function has a variable argument list (VarArgs).

      • setVarArgs

        void setVarArgs​(boolean hasVarArgs)
        Set whether parameters can be passed as a VarArg (variable argument list).
        Parameters:
        hasVarArgs - true if this function has a variable argument list (ie printf(fmt, ...)).

      • isInline

        boolean isInline()
        Returns:
        true if this is an inline function.

      • setInline

        void setInline​(boolean isInline)
        Sets whether or not this function is inline.
        Parameters:
        isInline - true if this is an inline function.

      • hasNoReturn

        boolean hasNoReturn()
        Returns:
        true if this function does not return.

      • setNoReturn

        void setNoReturn​(boolean hasNoReturn)
        Set whether or not this function has a return.
        Parameters:
        hasNoReturn - true if this function does not return.

      • hasCustomVariableStorage

        boolean hasCustomVariableStorage()
        Returns:
        true if function parameters utilize custom variable storage.

      • setCustomVariableStorage

        void setCustomVariableStorage​(boolean hasCustomVariableStorage)
        Set whether or not this function uses custom variable storage
        Parameters:
        hasCustomVariableStorage -

      • getCallingConvention

        PrototypeModel getCallingConvention()
        Gets the calling convention prototype model for this function.
        Returns:
        the prototype model of the function's current calling convention or null.

      • getCallingConventionName

        java.lang.String getCallingConventionName()
        Gets the calling convention's name for this 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).

      • getDefaultCallingConventionName

        java.lang.String getDefaultCallingConventionName()
        Gets the name of the default calling convention.
        Note: The name in the PrototypeModel of the default calling convention may be null.
        Returns:
        the name of the default calling convention.

      • setCallingConvention

        void setCallingConvention​(java.lang.String name)
                   throws InvalidInputException
        Sets the calling convention for this function to the named calling convention.
        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.

      • isThunk

        boolean isThunk()
        Returns:
        true if this function is a Thunk and has a referenced Thunked Function.
        See Also:
        getThunkedFunction(boolean)

      • getThunkedFunction

        Function getThunkedFunction​(boolean recursive)
        If this function is a Thunk, this method returns the referenced 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

      • getFunctionThunkAddresses

        Address[] getFunctionThunkAddresses()
        If this function is "Thunked", an array of Thunk Function entry points is returned
        Returns:
        associated thunk function entry points or null if this is not a "Thunked" function.

      • setThunkedFunction

        void setThunkedFunction​(Function thunkedFunction)
                 throws java.lang.IllegalArgumentException
        Set the currently Thunked Function or null to convert to a normal function
        Parameters:
        thunkedFunction - the thunked function or null to convert this thunked function to a normal function.
        Throws:
        java.lang.IllegalArgumentException - if an attempt is made to thunk a function or another thunk which would result in a loop back to this function or if this function is an external function, or specified function is from a different program instance.

      • isExternal

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

      • getExternalLocation

        ExternalLocation getExternalLocation()
        Returns:
        if this is an external function return the associated external location object.

      • getCallingFunctions

        java.util.Set<Function> getCallingFunctions​(TaskMonitor monitor)
        Returns a set of functions that call this 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

        java.util.Set<Function> getCalledFunctions​(TaskMonitor monitor)
        Returns a set of functions that this function calls.
        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.

      • promoteLocalUserLabelsToGlobal

        void promoteLocalUserLabelsToGlobal()
        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.