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>
<title>Cppcheck 1.75 dev</title>
<date>2015-09-09</date>
<date>2016-07-27</date>
</bookinfo>
<chapter>
@ -314,7 +314,7 @@ cppcheck --enable=all</programlisting>
<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
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>
<programlisting># check all configurations
@ -662,14 +662,17 @@ Checking test.c...
<chapter>
<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
behave. <literal>Cppcheck</literal> then fails to detect various problems
such as leaks, buffer overflows, possible null pointer dereferences, etc.
But this can be fixed with configuration files.</para>
<para>If you create a configuration file for a popular library, we would
appreciate if you upload it to us.</para>
<para>Cppcheck already contains configurations for several libraries. They
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>
<title>Using your own custom .cfg file</title>
@ -692,7 +695,9 @@ Checking test.c...
<section>
<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>
<title>alloc and dealloc</title>
@ -705,14 +710,14 @@ Checking test.c...
}</programlisting></para>
<para>The code example above has a resource leak -
<literal>CreatePen()</literal> is a windows function that creates a
pen. However Cppcheck doesn't assume that return values from functions
<literal>CreatePen()</literal> is a WinAPI function that creates a
pen. However, Cppcheck doesn't assume that return values from functions
must be freed. There is no error message:</para>
<programlisting># cppcheck pen1.c
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>
<programlisting># cppcheck --library=windows.cfg pen1.c
@ -730,6 +735,12 @@ Checking pen1.c...
&lt;/def&gt;</programlisting>
</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>
<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>
<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;
&lt;def&gt;
&lt;function name="dostuff"&gt;
&lt;leak-ignore/&gt;
&lt;arg nr="1"/&gt;
&lt;arg nr="2"/&gt;
&lt;/function&gt;
&lt;/def&gt;</programlisting>
@ -764,13 +775,12 @@ Checking pen1.c...
<programlisting>&lt;?xml version="1.0"?&gt;
&lt;def&gt;
&lt;memory&gt;
&lt;alloc&gt;malloc&lt;/alloc&gt;
&lt;dealloc&gt;free&lt;/dealloc&gt;
&lt;use&gt;dostuff&lt;/use&gt;
&lt;/memory&gt;
&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
without it. Use it to silence <literal>--check-library</literal>
information messages.</para>
@ -778,7 +788,29 @@ Checking pen1.c...
</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>
@ -790,14 +822,14 @@ Checking pen1.c...
}</programlisting>
<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
uninitialized variables to functions:</para>
<programlisting># cppcheck uninit.c
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>
<programlisting># cppcheck --library=windows.cfg uninit.c
@ -819,7 +851,7 @@ Checking uninit.c...
</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
is an example program:</para>
@ -858,7 +890,7 @@ Checking null.c...
</section>
<section>
<title>Function Argument: Format string</title>
<title>Format string</title>
<para>You can define that a function takes a format string.
Example:</para>
@ -871,7 +903,7 @@ Checking null.c...
<para>No error is reported for that:</para>
<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
format string. For instance:</para>
@ -904,7 +936,7 @@ Checking formatstring.c...
</section>
<section>
<title>Function Argument: Value range</title>
<title>Value range</title>
<para>The valid values can be defined. Imagine:</para>
@ -944,7 +976,7 @@ Checking range.c...
</section>
<section>
<title>Function Argument: minsize</title>
<title>minsize</title>
<para>Some function arguments take a buffer. With minsize you can
configure the min size of the buffer (in bytes, not elements).
@ -1023,7 +1055,7 @@ Checking minsize.c...
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>noreturn</title>
@ -1107,6 +1139,44 @@ Checking useretval.c...
&lt;/def&gt;</programlisting>
</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>
<title>define</title>
@ -1190,51 +1260,6 @@ Checking unusedvar.cpp...
&lt;/container&gt;
&lt;/def&gt;</programlisting>
</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>