...

Using Flow Analysis

Anchor
Using BugDetective Static Analysis Using BugDetective Static Analysis

...

1. Identify or create a Test Configuration with your preferred Flow Analysis standard analysis settings.
   • For a description of preconfigured Test Configurations, see Built-in Test Configurations.
   • For general procedures related to configuring and sharing Test Configurations, see the Configuring Test Configurations and Rules for Policies. For details on C++test-specific Flow Analysis options, see Static Tab Settings : - Defining How Static Analysis is Performed.
2. Start the test using the preferred Test Configuration.
   • For details on testing from the GUI, see Testing from the GUI.
   • For details on testing from the command line, see Testing from the Command Line Interface.
3. Review and respond to the results.
   • For details, see Reviewing Flow Analysis Static Analysis Results.
4. (Optional) Fine-tune Flow Analysis settings as needed.
   • For details, see Customizing Flow Analysis Static Analysis.

...

• Never put independent projects in the same analysis scope. Different projects can have different definitions of a type with the same fully-qualified name or a function with specific signature. If there is a call to a function that is defined multiple times, Flow Analysis may be unable to trace the call into the correct function.
• If you want to analyze compilation unit A and it depends on compilation unit B, then it is typically recommended to include both A and B in the analysis scope so that Flow Analysis can take into account any necessary information from unit B when analyzing A. The same pattern applies to dependent projects. Of course, the more files that are included in the analysis, the longer the analysis will take. Flow Analysis does allow analysis on just a single file. However, such limited analysis is likely to be less precise.

Anchor
Bugdetective Bugdetective

Reviewing Flow Analysis

...

Results

This topic covers how to analyze the bugs reported by Flow Analysis.

...

...

The types of bugs that Flow Analysis detects is determined by which rules you have enabled in the Test Configuration—in much the same way as you configure static code analysis with coding standards. The basic static analysis settings (maximum tasks reported per rule, etc.—see Static Tab Settings : - Defining How Static Analysis is Performed for for details) apply to both static code analysis and Flow Analysis analysis.

...

1. Click Add.
2. Type the name of the resource type.
3. Press <Enter>. A new entry will be added to the resource table.
4. If appropriate/desired, disable the Do not report violations at application termination option.
5. Complete the entry by clicking the Edit button, then completing the dialog that allows you to define how the given resource is allocated/deallocated. Details about completing this dialog are provided below.

Parameterization Common to Both Allocators and Deallocators

1. resource allocators, resource closers , resource checkers, and safe functions. Any single row in either panel's table corresponds to exactly one

...

1. function and contains enough information to unambiguously identify a function  (or—if wildcards are used—a family of  functions) and depict how it allocates/frees a resource.

...

1. Details about completing this dialog are provided below.

Configuring Resource Allocators

The Resource allocators table can be completed with the descriptors of functions that can produce a resource. The table has the following columns:

The column labeled Enabled should be used to include/exclude a function from consideration during the analysis.

...

• Enabled: specifies whether the allocator should be considered during analysis.

• Fully-qualified type name or namespace (wildcard)

...

• : the fully-qualified name of the type or namespace where the function is declared. Use '*' if you want to describe

...

• a function declared in any type

...

• or namespace, or a global function declared outside of any type.
• Function

...

• name (wildcard)

...

• : the name of the allocating

...

• function. '*' can be used to denote any number of any symbols.

...

• Resource parameters: specifies that the function allocates a resource in one or more of its parameters. In this case, either specify a 1-based number of the parameter that is allocated by the function, or use '*' to denote that all of the parameters are allocated.
• + definitions in subclasses: a check box that indicates whether the definitions (of functions with the given name) in subclasses should be considered allocators

...

• as well. Note that this applies to both instance and static functions.

Allocators

The 'Resource allocators' panel can be completed with the descriptors of functions that can produce a resource. These can be represented by functions that are able to:

• Return an allocated resource. In this case, check the checkbox in the Returns a resource object column.
• Allocate a resource in the object on which the function is called. In this case, check the check-box in the "this" object is a resource column.
• Allocate a resource in one or more of its parameters. In this case, either specify a 1-based number of the parameter that is allocated by the function, or use '*' to denote that all of the parameters are allocated.

• "this" object is a resource: a check box that indicates that the function allocates a resource in the object on which the function is called.
• Returns a resource object: a check box that indicates that the function returns an allocated resource.
• Return value constraint on error: specifies a return value constraint in case of allocation fail-ure if a resource allocator returns an integral value. Enter the condition in the following format: <comparison operator><integer value>. For example, if the function returns non-zero value on failure, enter "!=0" (without quotes) into the field. If return code on error is -1, type "==-1" there. In addition to "!=" and "==", you can use the following operators for specifying error conditions: ">", ">=", "<", and "<=".

It is common that allocation functions return an error code It is common that allocation functions return an error code to indicate allocation failure. When an allocation function returns a pointer to a resource, a NULL pointer normally indicates an allocation failure. When Flow Analysis is looking for resource leaks, it needs to understand if allocation succeeded or failed; this helps it report only missing calls to deallocation functions on paths where allocation actually occurred. In cases where a resource allocator function returns a pointer to a resource, Flow Analysis assumes that the resource is successfully allocated if the pointer is not NULL.

If a resource allocator returns an integral value, you can specify a return value constraint in case of allocation failure by entering the condition into the Return value constraint on error field. The condition must be specified according to the following format: <comparison operator><integer value>. For example, if the function returns non-zero value on failure, enter "!=0" (without quotes) into the field. If return code on error  is -1, type "==-1" there. In addition to "!=" and "==", you can use the following operators for specifying error conditions: ">", ">=", "<", and "<=".

Deallocators

The second panel should be completed with functions that close resources. Two cases where a function closes a resource are possible:

Configuring Resource Closers

The Resource closers table can be completed with the descriptors of functions that can close a resource. The table has the following columns:

• Enabled: specifies whether the closer should be considered during analysis.
• Fully-qualified type name or namespace (wildcard): the fully-qualified name of the type or namespace where the function is declared. Use '*' if you want to describe a function declared in any type or namespace, or a global function declared outside of any type.
• Function name (wildcard): the name of the closing function. '*' can be used to denote any number of any symbols.
• + definitions in subclasses: a check box that indicates whether the definitions (of functions with the given name) in subclasses should be considered closers as well. Note that this applies to both instance and static functions.
• "this" object is a resource: a check box that indicates that a resource in the object on which the function is called is closed.
• Resource parameters: specifies that a resource in one or more of its parameters is closed. In this case, either specify a 1-based number of the parameter that is closed by the function, or use '*' to denote that all of the parameters are allocated.

Configuring Resource Checkers

The Resource checkers table can be completed with the descriptors of functions that can check if the resource is open. The table has the following columns:

• Enabled: specifies whether the checker should be considered during analysis.
• Fully-qualified type name or namespace (wildcard): the fully-qualified name of the type or namespace where the function is declared. Use '*' if you want to describe a function declared in any type or namespace, or a global function declared outside of any type.
• Function name (wildcard): the name of the checking function. '*' can be used to denote any number of any symbols.
• + definitions in subclasses: a check box that indicates whether the definitions (of functions with the given name) in subclasses should be considered checkers as well. Note that this applies to both instance and static functions.
• 'this' object is a resource: a check box that indicates that the function checks a resource in the object on which the function is called.
• Resources parameters: specifies that the function checks a resource in one or more of its parameters. In this case, either specify a 1-based number of the parameter that is checked by the function, or use '*' to denote that all of the parameters are checked.
• Returned value when resource is open: specifies the return value of checking the function when the resource is open. Acceptable values are true or false.

Configuring Safe Functions

The Safe functions table can be completed with the descriptors of functions that can be safely called on a closed resource –  without triggering the BD-RES-FREE rule. The table has the following columns:

• Enabled: specifies whether the safe function should be considered during analysis.
• Fully-qualified type name or namespace (wildcard): the fully-qualified name of the type or namespace where the function is declared. Use '*' if you want to describe a function declared in any type or namespace, or a global function declared outside of any type.
• Function name (wildcard): the name of the safe function. '*' can be used to denote any number of any symbols.
• + definitions in subclasses: a check box that indicates whether the definitions (of functions with the given name) in subclasses should be considered safe as well. Note that this applies to both instance and static functions
• A resource in the object on which the function is called is closed. In this case, check the check-box in the "this" object is a resource column.
• A resource in one or more of its parameters is closed. In this case, either specify a 1-based number of the parameter that is closed by the function, or use '*' to denote that all  of the parameters are allocated.

Resources with Built-In Support

...