Functions to stub (-functions-to-stub)

Specify functions to stub during analysis

Description

Specify functions to stub during analysis.

For specified functions, Polyspace^® :

• Ignores the function definition even if it exists.

• Assumes that the function inputs and outputs have full range of values allowed by their type.

Set Option

User interface (desktop products only): In your project configuration, the option is on the Inputs & Stubbing node.

User interface (Polyspace Platform, desktop products only): In your project configuration, the option is on the Static Analysis tab on the Inputs & Stubbing node.

Command line and options file: Use the option -functions-to-stub. See Command-Line Information.

Why Use This Option

If you want the analysis to ignore the code in a function body, you can stub the function.

For instance:

• Suppose you have not completed writing the function and do not want the analysis to consider the function body. You can use this option to stub the function and then specify constraints on its return value and modifiable arguments.

• Suppose the analysis of a function body is imprecise. The analysis assumes that the function returns all possible values that the function return type allows. You can use this option to stub the function and then specify constraints on its return value.

Settings

No Default

Enter function names or choose from a list.

• Click to add a field and enter the function name.

• Click to list functions in your code. Choose functions from the list.

When entering function names, use either the basic syntax or, to differentiate overloaded functions, the argument syntax. For the argument syntax, separate function arguments with semicolons. See the following code and table for examples.

//simple function

void test(int a, int b);

//C++ template function

Template <class myType>
myType test(myType a, myType b);

//C++ class method

class A {
	public:
	int test(int var1, int var2);
};


//C++ template class method

template <class myType> class A
{
	public:
	myType test(myType var1, myType var2);
};

Function Type	Basic Syntax	Argument Syntax
Simple function	test	test(int; int)
C++ template function	test	test(myType; myType)
C++ class method	A::test	A::test(int;int)
C++ template class method	A<myType>::test	A<myType>::test(myType;myType)

Tips

• Code Prover makes assumptions about the arguments and return values of stubbed functions. For example, Polyspace assumes that the return values of stubbed functions are full range. These assumptions can affect checks in other sections of the code. See Code Prover Assumptions About Stubbed Functions (Polyspace Code Prover).

• If you stub a function, you can constrain the range of function arguments and return value. To specify constraints, use the analysis option Constraint setup (-data-range-specifications).

• When you use this option, you might see a change in file-level code complexity metrics such as number of lines and comment density because one or more function bodies are no longer analyzed.

• For C functions, these special characters are allowed:( ) < > ; _

  For C++ functions, these special characters are allowed : ( ) < > ; _ * & [ ]

  Space characters are allowed for C++, but are not allowed for C functions.

• You cannot use this option to stub the following C++ functions:

  • constexpr functions

  • Function-try-blocks that associate a catch clause with an entire function body, for instance:

    Class()
        try : Class( 0.0 ) //delegate constructor
        {
            // ...
        }
        catch (...)
        {
            // exception occurred on initialization
        }

  • Template functions with a parameter pack, for instance:

    template <class T, class... T2>
        X(T n, T n2, T2... rest): X(rest...) {
            v.insert(v.begin(), n);
            v.insert(v.begin(), n2);
        }

  • Functions with auto return type, for instance:

    template <typename F, typename... Args>
    inline decltype(auto) invoke(F&& func, Args&&... args)
    {
      return invoke_impl(eastl::forward<F>(func), eastl::forward<Args>(args)...);
    }

Command-Line Information

Parameter: -functions-to-stub

No Default

Value: function1[,function2[,...]]

Example (Code Prover): polyspace-code-prover -sources file_name -functions-to-stub function_1,function_2

Example (Code Prover Server): polyspace-code-prover-server -sources file_name -functions-to-stub function_1,function_2