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
|
./cppcheck gui/test.cpp --xml 2> err.xml
|
||||||
htmlreport/cppcheck-htmlreport --file=err.xml --report-dir=test1 --source-dir=.
|
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