Main Content

Detect stack pointer dereference outside scope (-detect-pointer-escape)

Find cases where a function returns a pointer to one of its local variables

Description

This option affects a Code Prover analysis only.

Specify that the verification must detect cases where you access a variable outside its scope via dangling pointers. Such an access can happen, for example, when a function returns a pointer to a local variable and you dereference the pointer outside the function. The dereference causes undefined behavior because the local variable that the pointer points to does not live outside the function.

Set Option

User interface (desktop products only): In your project configuration, the option is on the Check Behavior node.

User interface (Polyspace Platform, desktop products only): In your project configuration, the option is on the Static Analysis tab on the Run Time Errors > Check Behavior node.

Command line and options file: Use the option -detect-pointer-escape. See Command-Line Information.

Why Use This Option

Use this option to enable detection of pointer escape.

Settings

On

The Illegally dereferenced pointer check performs an additional task, besides its usual specifications. When you dereference a pointer, the check also determines if you are accessing a variable outside its scope through the pointer. The check is:

  • Red, if all the variables that the pointer points to are accessed outside their scope.

    For instance, you dereference a pointer ptr in a function func that is called twice in your code. In both calls, when you perform the dereference *ptr, ptr is pointing to variables outside their scope. Therefore, the Illegally dereferenced pointer check is red.

  • Orange, if only some of the variables that the pointer points to are accessed outside their scope.

  • Green, if none of the variables that the pointer points to are accessed outside their scope, and other requirements of the check are also satisfied.

In the following code, if you enable this option, Polyspace® Code Prover™ produces a red Illegally dereferenced pointer check on *ptr. Otherwise, the Illegally dereferenced pointer check on *ptr is green.

void func2(int *ptr) {
    *ptr = 0; 
}

int* func1(void) {
    int ret = 0;
    return &ret ;
}
void main(void) {
    int* ptr = func1() ;
    func2(ptr) ;
}
The Result Details pane displays a message indicating that ret is accessed outside its scope.

Off (default)

When you dereference a pointer, the Illegally dereferenced pointer check does not check for whether you are accessing a variable outside its scope. The check is green even if the pointer dereference is outside the variable scope, as long as it satisfies these requirements:

  • The pointer is not NULL.

  • The pointer points within the memory buffer.

Tips

The detection of stack pointer deference outside scope does not apply to certain types of pointers. For specific limitations, see Limitations of Polyspace Verification.

Command-Line Information

Parameter: -detect-pointer-escape
Default: Off
Example (Code Prover): polyspace-code-prover -sources file_name -detect-pointer-escape
Example (Code Prover Server): polyspace-code-prover-server -sources file_name -detect-pointer-escape

Version History

Introduced in R2015a

See Also

Topics