496 lines
14 KiB
XML
496 lines
14 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"/usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
|
|
<book>
|
|
<bookinfo>
|
|
<title>Cppcheck 1.40</title>
|
|
|
|
<date>2010-01-17</date>
|
|
</bookinfo>
|
|
|
|
<chapter>
|
|
<title>Introduction</title>
|
|
|
|
<para>Cppcheck is an analysis tool for C/C++ code. Unlike C/C++ compilers
|
|
and many other analysis tools, it doesn't detect syntax errors. Cppcheck
|
|
only detects the types of bugs that the compilers normally fail to detect.
|
|
The goal is no false positives.</para>
|
|
|
|
<para>Supported code and platforms:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>You can check non-standard code that includes various compiler
|
|
extensions, inline assembly code, etc.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Cppcheck should be compilable by any C++ compiler that handles
|
|
the latest C++ standard.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Cppcheck should work on any platform that has sufficient cpu and
|
|
memory.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Accuracy</para>
|
|
|
|
<para>Please understand that there are limits of Cppcheck. Cppcheck is
|
|
rarely wrong about reported errors. But there are many bugs that it
|
|
doesn't detect.</para>
|
|
|
|
<para>You will find more bugs in your software by testing your software
|
|
carefully, than by using Cppcheck. You will find more bugs in your
|
|
software by instrumenting your software, than by using Cppcheck. But
|
|
Cppcheck can still detect some of the bugs that you miss when testing and
|
|
instrumenting your software.</para>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Getting started</title>
|
|
|
|
<section>
|
|
<title>First test</title>
|
|
|
|
<para>Here is a simple code</para>
|
|
|
|
<programlisting>int main()
|
|
{
|
|
char a[10];
|
|
a[10] = 0;
|
|
return 0;
|
|
}</programlisting>
|
|
|
|
<para>If you save that into <filename>file1.c</filename> and
|
|
execute:</para>
|
|
|
|
<programlisting>cppcheck file1.c</programlisting>
|
|
|
|
<para>The output from cppcheck will then be:</para>
|
|
|
|
<programlisting>Checking file1.c...
|
|
[file1.c:4]: (error) Array index out of bounds</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Checking all files in a folder</title>
|
|
|
|
<para>Normally a program has many sourcefiles. And you want to check
|
|
them all. Cppcheck can check all sourcefiles in a directory:</para>
|
|
|
|
<programlisting>cppcheck path</programlisting>
|
|
|
|
<para>If "path" is a folder then cppcheck will check all sourcefiles in
|
|
this folder.</para>
|
|
|
|
<programlisting>Checking path/file1.cpp...
|
|
1/2 files checked 50% done
|
|
Checking path/file2.cpp...
|
|
2/2 files checked 100% done</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Possible errors</title>
|
|
|
|
<para>By default, an error is only reported when
|
|
<literal><literal>Cppcheck</literal></literal> is sure there is an
|
|
error. When <literal>--enable=possibleError</literal> is given issues
|
|
will also be reported when <literal>Cppcheck</literal> is unsure.</para>
|
|
|
|
<para>The <literal>--enable=possibleError</literal> flag is useful but
|
|
makes <literal>Cppcheck</literal> more unreliable, you will probably get
|
|
false positives.</para>
|
|
|
|
<para>Here is a simple code example:</para>
|
|
|
|
<programlisting>void f()
|
|
{
|
|
Fred *f = new Fred;
|
|
}</programlisting>
|
|
|
|
<para>Execute this command:</para>
|
|
|
|
<programlisting>cppcheck --enable=possibleError file1.cpp</programlisting>
|
|
|
|
<para>The output from Cppcheck:</para>
|
|
|
|
<programlisting>[file1.cpp:4]: (possible error) Memory leak: fred</programlisting>
|
|
|
|
<para>The "possible" means that the reported message may be wrong (if
|
|
Fred has automatic deallocation it is not a memory leak).</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stylistic issues</title>
|
|
|
|
<para>By default Cppcheck will only check for bugs. There are also a few
|
|
checks for stylistic issues.</para>
|
|
|
|
<para>Here is a simple code example:</para>
|
|
|
|
<programlisting>void f(int x)
|
|
{
|
|
int i;
|
|
if (x == 0)
|
|
{
|
|
i = 0;
|
|
}
|
|
}</programlisting>
|
|
|
|
<para>To enable stylistic checks, use the --style flag:</para>
|
|
|
|
<programlisting>cppcheck --enable=style file1.c</programlisting>
|
|
|
|
<para>The reported error is:</para>
|
|
|
|
<programlisting>[file3.c:3]: (style) The scope of the variable i can be limited</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Saving results in file</title>
|
|
|
|
<para>Many times you will want to save the results in a file. You can
|
|
use the normal shell redirection for piping error output to a
|
|
file.</para>
|
|
|
|
<programlisting>cppcheck file1.c 2> err.txt</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Unused functions</title>
|
|
|
|
<para>This check will try to find unused functions. It is best to use
|
|
this when the whole program is checked, so that all usages is seen by
|
|
cppcheck.</para>
|
|
|
|
<programlisting>cppcheck --enable=unusedFunctions path</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Enable all checks</title>
|
|
|
|
<para>To enable all checks your can use the
|
|
<literal>--enable=all</literal> flag:</para>
|
|
|
|
<programlisting>cppcheck --enable=all path</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Multithreaded checking</title>
|
|
|
|
<para>To use 4 threads to check the files in a folder:</para>
|
|
|
|
<programlisting>cppcheck -j 4 path</programlisting>
|
|
</section>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>XML output</title>
|
|
|
|
<para>Cppcheck can generate the output in XML format.</para>
|
|
|
|
<para>Use the --xml flag when you execute cppcheck:</para>
|
|
|
|
<programlisting>cppcheck --xml file1.cpp</programlisting>
|
|
|
|
<para>The xml format is:</para>
|
|
|
|
<programlisting><?xml version="1.0"?>
|
|
<results>
|
|
<error file="file1.cpp" line="123" id="someError"
|
|
severity="error" msg="some error text"/>
|
|
</results></programlisting>
|
|
|
|
<para>Attributes:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>file</term>
|
|
|
|
<listitem>
|
|
<para>filename. Both relative and absolute paths are possible</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>line</term>
|
|
|
|
<listitem>
|
|
<para>a number</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>id</term>
|
|
|
|
<listitem>
|
|
<para>id of error. These are always valid symbolnames.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>severity</term>
|
|
|
|
<listitem>
|
|
<para>one of: error / possible error / style / possible style</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>msg</term>
|
|
|
|
<listitem>
|
|
<para>the error message</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Reformatting the output</title>
|
|
|
|
<para>If you want to reformat the output so it looks different you can use
|
|
templates.</para>
|
|
|
|
<para>To get Visual Studio compatible output you can use "--template
|
|
vs":</para>
|
|
|
|
<programlisting>cppcheck --template vs gui/test.cpp</programlisting>
|
|
|
|
<para>This output will look like this:</para>
|
|
|
|
<programlisting>Checking gui/test.cpp...
|
|
gui/test.cpp(31): error: Memory leak: b
|
|
gui/test.cpp(16): error: Mismatching allocation and deallocation: k</programlisting>
|
|
|
|
<para>To get gcc compatible output you can use "--template gcc":</para>
|
|
|
|
<programlisting>cppcheck --template gcc gui/test.cpp</programlisting>
|
|
|
|
<para>The output will look like this:</para>
|
|
|
|
<programlisting>Checking gui/test.cpp...
|
|
gui/test.cpp:31: error: Memory leak: b
|
|
gui/test.cpp:16: error: Mismatching allocation and deallocation: k</programlisting>
|
|
|
|
<para>You can write your own pattern (for example a comma-separated
|
|
format):</para>
|
|
|
|
<programlisting>cppcheck --template "{file},{line},{severity},{id},{message}" gui/test.cpp</programlisting>
|
|
|
|
<para>The output will look like this:</para>
|
|
|
|
<programlisting>Checking gui/test.cpp...
|
|
gui/test.cpp,31,error,memleak,Memory leak: b
|
|
gui/test.cpp,16,error,mismatchAllocDealloc,Mismatching allocation and deallocation: k</programlisting>
|
|
|
|
<para></para>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Suppressions</title>
|
|
|
|
<para>If you want to filter out certain errors you can suppress these.
|
|
First you need to create a suppressions file. The format is:</para>
|
|
|
|
<programlisting>[error id]:[filename]
|
|
[error id]:[filename2]
|
|
[error id]</programlisting>
|
|
|
|
<para>The <literal>error id</literal> is the id that you want to suppress.
|
|
The easiest way to get it is to use the <literal>--xml</literal> command
|
|
line flag. Copy and paste the <literal>id</literal> string from the xml
|
|
output.</para>
|
|
|
|
<para>Here is an example:</para>
|
|
|
|
<programlisting>memleak:file1.cpp
|
|
exceptNew:file1.cpp
|
|
uninitvar</programlisting>
|
|
|
|
<para>You can then use the suppressions file:</para>
|
|
|
|
<programlisting>cppcheck --suppressions suppressions.txt src/</programlisting>
|
|
|
|
<para></para>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Leaks</title>
|
|
|
|
<para>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 both increase the capabilities and also reduce the
|
|
amount of false positives.</para>
|
|
|
|
<section>
|
|
<title>Automatic deallocation</title>
|
|
|
|
<para>A common cause of false positives is when there is automatic
|
|
deallocation. Here is an example:</para>
|
|
|
|
<programlisting>void Form1::foo()
|
|
{
|
|
QPushButton *pb = new QPushButton("OK", this);
|
|
}</programlisting>
|
|
|
|
<para>Cppcheck can't see where the deallocation is when you have such
|
|
code.</para>
|
|
|
|
<para>If you execute:</para>
|
|
|
|
<programlisting>cppcheck --enable=possibleError file1.cpp</programlisting>
|
|
|
|
<para>The result will be:</para>
|
|
|
|
<programlisting>[file1.cpp:4]: (possible error) Memory leak: pb</programlisting>
|
|
|
|
<para>The "possible" in the error message means that the message may be
|
|
a false positive.</para>
|
|
|
|
<para>To avoid such false positives, create a textfile and write the
|
|
names of the automaticly deallocated classes.</para>
|
|
|
|
<programlisting>QLabel
|
|
QPushButton</programlisting>
|
|
|
|
<para>Then execute cppcheck with the <literal>--auto-dealloc</literal>
|
|
option:</para>
|
|
|
|
<programlisting>cppcheck --auto-dealloc qt.lst --enable=possibleError file1.cpp</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Userdefined allocation/deallocation functions</title>
|
|
|
|
<para><literal>Cppcheck</literal> understands many common allocation and
|
|
deallocation functions. But not all.</para>
|
|
|
|
<para>Here is example code that might leak memory or resources:</para>
|
|
|
|
<para><programlisting>void foo(int x)
|
|
{
|
|
void *f = CreateFred();
|
|
if (x == 1)
|
|
return;
|
|
DestroyFred(f);
|
|
}</programlisting></para>
|
|
|
|
<para>If you analyse that with Cppcheck it won't find any leaks:</para>
|
|
|
|
<programlisting>cppcheck --enable=possibleError fred1.cpp</programlisting>
|
|
|
|
<para>You can add some custom leaks checking by providing simple
|
|
implementations for the allocation and deallocation functions. Write
|
|
this in a separate file:</para>
|
|
|
|
<programlisting>void *CreateFred()
|
|
{
|
|
return malloc(100);
|
|
}
|
|
|
|
void DestroyFred(void *p)
|
|
{
|
|
free(p);
|
|
}</programlisting>
|
|
|
|
<para>When Cppcheck see this it understands that CreateFred will return
|
|
allocated memory and that DestroyFred will deallocate memory.</para>
|
|
|
|
<para>Now, execute <literal>Cppcheck</literal> this way:</para>
|
|
|
|
<programlisting>cppcheck --append=fred.cpp fred1.cpp</programlisting>
|
|
|
|
<para>The output from cppcheck is:</para>
|
|
|
|
<programlisting>Checking fred1.cpp...
|
|
[fred1.cpp:5]: (error) Memory leak: f</programlisting>
|
|
</section>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Exception safety</title>
|
|
|
|
<para>Cppcheck has a few checks that ensure that you don't break the basic
|
|
guarantee of exception safety. It doesn't have any checks for the strong
|
|
guarantee yet.</para>
|
|
|
|
<para>Example:</para>
|
|
|
|
<programlisting>Fred::Fred() : a(new int[20]), b(new int[20])
|
|
{
|
|
}</programlisting>
|
|
|
|
<para>By default cppcheck will not detect any problems in that
|
|
code.</para>
|
|
|
|
<para>To enable the exception safety checking you can use
|
|
<literal>--enable</literal>:</para>
|
|
|
|
<programlisting>cppcheck --enable=exceptNew --enable=exceptRealloc fred.cpp</programlisting>
|
|
|
|
<para>The output will be:</para>
|
|
|
|
<programlisting>[fred.cpp:3]: (style) Upon exception there is memory leak: a</programlisting>
|
|
|
|
<para>If an exception occurs when <literal>b</literal> is allocated,
|
|
<literal>a</literal> will leak.</para>
|
|
|
|
<para>Here is another example:</para>
|
|
|
|
<programlisting>int *p;
|
|
|
|
int a(int sz)
|
|
{
|
|
delete [] p;
|
|
if (sz <= 0)
|
|
throw std::runtime_error("size <= 0");
|
|
p = new int[sz];
|
|
}</programlisting>
|
|
|
|
<para>Check that with Cppcheck:</para>
|
|
|
|
<programlisting>cppcheck --enable=exceptNew --enable=exceptRealloc except2.cpp</programlisting>
|
|
|
|
<para>The output from Cppcheck is:</para>
|
|
|
|
<programlisting>[except2.cpp:7]: (error) Throwing exception in invalid state, p points at deallocated memory</programlisting>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>html report</title>
|
|
|
|
<para>You can convert the xml output from cppcheck into a html report.
|
|
You'll need python and the pygments module
|
|
(<uri>http://pygments.org/</uri>) for this to work. In the Cppcheck source
|
|
tree there is a folder "htmlreport" that contains a script that transforms
|
|
a Cppcheck xml file into html output.</para>
|
|
|
|
<para>This command generates the help screen:</para>
|
|
|
|
<para><programlisting>htmlreport/cppcheck-htmlreport -h</programlisting></para>
|
|
|
|
<para>The output screen says:</para>
|
|
|
|
<para><programlisting>Usage: cppcheck-htmlreport [options]
|
|
|
|
Options:
|
|
-h, --help show this help message and exit
|
|
--file=FILE The cppcheck xml output file to read defects from.
|
|
Default is reading from stdin.
|
|
--report-dir=REPORT_DIR
|
|
The directory where the html report content is written.
|
|
--source-dir=SOURCE_DIR
|
|
Base directory where source code files can be found.</programlisting></para>
|
|
|
|
<para>An example usage:</para>
|
|
|
|
<programlisting>./cppcheck gui/test.cpp --xml 2> err.xml
|
|
htmlreport/cppcheck-htmlreport --file=err.xml --report-dir=test1 --source-dir=.</programlisting>
|
|
|
|
<para></para>
|
|
</chapter>
|
|
</book>
|