walkero
/
cppcheck
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Manual: Refactorized chapter about libraries 

- Reordered sections
- Describe more features
This commit is contained in:
PKEuS 2016-07-27 15:28:35 +02:00
parent 13c11b8c1d
commit e2a04c508c
1 changed files with 227 additions and 202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

159
man/manual.docbook
View File

@ -5,7 +5,7 @@
<bookinfo> <bookinfo>
<title>Cppcheck 1.75 dev</title> <title>Cppcheck 1.75 dev</title>
<date>2015-09-09</date> <date>2016-07-27</date>
</bookinfo> </bookinfo>
<chapter> <chapter>
@ -314,7 +314,7 @@ cppcheck --enable=all</programlisting>
<para>You can use -D to change this. When you use -D, cppcheck will by <para>You can use -D to change this. When you use -D, cppcheck will by
default only check the given configuration and nothing else. This is how default only check the given configuration and nothing else. This is how
compilers work. But you can use <literal>--force</literal> or compilers work. But you can use <literal>--force</literal> or
<literal><literal>--max-configs</literal></literal> to override the number <literal>--max-configs</literal> to override the number
of configurations.</para> of configurations.</para>
<programlisting># check all configurations <programlisting># check all configurations
@ -662,14 +662,17 @@ Checking test.c...
<chapter> <chapter>
<title>Library configuration</title> <title>Library configuration</title>
<para>When external libraries are used, such as windows/posix/gtk/qt/etc, <para>When external libraries are used, such as WinAPI, POSIX, gtk, Qt, etc,
<literal>Cppcheck</literal> doesn't know how the external functions <literal>Cppcheck</literal> doesn't know how the external functions
behave. <literal>Cppcheck</literal> then fails to detect various problems behave. <literal>Cppcheck</literal> then fails to detect various problems
such as leaks, buffer overflows, possible null pointer dereferences, etc. such as leaks, buffer overflows, possible null pointer dereferences, etc.
But this can be fixed with configuration files.</para> But this can be fixed with configuration files.</para>
<para>If you create a configuration file for a popular library, we would <para>Cppcheck already contains configurations for several libraries. They
appreciate if you upload it to us.</para> can be loaded as described below. Note that the configuration for the standard
libraries of C and C++, <literal>std.cfg</literal>, is always loaded by
cppcheck. If you create or update a configuration file for a
popular library, we would appreciate if you upload it to us.</para>
<section> <section>
<title>Using your own custom .cfg file</title> <title>Using your own custom .cfg file</title>
@ -692,7 +695,9 @@ Checking test.c...
<section> <section>
<title>Memory/resource leaks</title> <title>Memory/resource leaks</title>
<para>Cppcheck has configurable checking for leaks.</para> <para>Cppcheck has configurable checking for leaks, e.g. you can specify
which functions allocate and free memory or resources and which functions
do not affect the allocation at all.</para>
<section> <section>
<title>alloc and dealloc</title> <title>alloc and dealloc</title>
@ -705,14 +710,14 @@ Checking test.c...
}</programlisting></para> }</programlisting></para>
<para>The code example above has a resource leak - <para>The code example above has a resource leak -
<literal>CreatePen()</literal> is a windows function that creates a <literal>CreatePen()</literal> is a WinAPI function that creates a
pen. However Cppcheck doesn't assume that return values from functions pen. However, Cppcheck doesn't assume that return values from functions
must be freed. There is no error message:</para> must be freed. There is no error message:</para>
<programlisting># cppcheck pen1.c <programlisting># cppcheck pen1.c
Checking pen1.c...</programlisting> Checking pen1.c...</programlisting>
<para>If you provide a windows configuration file then <para>If you provide a configuration file then
<literal>Cppcheck</literal> detects the bug:</para> <literal>Cppcheck</literal> detects the bug:</para>
<programlisting># cppcheck --library=windows.cfg pen1.c <programlisting># cppcheck --library=windows.cfg pen1.c
@ -730,6 +735,12 @@ Checking pen1.c...
&lt;/def&gt;</programlisting> &lt;/def&gt;</programlisting>
</section> </section>
<para>The allocation and deallocation functions are organized in groups.
Each group is defined in a <literal>&lt;resource&gt;</literal> or
<literal>&lt;memory&gt;</literal> tag and is identified by its <literal>&lt;dealloc&gt;</literal>
functions. This means, groups with overlapping <literal>&lt;dealloc&gt;</literal>
tags are merged.</para>
<section> <section>
<title>leak-ignore and use</title> <title>leak-ignore and use</title>
@ -747,14 +758,14 @@ Checking pen1.c...
takes care of the memory so there is no memory leak.</para> takes care of the memory so there is no memory leak.</para>
<para>To specify that <literal>dostuff</literal> doesn't take care of <para>To specify that <literal>dostuff</literal> doesn't take care of
the memory in any way, use <literal>leak-ignore</literal>:</para> the memory in any way, use <literal>leak-ignore</literal> in the
<literal>&lt;function&gt;</literal> tag (see next section):</para>
<programlisting>&lt;?xml version="1.0"?&gt; <programlisting>&lt;?xml version="1.0"?&gt;
&lt;def&gt; &lt;def&gt;
&lt;function name="dostuff"&gt; &lt;function name="dostuff"&gt;
&lt;leak-ignore/&gt; &lt;leak-ignore/&gt;
&lt;arg nr="1"/&gt; &lt;arg nr="1"/&gt;
&lt;arg nr="2"/&gt;
&lt;/function&gt; &lt;/function&gt;
&lt;/def&gt;</programlisting> &lt;/def&gt;</programlisting>
@ -764,13 +775,12 @@ Checking pen1.c...
<programlisting>&lt;?xml version="1.0"?&gt; <programlisting>&lt;?xml version="1.0"?&gt;
&lt;def&gt; &lt;def&gt;
&lt;memory&gt; &lt;memory&gt;
&lt;alloc&gt;malloc&lt;/alloc&gt;
&lt;dealloc&gt;free&lt;/dealloc&gt; &lt;dealloc&gt;free&lt;/dealloc&gt;
&lt;use&gt;dostuff&lt;/use&gt; &lt;use&gt;dostuff&lt;/use&gt;
&lt;/memory&gt; &lt;/memory&gt;
&lt;/def&gt;</programlisting> &lt;/def&gt;</programlisting>
<para>The <literal><literal>&lt;use&gt;</literal></literal> <para>The <literal>&lt;use&gt;</literal>
configuration has no logical purpose. You will get the same warnings configuration has no logical purpose. You will get the same warnings
without it. Use it to silence <literal>--check-library</literal> without it. Use it to silence <literal>--check-library</literal>
information messages.</para> information messages.</para>
@ -778,7 +788,29 @@ Checking pen1.c...
</section> </section>
<section> <section>
<title>Function argument: Uninitialized memory</title> <title>Function behaviour</title>
<para>To specify the behaviour of functions and how they should be used,
<literal>&lt;function&gt;</literal> tags can be used. Functions are identified
by their name, specified in the <literal>name</literal> attribute and their
number of arguments. The name is a comma-separated list of function names.
For functions in namespaces or classes, just provide their fully qualified
name. For example: <literal>&lt;function name="memcpy,std::memcpy"&gt;</literal>.
</para>
<section>
<title>Function arguments</title>
<para>The arguments a function takes can be specified by <literal>&lt;arg&gt;</literal>
tags. Each of them takes the number of the argument (starting from 1) in the
<literal>nr</literal> attribute, or <literal>nr="any"</literal> for variadic arguments.
Optional arguments can be specified by providing a default value:
<literal>default="value"</literal>. Specifying <literal>-1</literal> as the argument
number is going to apply a check to all arguments of that function. The specifications
for individual arguments override this setting.</para>
<section>
<title>Uninitialized memory</title>
<para>Here is an example program:</para> <para>Here is an example program:</para>
@ -790,14 +822,14 @@ Checking pen1.c...
}</programlisting> }</programlisting>
<para>The bug here is that buffer2 is uninitialized. The second argument <para>The bug here is that buffer2 is uninitialized. The second argument
for CopyMemory needs to be initialized. However for CopyMemory needs to be initialized. However,
<literal>Cppcheck</literal> assumes that it is fine to pass <literal>Cppcheck</literal> assumes that it is fine to pass
uninitialized variables to functions:</para> uninitialized variables to functions:</para>
<programlisting># cppcheck uninit.c <programlisting># cppcheck uninit.c
Checking uninit.c...</programlisting> Checking uninit.c...</programlisting>
<para>If you provide a windows configuration file then Cppcheck detects <para>If you provide a configuration file then Cppcheck detects
the bug:</para> the bug:</para>
<programlisting># cppcheck --library=windows.cfg uninit.c <programlisting># cppcheck --library=windows.cfg uninit.c
@ -819,7 +851,7 @@ Checking uninit.c...
</section> </section>
<section> <section>
<title>Function Argument: Null pointers</title> <title>Null pointers</title>
<para>Cppcheck assumes it's ok to pass NULL pointers to functions. Here <para>Cppcheck assumes it's ok to pass NULL pointers to functions. Here
is an example program:</para> is an example program:</para>
@ -858,7 +890,7 @@ Checking null.c...
</section> </section>
<section> <section>
<title>Function Argument: Format string</title> <title>Format string</title>
<para>You can define that a function takes a format string. <para>You can define that a function takes a format string.
Example:</para> Example:</para>
@ -871,7 +903,7 @@ Checking null.c...
<para>No error is reported for that:</para> <para>No error is reported for that:</para>
<programlisting># cppcheck formatstring.c <programlisting># cppcheck formatstring.c
Checking formatstring.c...</programlisting> Checking formatstring.c...</programlisting>
<para>A configuration file can be created that says that the string is a <para>A configuration file can be created that says that the string is a
format string. For instance:</para> format string. For instance:</para>
@ -904,7 +936,7 @@ Checking formatstring.c...
</section> </section>
<section> <section>
<title>Function Argument: Value range</title> <title>Value range</title>
<para>The valid values can be defined. Imagine:</para> <para>The valid values can be defined. Imagine:</para>
@ -944,7 +976,7 @@ Checking range.c...
</section> </section>
<section> <section>
<title>Function Argument: minsize</title> <title>minsize</title>
<para>Some function arguments take a buffer. With minsize you can <para>Some function arguments take a buffer. With minsize you can
configure the min size of the buffer (in bytes, not elements). configure the min size of the buffer (in bytes, not elements).
@ -1023,7 +1055,7 @@ Checking minsize.c...
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</section> </section>
</section>
<section> <section>
<title>noreturn</title> <title>noreturn</title>
@ -1107,6 +1139,44 @@ Checking useretval.c...
&lt;/def&gt;</programlisting> &lt;/def&gt;</programlisting>
</section> </section>
<section>
<title>Example configuration for strcpy()</title>
<para>The proper configuration for the standard strcpy() function would
be:</para>
<programlisting> &lt;function name="strcpy"&gt;
&lt;leak-ignore/&gt;
&lt;noreturn&gt;false&lt;/noreturn&gt;
&lt;arg nr="1"&gt;
&lt;not-null/&gt;
&lt;/arg&gt;
&lt;arg nr="2"&gt;
&lt;not-null/&gt;
&lt;not-uninit/&gt;
&lt;strz/&gt;
&lt;/arg&gt;
&lt;/function&gt;</programlisting>
<para>The <literal>&lt;leak-ignore/&gt;</literal> tells Cppcheck to
ignore this function call in the leaks checking. Passing allocated
memory to this function won't mean it will be deallocated.</para>
<para>The <literal>&lt;noreturn&gt;</literal> tells Cppcheck if this
function returns or not.</para>
<para>The first argument that the function takes is a pointer. It must
not be a null pointer, therefore <literal>&lt;not-null&gt;</literal> is
used.</para>
<para>The second argument the function takes is a pointer. It must not
be null. And it must point at initialized data. Using
<literal>&lt;not-null&gt;</literal> and
<literal>&lt;not-uninit&gt;</literal> is correct. Moreover it must point
at a zero-terminated string so &lt;strz&gt; is also used.</para>
</section>
</section>
<section> <section>
<title>define</title> <title>define</title>
@ -1190,51 +1260,6 @@ Checking unusedvar.cpp...
&lt;/container&gt; &lt;/container&gt;
&lt;/def&gt;</programlisting> &lt;/def&gt;</programlisting>
</section> </section>
<section>
<title>Example configuration for strcpy()</title>
<para>The proper configuration for the standard strcpy() function would
be:</para>
<programlisting> &lt;function name="strcpy"&gt;
&lt;leak-ignore/&gt;
&lt;noreturn&gt;false&lt;/noreturn&gt;
&lt;arg nr="1"&gt;
&lt;not-null/&gt;
&lt;/arg&gt;
&lt;arg nr="2"&gt;
&lt;not-null/&gt;
&lt;not-uninit/&gt;
&lt;strz/&gt;
&lt;/arg&gt;
&lt;/function&gt;</programlisting>
<para>The <literal>&lt;leak-ignore/&gt;</literal> tells Cppcheck to
ignore this function call in the leaks checking. Passing allocated
memory to this function won't mean it will be deallocated.</para>
<para>The <literal>&lt;noreturn&gt;</literal> tells Cppcheck if this
function returns or not.</para>
<para>The first argument that the function takes is a pointer. It must
not be a null pointer, therefore <literal>&lt;not-null&gt;</literal> is
used.</para>
<para>The second argument the function takes is a pointer. It must not
be null. And it must point at initialized data. Using
<literal>&lt;not-null&gt;</literal> and
<literal>&lt;not-uninit&gt;</literal> is correct. Moreover it must point
at a zero-terminated string so &lt;strz&gt; is also used.</para>
</section>
<section>
<title>Specifications for all arguments</title>
<para>Specifying <literal>-1</literal> as the argument number is going
to apply a check to all arguments of that function. The specifications
for individual arguments override this setting.</para>
</section>
</chapter> </chapter>
<chapter> <chapter>