diff --git a/man/manual.docbook b/man/manual.docbook
index d33e5a252..1d0cc089e 100644
--- a/man/manual.docbook
+++ b/man/manual.docbook
@@ -5,7 +5,7 @@
Cppcheck 1.75 dev
- 2015-09-09
+ 2016-07-27
@@ -314,7 +314,7 @@ cppcheck --enable=all
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 --force or
- --max-configs to override the number
+ --max-configs to override the number
of configurations.
# check all configurations
@@ -662,14 +662,17 @@ Checking test.c...
Library configuration
- When external libraries are used, such as windows/posix/gtk/qt/etc,
+ When external libraries are used, such as WinAPI, POSIX, gtk, Qt, etc,
Cppcheck doesn't know how the external functions
behave. Cppcheck then fails to detect various problems
such as leaks, buffer overflows, possible null pointer dereferences, etc.
But this can be fixed with configuration files.
- If you create a configuration file for a popular library, we would
- appreciate if you upload it to us.
+ 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++, std.cfg, 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.
Using your own custom .cfg file
@@ -692,7 +695,9 @@ Checking test.c...
Memory/resource leaks
- Cppcheck has configurable checking for leaks.
+ 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.
alloc and dealloc
@@ -705,14 +710,14 @@ Checking test.c...
}
The code example above has a resource leak -
- CreatePen() is a windows function that creates a
- pen. However Cppcheck doesn't assume that return values from functions
+ CreatePen() 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:
# cppcheck pen1.c
Checking pen1.c...
- If you provide a windows configuration file then
+ If you provide a configuration file then
Cppcheck detects the bug:
# cppcheck --library=windows.cfg pen1.c
@@ -730,6 +735,12 @@ Checking pen1.c...
</def>
+ The allocation and deallocation functions are organized in groups.
+ Each group is defined in a <resource> or
+ <memory> tag and is identified by its <dealloc>
+ functions. This means, groups with overlapping <dealloc>
+ tags are merged.
+
leak-ignore and use
@@ -747,14 +758,14 @@ Checking pen1.c...
takes care of the memory so there is no memory leak.
To specify that dostuff doesn't take care of
- the memory in any way, use leak-ignore:
+ the memory in any way, use leak-ignore in the
+ <function> tag (see next section):
<?xml version="1.0"?>
<def>
<function name="dostuff">
<leak-ignore/>
<arg nr="1"/>
- <arg nr="2"/>
</function>
</def>
@@ -764,13 +775,12 @@ Checking pen1.c...
<?xml version="1.0"?>
<def>
<memory>
- <alloc>malloc</alloc>
<dealloc>free</dealloc>
<use>dostuff</use>
</memory>
</def>
- The <use>
+ The <use>
configuration has no logical purpose. You will get the same warnings
without it. Use it to silence --check-library
information messages.
@@ -778,35 +788,57 @@ Checking pen1.c...
- Function argument: Uninitialized memory
+ Function behaviour
- Here is an example program:
+ To specify the behaviour of functions and how they should be used,
+ <function> tags can be used. Functions are identified
+ by their name, specified in the name 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: <function name="memcpy,std::memcpy">.
+
- void test()
+
+ Function arguments
+
+ The arguments a function takes can be specified by <arg>
+ tags. Each of them takes the number of the argument (starting from 1) in the
+ nr attribute, or nr="any" for variadic arguments.
+ Optional arguments can be specified by providing a default value:
+ default="value". Specifying -1 as the argument
+ number is going to apply a check to all arguments of that function. The specifications
+ for individual arguments override this setting.
+
+
+ Uninitialized memory
+
+ Here is an example program:
+
+ void test()
{
char buffer1[1024];
char buffer2[1024];
CopyMemory(buffer1, buffer2, 1024);
}
- The bug here is that buffer2 is uninitialized. The second argument
- for CopyMemory needs to be initialized. However
- Cppcheck assumes that it is fine to pass
- uninitialized variables to functions:
+ The bug here is that buffer2 is uninitialized. The second argument
+ for CopyMemory needs to be initialized. However,
+ Cppcheck assumes that it is fine to pass
+ uninitialized variables to functions:
- # cppcheck uninit.c
+ # cppcheck uninit.c
Checking uninit.c...
- If you provide a windows configuration file then Cppcheck detects
- the bug:
+ If you provide a configuration file then Cppcheck detects
+ the bug:
- # cppcheck --library=windows.cfg uninit.c
+ # cppcheck --library=windows.cfg uninit.c
Checking uninit.c...
[uninit.c:5]: (error) Uninitialized variable: buffer2
- Here is the minimal windows.cfg:
+ Here is the minimal windows.cfg:
- <?xml version="1.0"?>
+ <?xml version="1.0"?>
<def>
<function name="CopyMemory">
<arg nr="1"/>
@@ -816,36 +848,36 @@ Checking uninit.c...
<arg nr="3"/>
</function>
</def>
-
+
-
- Function Argument: Null pointers
+
+ Null pointers
- Cppcheck assumes it's ok to pass NULL pointers to functions. Here
- is an example program:
+ Cppcheck assumes it's ok to pass NULL pointers to functions. Here
+ is an example program:
- void test()
+ void test()
{
CopyMemory(NULL, NULL, 1024);
}
- The MSDN documentation is not clear if that is ok or not. But
- let's assume it's bad. Cppcheck assumes that it's ok to pass NULL to
- functions so no error is reported:
+ The MSDN documentation is not clear if that is ok or not. But
+ let's assume it's bad. Cppcheck assumes that it's ok to pass NULL to
+ functions so no error is reported:
- # cppcheck null.c
+ # cppcheck null.c
Checking null.c...
- If you provide a windows configuration file then
- Cppcheck detects the bug:
+ If you provide a windows configuration file then
+ Cppcheck detects the bug:
- cppcheck --library=windows.cfg null.c
+ cppcheck --library=windows.cfg null.c
Checking null.c...
[null.c:3]: (error) Null pointer dereference
- Here is a minimal windows.cfg file:
+ Here is a minimal windows.cfg file:
- <?xml version="1.0"?>
+ <?xml version="1.0"?>
<def>
<function name="CopyMemory">
<arg nr="1">
@@ -855,28 +887,28 @@ Checking null.c...
<arg nr="3"/>
</function>
</def>
-
+
-
- Function Argument: Format string
+
+ Format string
- You can define that a function takes a format string.
- Example:
+ You can define that a function takes a format string.
+ Example:
- void test()
+ void test()
{
do_something("%i %i\n", 1024);
}
- No error is reported for that:
+ No error is reported for that:
- # cppcheck formatstring.c
-Checking formatstring.c...
+ # cppcheck formatstring.c
+ Checking formatstring.c...
- A configuration file can be created that says that the string is a
- format string. For instance:
+ A configuration file can be created that says that the string is a
+ format string. For instance:
- <?xml version="1.0"?>
+ <?xml version="1.0"?>
<def>
<function name="do_something">
<formatstr type="printf"/>
@@ -886,42 +918,42 @@ Checking formatstring.c...
</function>
</def>Now Cppcheck will report an error:
- cppcheck --library=test.cfg formatstring.c
+ cppcheck --library=test.cfg formatstring.c
Checking formatstring.c...
[formatstring.c:3]: (error) do_something format string requires 2 parameters but only 1 is given.
- The type attribute can be either:
+ The type attribute can be either:
-
-
- printf - format string follows the printf rules
-
+
+
+ printf - format string follows the printf rules
+
-
- scanf - format string follows the scanf rules
-
-
-
+
+ scanf - format string follows the scanf rules
+
+
+
-
- Function Argument: Value range
+
+ Value range
- The valid values can be defined. Imagine:
+ The valid values can be defined. Imagine:
- void test()
+ void test()
{
do_something(1024);
}
- No error is reported for that:
+ No error is reported for that:
- # cppcheck valuerange.c
+ # cppcheck valuerange.c
Checking valuerange.c...
- A configuration file can be created that says that 1024 is out of
- bounds. For instance:
+ A configuration file can be created that says that 1024 is out of
+ bounds. For instance:
- <?xml version="1.0"?>
+ <?xml version="1.0"?>
<def>
<function name="do_something">
<arg nr="1">
@@ -930,42 +962,42 @@ Checking valuerange.c...
</function>
</def>Now Cppcheck will report an error:
- cppcheck --library=test.cfg range.c
+ cppcheck --library=test.cfg range.c
Checking range.c...
[range.c:3]: (error) Invalid do_something() argument nr 1. The value is 1024 but the valid values are '0-1023'.
- Some example expressions you can use in the valid element:
+ Some example expressions you can use in the valid element:
- 0,3,5 => only values 0, 3 and 5 are valid
+ 0,3,5 => only values 0, 3 and 5 are valid
-10:20 => all values between -10 and 20 are valid
:0 => all values that are less or equal to 0 are valid
0: => all values that are greater or equal to 0 are valid
0,2:32 => the value 0 and all values between 2 and 32 are valid
-
+
-
- Function Argument: minsize
+
+ minsize
- Some function arguments take a buffer. With minsize you can
- configure the min size of the buffer (in bytes, not elements).
- Imagine:
+ Some function arguments take a buffer. With minsize you can
+ configure the min size of the buffer (in bytes, not elements).
+ Imagine:
- void test()
+ void test()
{
char str[5];
do_something(str,"12345");
}
- No error is reported for that:
+ No error is reported for that:
- # cppcheck minsize.c
+ # cppcheck minsize.c
Checking minsize.c...
- A configuration file can for instance be created that says that
- the size of the buffer in argument 1 must be larger than the strlen of
- argument 2.For instance:
+ A configuration file can for instance be created that says that
+ the size of the buffer in argument 1 must be larger than the strlen of
+ argument 2.For instance:
- <?xml version="1.0"?>
+ <?xml version="1.0"?>
<def>
<function name="do_something">
<arg nr="1">
@@ -975,62 +1007,62 @@ Checking minsize.c...
</function>
</def>Now Cppcheck will report this error:
- cppcheck --library=1.cfg minsize.c
+ cppcheck --library=1.cfg minsize.c
Checking minsize.c...
[minsize.c:4]: (error) Buffer is accessed out of bounds: str
- There are different types of minsizes:
+ There are different types of minsizes:
-
-
- strlen
+
+
+ strlen
-
- buffer size must be larger than other arguments string
- length. Example: see strcpy configuration in std.cfg
-
-
+
+ buffer size must be larger than other arguments string
+ length. Example: see strcpy configuration in std.cfg
+
+
-
- argvalue
+
+ argvalue
-
- buffer size must be larger than value in other argument.
- Example: see memset configuration in std.cfg
-
-
+
+ buffer size must be larger than value in other argument.
+ Example: see memset configuration in std.cfg
+
+
-
- sizeof
+
+ sizeof
-
- buffer size must be larger than other argument buffer size.
- Example: see strncpy configuration in std.cfg
-
-
+
+ buffer size must be larger than other argument buffer size.
+ Example: see strncpy configuration in std.cfg
+
+
-
- mul
+
+ mul
-
- buffer size must be larger than multiplication result when
- multiplying values given in two other arguments. Typically one
- argument defines the element size and another element defines the
- number of elements. Example: see fread configuration in
- std.cfg
-
-
-
-
+
+ buffer size must be larger than multiplication result when
+ multiplying values given in two other arguments. Typically one
+ argument defines the element size and another element defines the
+ number of elements. Example: see fread configuration in
+ std.cfg
+
+
+
+
+
+
+ noreturn
-
- noreturn
+ Cppcheck doesn't assume that functions always return. Here is an
+ example code:
- Cppcheck doesn't assume that functions always return. Here is an
- example code:
-
- void test(int x)
+ void test(int x)
{
int data, buffer[1024];
if (x == 1)
@@ -1040,71 +1072,109 @@ Checking minsize.c...
buffer[0] = data; // <- error: data is uninitialized if x is not 1
}
- In theory, if ZeroMemory terminates the program
- then there is no bug. Cppcheck therefore reports no error:
+ In theory, if ZeroMemory terminates the program
+ then there is no bug. Cppcheck therefore reports no error:
- # cppcheck noreturn.c
+ # cppcheck noreturn.c
Checking noreturn.c...
- However if you use --check-library and
- --enable=information you'll get this:
+ However if you use --check-library and
+ --enable=information you'll get this:
- # cppcheck --check-library --enable=information noreturn.c
+ # cppcheck --check-library --enable=information noreturn.c
Checking noreturn.c...
[noreturn.c:7]: (information) --check-library: Function ZeroMemory() should have <noreturn> configuration
- If a proper windows.cfg is provided, the bug is
- detected:
+ If a proper windows.cfg is provided, the bug is
+ detected:
- # cppcheck --library=windows.cfg noreturn.c
+ # cppcheck --library=windows.cfg noreturn.c
Checking noreturn.c...
[noreturn.c:8]: (error) Uninitialized variable: data
- Here is a minimal windows.cfg file:
+ Here is a minimal windows.cfg file:
- <?xml version="1.0"?>
+ <?xml version="1.0"?>
<def>
<function name="ZeroMemory">
<noreturn>false</noreturn>
</function>
</def>
-
+
-
- use-retval
+
+ use-retval
- As long as nothing else is specified, cppcheck assumes that
- ignoring the return value of a function is ok:
+ As long as nothing else is specified, cppcheck assumes that
+ ignoring the return value of a function is ok:
- bool test(const char* a, const char* b)
+ bool test(const char* a, const char* b)
{
strcmp(a, b); // <- bug: The call of strcmp does not have side-effects, but the return value is ignored.
return true;
}
- In case strcmp has side effects, such as
- assigning the result to one of the parameters passed to it, nothing bad
- would happen:
+ In case strcmp has side effects, such as
+ assigning the result to one of the parameters passed to it, nothing bad
+ would happen:
- # cppcheck useretval.c
+ # cppcheck useretval.c
Checking useretval.c...
- If a proper lib.cfg is provided, the bug is
- detected:
+ If a proper lib.cfg is provided, the bug is
+ detected:
- # cppcheck --library=lib.cfg --enable=warning useretval.c
+ # cppcheck --library=lib.cfg --enable=warning useretval.c
Checking useretval.c...
[noreturn.c:3]: (warning) Return value of function strcmp() is not used.
- Here is a minimal lib.cfg file:
+ Here is a minimal lib.cfg file:
- <?xml version="1.0"?>
+ <?xml version="1.0"?>
<def>
<function name="strcmp">
<use-retval/>
</function>
</def>
+
+
+
+ Example configuration for strcpy()
+
+ The proper configuration for the standard strcpy() function would
+ be:
+
+ <function name="strcpy">
+ <leak-ignore/>
+ <noreturn>false</noreturn>
+ <arg nr="1">
+ <not-null/>
+ </arg>
+ <arg nr="2">
+ <not-null/>
+ <not-uninit/>
+ <strz/>
+ </arg>
+ </function>
+
+ The <leak-ignore/> tells Cppcheck to
+ ignore this function call in the leaks checking. Passing allocated
+ memory to this function won't mean it will be deallocated.
+
+ The <noreturn> tells Cppcheck if this
+ function returns or not.
+
+ The first argument that the function takes is a pointer. It must
+ not be a null pointer, therefore <not-null> is
+ used.
+
+ The second argument the function takes is a pointer. It must not
+ be null. And it must point at initialized data. Using
+ <not-null> and
+ <not-uninit> is correct. Moreover it must point
+ at a zero-terminated string so <strz> is also used.
+
@@ -1190,51 +1260,6 @@ Checking unusedvar.cpp...
</container>
</def>
-
-
- Example configuration for strcpy()
-
- The proper configuration for the standard strcpy() function would
- be:
-
- <function name="strcpy">
- <leak-ignore/>
- <noreturn>false</noreturn>
- <arg nr="1">
- <not-null/>
- </arg>
- <arg nr="2">
- <not-null/>
- <not-uninit/>
- <strz/>
- </arg>
- </function>
-
- The <leak-ignore/> tells Cppcheck to
- ignore this function call in the leaks checking. Passing allocated
- memory to this function won't mean it will be deallocated.
-
- The <noreturn> tells Cppcheck if this
- function returns or not.
-
- The first argument that the function takes is a pointer. It must
- not be a null pointer, therefore <not-null> is
- used.
-
- The second argument the function takes is a pointer. It must not
- be null. And it must point at initialized data. Using
- <not-null> and
- <not-uninit> is correct. Moreover it must point
- at a zero-terminated string so <strz> is also used.
-
-
-
- Specifications for all arguments
-
- Specifying -1 as the argument number is going
- to apply a check to all arguments of that function. The specifications
- for individual arguments override this setting.
-