From 6a0fb05e6894af1430a092a13d8bce3a3c855630 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Marjam=C3=A4ki?= Date: Thu, 21 Apr 2022 21:34:07 +0200 Subject: [PATCH] manual: removed chapter about bug hunting --- man/manual.md | 177 -------------------------------------------------- 1 file changed, 177 deletions(-) diff --git a/man/manual.md b/man/manual.md index 1c7ce36e6..1a6ad2c1b 100644 --- a/man/manual.md +++ b/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.