manual: removed chapter about bug hunting
This commit is contained in:
Daniel Marjamäki
parent
5e6cc1053a
commit
6a0fb05e68
177
man/manual.md
177
man/manual.md
|
|
@ -961,180 +961,3 @@ Example usage:
|
|||
./cppcheck gui/test.cpp --xml 2> err.xml
|
||||
htmlreport/cppcheck-htmlreport --file=err.xml --report-dir=test1 --source-dir=.
|
||||
|
||||
# Bug hunting
|
||||
|
||||
If you want to detect most bugs and can accept false alarms, then Cppcheck has analysis for that.
|
||||
|
||||
This analysis is soundy; it should diagnose most bugs reported in CVEs and from dynamic analysis.
|
||||
|
||||
You have to expect false alarms. However Cppcheck tries to limit false alarms.
|
||||
The purpose of the data flow analysis is to limit false alarms.
|
||||
|
||||
Some possible use cases;
|
||||
|
||||
- you are writing new code and want to ensure it is safe.
|
||||
- you are reviewing code and want to get hints about possible UB.
|
||||
- you need extra help troubleshooting a weird bug.
|
||||
- you want to check if a release candidate is safe.
|
||||
|
||||
The intention is that this will be used primarily in the GUI.
|
||||
|
||||
## Activate this analysis
|
||||
|
||||
On the command line you can use `--bug-hunting`. In the GUI go to the project dialog.
|
||||
In the `Analysis` tab there is a check box for `Bug hunting`.
|
||||
|
||||
## Contracts
|
||||
|
||||
To handle false alarms and improve the analysis you are encouraged to use contracts.
|
||||
|
||||
To provide contracts, you can either annotate your code or configure the contracts in the GUI.
|
||||
|
||||
There exists various annotations for C and C++ code. gcc has attributes, there
|
||||
are SAL annotations, and then there are standard C++ annotations. It is our
|
||||
goal to handle various types of annotations, if you can reuse those annotations
|
||||
in Cppcheck analysis that will be an extra benefit.
|
||||
|
||||
### Function contracts
|
||||
|
||||
Here is an example code:
|
||||
|
||||
int foo(int x)
|
||||
{
|
||||
return 100 / x;
|
||||
}
|
||||
|
||||
The bug hunting analysis will warn about a division by zero. Right now, it
|
||||
can't be proven that x can't be 0 here. A function contract can be used to
|
||||
tell Cppcheck what input "foo(x)" expects.
|
||||
|
||||
#### Annotation
|
||||
|
||||
You can use "C++ function contracts" syntax both in C and C++.
|
||||
|
||||
For C++ code you can write:
|
||||
|
||||
int foo(int x)
|
||||
[[expects: x > 0]]
|
||||
{
|
||||
return 100 / x; // No division by zero
|
||||
}
|
||||
|
||||
void bar()
|
||||
{
|
||||
foo(-10); // Warning: Contract is violated!
|
||||
}
|
||||
|
||||
For C code you can write (works in C++ too):
|
||||
|
||||
#ifdef __cppcheck__
|
||||
#define Expects(EXPR) [[expects: EXPR]]
|
||||
#else
|
||||
#define Expects(EXPR)
|
||||
#endif
|
||||
|
||||
int foo(int x)
|
||||
Expects(x > 0)
|
||||
{
|
||||
return 100 / x;
|
||||
}
|
||||
|
||||
void bar()
|
||||
{
|
||||
foo(-10); // Warning: Contract is violated!
|
||||
}
|
||||
|
||||
|
||||
#### Configuration in gui
|
||||
|
||||
You can configure contracts in the GUI.
|
||||
|
||||
Example code:
|
||||
|
||||
int foo(int x)
|
||||
{
|
||||
return 100 / x;
|
||||
}
|
||||
|
||||
If you run bug hunting analysis on this code, then because Cppcheck can't prove
|
||||
that x can't be 0, you will get a warning about division by zero.
|
||||
|
||||
Either:
|
||||
|
||||
- Right click on that warning and select "Edit contract..".
|
||||
- Open the "Functions" tab at the bottom and lookup the "foo(x)" function. Then
|
||||
double click on that.
|
||||
|
||||
A dialog box is shown where you can configure the contract for function "foo(x)".
|
||||
A textbox allows you to edit the "Expects" expression.
|
||||
|
||||
Enter the expression "x > 0" in the dialog box and click OK.
|
||||
|
||||
Now if you run analysis the division by zero warning will be gone. As for
|
||||
annotations, if the contract is violated somewhere then you will get a warning.
|
||||
|
||||
|
||||
|
||||
### Variable contracts
|
||||
|
||||
Here is an example code:
|
||||
|
||||
int x;
|
||||
|
||||
int foo()
|
||||
{
|
||||
return 100 / x;
|
||||
}
|
||||
|
||||
The bug hunting analysis will warn about a division by zero. It can't be proven
|
||||
that x can't be 0.
|
||||
|
||||
A variable contract specify the allowed values for a variable. Cppcheck use variable
|
||||
contracts both when a variable is read and written:
|
||||
- When a variable is read, Cppcheck will assume that the contract is met. This
|
||||
means you can avoid false positives for impossible variable values.
|
||||
- When a variable is written, Cppcheck will ensure that its contract is not
|
||||
violated. If it can't be determined that the contract is met you will get a
|
||||
warning.
|
||||
|
||||
#### Annotation
|
||||
|
||||
You can use Cppcheck attributes `__cppcheck_low__(value)` and
|
||||
`__cppcheck_high__(value)` to configure min and max values for variables
|
||||
and types.
|
||||
|
||||
Example code:
|
||||
|
||||
__cppcheck_low__(1) int x;
|
||||
|
||||
int foo()
|
||||
{
|
||||
return 100 / x; // No division by zero
|
||||
}
|
||||
|
||||
Tip: You can create an integer type with a limited value range. For instance
|
||||
here is an unsigned integer type that can only have the values 0-100:
|
||||
|
||||
typedef __cppcheck_high__(100) unsigned int percent_t;
|
||||
percent_t x;
|
||||
x = 110; // <- Cppcheck will warn about this assignment
|
||||
|
||||
|
||||
#### GUI
|
||||
|
||||
To configure variable contracts in the GUI, open the "Variables" tab at the
|
||||
bottom.
|
||||
|
||||
Lookup the variable you want to configure and double click on that.
|
||||
|
||||
A dialog box is shown for the variable, where you can configure the min and
|
||||
max values.
|
||||
|
||||
|
||||
## Incomplete analysis
|
||||
|
||||
The data flow analysis can analyze simple functions completely but complex functions are not analyzed completely (yet).
|
||||
The data flow analysis will be continuously improved in the future but it will never be perfect.
|
||||
|
||||
It is likely that you will get false alarms caused by incomplete data flow analysis. Unfortunately it is unlikely that
|
||||
such false alarms can be fixed by contracts.
|
||||
|
|
|
|||
Loading…
Reference in New Issue