diff --git a/man/manual.docbook b/man/manual.docbook new file mode 100644 index 000000000..f07ac9f6c --- /dev/null +++ b/man/manual.docbook @@ -0,0 +1,377 @@ + + + + + Cppcheck + + 2009-10-11 + + + + Getting started + +
+ First test + + Here is a simple code + + int main() +{ + char a[10]; + a[10] = 0; + return 0; +} + + If you save that into file1.c and + execute: + + cppcheck file1.c + + The output from cppcheck will then be: + + Checking file1.c... +[file1.c:4]: (error) Array index out of bounds +
+ +
+ Checking all files in a folder + + Normally a program has many sourcefiles. And you want to check + them all. Cppcheck can check all sourcefiles in a directory: + + cppcheck path + + If "path" is a folder then cppcheck will check all sourcefiles in + this folder. + + Checking path/file1.cpp... +1/2 files checked 50% done +Checking path/file2.cpp... +2/2 files checked 100% done +
+ +
+ Uncertain errors + + By default, only certain errors are reported. + + With "--all" you will get more reports. But beware - some messages + may be wrong. + + Here is a simple code example: + + void f() +{ + Fred *f = new Fred; +} + + Execute this command: + + cppcheck --all file1.cpp + + The output from Cppcheck: + + [file1.cpp:4]: (possible error) Memory leak: fred + + The "possible" means that the reported message may be wrong (if + Fred has automatic deallocation it is not a memory leak). +
+ +
+ Stylistic issues + + By default Cppcheck will only check for bugs. There are also a few + checks for stylistic issues. + + Here is a simple code example: + + void f(int x) +{ + int i; + if (x == 0) + { + i = 0; + } +} + + To enable stylistic checks, use the --style flag: + + cppcheck --style file1.c + + The reported error is: + + [file3.c:3]: (style) The scope of the variable i can be limited +
+ +
+ Saving results in file + + Many times you will want to save the results in a file. The + results are written to stderr and the progress messages are written to + stdout. So you can use the standard redirections to save to file. + + cppcheck file1.c 2> err.txt +
+ +
+ Unused functions + + 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. + + cppcheck --unused-functions path +
+ + + + XML output + + Cppcheck can generate the output in XML format. + + Use the --xml flag when you execute cppcheck: + + cppcheck --xml file1.cpp + + The xml format is: + + <?xml version="1.0"?> +<results> + <error file="file1.cpp" line="123" id="someError" severity="error" msg="some error text"/> +</results> + + Attributes: + + + + file + + + filename. Both relative and absolute paths are possible + + + + + line + + + a number + + + + + id + + + id of error. These are always valid symbolnames. + + + + + severity + + + one of: error / possible error / style / possible style + + + + + msg + + + the error message in plain text + + + + + + + Reformatting the output + + If you want to reformat the output so it looks different you can use + templates. + + To get Visual Studio compatible output you can use "--template + vs": + + cppcheck --template vs gui/test.cpp + + This output will look like this: + + Checking gui/test.cpp... +gui/test.cpp(31): error: Memory leak: b +gui/test.cpp(16): error: Mismatching allocation and deallocation: k + + To get gcc compatible output you can use "--template gcc": + + cppcheck --template gcc gui/test.cpp + + The output will look like this: + + Checking gui/test.cpp... +gui/test.cpp:31: error: Memory leak: b +gui/test.cpp:16: error: Mismatching allocation and deallocation: k + + You can write your own pattern (for example a comma-separated + format): + + cppcheck --template "{file},{line},{severity},{id},{message}" gui/test.cpp + + The output will look like this: + + Checking gui/test.cpp... +gui/test.cpp,31,error,memleak,Memory leak: b +gui/test.cpp,16,error,mismatchAllocDealloc,Mismatching allocation and deallocation: k + + + + + + Suppressions + + If you want to filter out certain errors you can suppress these. + First you need to create a suppressions file. + + [error id]:[filename] +[error id]:[filename2] +[error id] + + The error id is the id that you want to suppress. + The easiest way to get it is to use the --xml command + line flag. Copy and paste the id string from the xml + output. + + Here is an example: + + memleak:file1.cpp +exceptNew:file1.cpp +uninitvar + + You can then use the suppressions file: + + cppcheck --suppressions suppressions.txt src/ + + + + + + Leaks + + 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. + +
+ Automatic deallocation + + A common cause of false positives is when there is automatic + deallocation. Here is an example: + + void Form1::foo() +{ + QPushButton *pb = new QPushButton( "OK", this ); +} + + Cppcheck can't see where the deallocation is when you have such + code. + + If you execute: + + cppcheck --all file1.cpp + + The result will be: + + [file1.cpp:4]: (possible error) Memory leak: pb + + The "possible" in the error message means that the message may be + a false positive. + + To avoid such false positives, create a textfile and write the + names of the automaticly deallocated classes. + + QLabel +QPushButton + + Then execute cppcheck with the --auto-dealloc + option: + + cppcheck --auto-dealloc qt.lst file1.cpp +
+ +
+ Userdefined allocation/deallocation functions + + Cppcheck understands many common allocation and deallocation + functions. But not all. + + Here is a trick to add custom checking. First we write simple + implementations for the allocation and deallocation functions: + + void *CreateFred() +{ + return malloc(100); +} + +void DestroyFred(void *p) +{ + free(p); +} + + When Cppcheck see this it understands that CreateFred will return + allocated memory and that DestroyFred will deallocate memory. + + Here is an example program that uses CreateFred and + DestroyFred: + + void foo(int x) +{ + void *f = CreateFred(); + if (x == 1) + return; + DestroyFred(f); +} + + Execute Cppcheck this way: + + cppcheck --append=fred.cpp fred1.cpp + + The output from cppcheck is: + + Checking fred1.cpp... +[fred1.cpp:5]: (error) Memory leak: f +
+ + + + Exception safety + + Cppcheck has a few checks that ensure that you don't break the basic + guarantee of exception safety. We don't have any checks for the strong + guarantee yet. + + Example: + + Fred::Fred() : a(new int[20]), b(new int[20]) +{ +} + + By default cppcheck will not detect any problems in that + code. + + To enable the exception safety checking you can use + --enable: + + cppcheck --enable except.cpp + + The output will be: + + [except.cpp:3]: (style) Upon exception there is memory leak: a + + If an exception occurs when b is allocated, + a will leak. + + + +