diff --git a/man/manual.docbook b/man/manual.docbook
index a14ad4c00..0679697c1 100644
--- a/man/manual.docbook
+++ b/man/manual.docbook
@@ -5,7 +5,7 @@
Cppcheck 1.61 dev
- 2013-01-12
+ 2013-07-14
@@ -442,33 +442,57 @@ gui/test.cpp:16: error: Mismatching allocation and deallocation: k
- The following format specifiers are supported:
-
-
- callstack
- callstack - if available
-
-
- file
- filename
-
-
- id
- message id
-
-
- line
- line number
-
-
- message
- verbose message text
-
-
- severity
- severity
-
-
+ The following format specifiers are supported:
+
+
+
+ callstack
+
+
+ callstack - if available
+
+
+
+
+ file
+
+
+ filename
+
+
+
+
+ id
+
+
+ message id
+
+
+
+
+ line
+
+
+ line number
+
+
+
+
+ message
+
+
+ verbose message text
+
+
+
+
+ severity
+
+
+ severity
+
+
+
The escape sequences \b (backspace), \n (newline), \r (formfeed) and
\t (horizontal tab) are supported.
@@ -571,58 +595,261 @@ Checking test.c...
- Leaks
+ Rules
- Looking for memory leaks and resource leaks is a key feature of
- Cppcheck. Cppcheck can detect many common mistakes by default. But through
- some tweaking you can improve the checking.
+ You can define custom rules using regular expressions.
+
+ These rules can not perform sophisticated analysis of the code. But
+ they give you an easy way to check for various simple patterns in the
+ code.
+
+ To get started writing rules, see the related articles here:
+
+ http://sourceforge.net/projects/cppcheck/files/Articles/
+
+ The file format for rules is:
+
+ <?xml version="1.0"?>
+<rule>
+ <tokenlist>LIST</tokenlist>
+ <pattern>PATTERN</pattern>
+ <message>
+ <id>ID</id>
+ <severity>SEVERITY</severity>
+ <summary>SUMMARY</summary>
+ </message>
+</rule>
- User-defined allocation/deallocation functions
+ <tokenlist>
- Cppcheck understands standard allocation and deallocation
- functions. But it doesn't know what library functions do.
+ The <tokenlist> element is optional. With
+ this element you can control what tokens are checked. The
+ LIST can be either define,
+ raw, normal or
+ simple.
- Here is example code that might leak memory or resources:
+
+
+ define
- void foo(int x)
+
+ used to check #define preprocessor statements.
+
+
+
+
+ raw
+
+
+ used to check the preprocessor output.
+
+
+
+
+ normal
+
+
+ used to check the normal token list.
+ There are some simplifications.
+
+
+
+
+ simple
+
+
+ used to check the simple token list. All simplifications are
+ used. Most Cppcheck checks use the simple token list.
+
+
+
+
+ If there is no <tokenlist> element then
+ simple is used automatically.
+
+
+
+ <pattern>
+
+ The PATTERN is the
+ PCRE-compatible regular expression that will be
+ executed.
+
+
+
+ <id>
+
+ The ID specify the user-defined message id.
+
+
+
+ <severity>
+
+ The SEVERITY must be one of the
+ Cppcheck severities: information,
+ performance, portability,
+ style, warning, or
+ error.
+
+
+
+ <summary>
+
+ Optional. The summary for the message. If no summary is given, the
+ matching tokens is written.
+
+
+
+
+ Library configuration
+
+ Cppcheck has internal knowledge about how
+ standard C/C++ functions work. There is no internal knowledge about how
+ various libraries and environments work. Cppcheck can
+ however be told how libraries and environments work by using configuration
+ files.
+
+ The idea is that users will be able to download configuration files
+ for all popular libraries and environments here:
+
+ http://cppcheck.sourceforge.net/archive
+
+ Ideally, all you need to do is choose and download the configuration
+ files you need.
+
+ The archive is not complete however. If you can't find the
+ configuration file you need in the archive, you can wait - maybe somebody
+ else will write it and share it. Or you can write your own configuration
+ file (and then it's possible to share your configuration file with
+ others).
+
+ A minimal configuration file looks like this:
+
+ <?xml version="1.0"?>
+<def>
+</def>
+
+
+ Leaks
+
+ Allocation and deallocation is defined with
+ <memory> and
+ <resource>.
+
+ Here is example code:
+
+ void ok()
{
- void *f = CreateFred();
- if (x == 1)
- return;
- DestroyFred(f);
-}
-
- If you analyse that with Cppcheck it won't find any leaks:
-
- cppcheck fred1.c
-
- You can add some custom leaks checking by providing simple
- implementations for the allocation and deallocation functions. Write
- this in a separate file fred.def:
-
- void *CreateFred()
-{
- return malloc(100);
+ char *p = alloc_something();
+ free_something(p);
}
-void DestroyFred(void *p)
+void leak()
{
- free(p);
+ char *p = alloc_something();
}
- When Cppcheck see this it understands that CreateFred()
- will return allocated memory and that
- DestroyFred() will deallocate memory.
+ Cppcheck doesn't normally report any errors for that:
- Now, execute cppcheck this way:
+ # cppcheck test.c
+Checking test.c...
- cppcheck --include=fred.def fred1.c
+ Example configuration:
- The output from cppcheck is:
+ <?xml version="1.0"?>
+<def>
+ <memory>
+ <dealloc>free_something</dealloc>
+ <alloc>alloc_something</alloc>
+ </memory>
+</def>
- Checking fred1.c...
-[fred1.c:5]: (error) Memory leak: f
+ Output from Cppcheck:
+
+ # cppcheck --library=something.cfg test.c
+Checking test.c...
+[test.c:10]: (error) Memory leak: p
+
+ Another example code:
+
+ void f()
+{
+ char *p = alloc_something();
+ do_something(p);
+ *p = 0;
+}
+
+ If you want that the do_something function call
+ is ignored, use <ignore>:
+
+ <?xml version="1.0"?>
+<def>
+ <memory>
+ <dealloc>free_something</dealloc>
+ <alloc>alloc_something</alloc>
+ </memory>
+ <ignore>do_something</ignore>
+</def>
+
+ Running Cppcheck now:
+
+ # cppcheck --library=something.cfg test.c
+Checking test.c...
+[test.c:10]: (error) Memory leak: pIf the
+ do_something takes the allocated memory and
+ deallocates it later, then use <use>
+ instead:
+
+ <?xml version="1.0"?>
+<def>
+ <memory>
+ <dealloc>free_something</dealloc>
+ <alloc>alloc_something</alloc>
+ <use>do_something</use>
+ </memory>
+</def>Running Cppcheck now:
+
+ # cppcheck --library=something.cfg test.c
+Checking test.c...
+
+
+
+ no return
+
+ You can define if a function is "noreturn" or not. Example
+ code:
+
+ int f(int x)
+{
+ int a;
+ if (x == 3)
+ a = 1;
+ else
+ do_something();
+ return a; // a is uninitialized if do_something() is called and it returns
+}
+
+ The output is:
+
+ # cppcheck test.c
+Checking test.c...
+
+ To tell Cppcheck that do_something is not a
+ noreturn function, use such configuration:
+
+ <?xml version="1.0"?>
+<def>
+ <function name="do_something">
+ <noreturn>false</noreturn>
+ </function>
+</def>
+
+ Now Cppcheck will be able to detect the error:
+
+ cppcheck --library=something.cfg test.c
+Checking test.c...
+[test.c:8]: (error) Uninitialized variable: a