From c071d752e0f68d732f7065b115fcc505ba3bfded Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Marjam=C3=A4ki?= Date: Tue, 16 Jul 2013 10:28:43 +0200 Subject: [PATCH] Manual: Made chapter about library configuration shorter --- man/manual.docbook | 310 ++++++++++++--------------------------------- 1 file changed, 83 insertions(+), 227 deletions(-) diff --git a/man/manual.docbook b/man/manual.docbook index 41f7b1a32..057d0bd5a 100644 --- a/man/manual.docbook +++ b/man/manual.docbook @@ -449,7 +449,7 @@ gui/test.cpp,16,error,mismatchAllocDealloc,Mismatching allocation and deallocati callstack - callstack - if available + callstack - if available @@ -457,7 +457,7 @@ gui/test.cpp,16,error,mismatchAllocDealloc,Mismatching allocation and deallocati file - filename + filename @@ -465,7 +465,7 @@ gui/test.cpp,16,error,mismatchAllocDealloc,Mismatching allocation and deallocati id - message id + message id @@ -473,7 +473,7 @@ gui/test.cpp,16,error,mismatchAllocDealloc,Mismatching allocation and deallocati line - line number + line number @@ -481,7 +481,7 @@ gui/test.cpp,16,error,mismatchAllocDealloc,Mismatching allocation and deallocati message - verbose message text + verbose message text @@ -489,7 +489,7 @@ gui/test.cpp,16,error,mismatchAllocDealloc,Mismatching allocation and deallocati severity - severity + severity @@ -731,246 +731,102 @@ Checking test.c... <def> </def> -
- <alloc> and <dealloc> + This configuration file is filled up with various options: - Allocation and deallocation is defined using - <alloc> and <dealloc>. These are used inside inside - <memory> or - <resource>. - - Here is example code: - - void ok() -{ - char *p = alloc_something(); - free_something(p); -} - -void leak() -{ - char *p = alloc_something(); -} - - Cppcheck doesn't normally report any errors for that: - - # cppcheck test.c -Checking test.c... - - Example configuration: - - <?xml version="1.0"?> + <?xml version="1.0"?> <def> <memory> - <alloc>alloc_something</alloc> - <dealloc>free_something</dealloc> + <alloc>CreateFred</alloc> + <dealloc>CloseFred</dealloc> + + <use>AppendFred</use> </memory> -</def> - That tells Cppcheck that alloc_something - allocates memory and that the matching deallocation function is - free_something. - - Output from Cppcheck: - - # cppcheck --library=something.cfg test.c -Checking test.c... -[test.c:10]: (error) Memory leak: p -
- -
- <ignore> and <use> - - The <ignore> and - <use> tells Cppcheck how functions uses - allocated memory. Example code: - - void f() -{ - char *p = alloc_something(); - do_something(p); - *p = 0; -} - - If you want that the do_something function call - is ignored, use <ignore>: - - <?xml version="1.0"?> -<def> <memory> - <alloc>alloc_something</alloc> - <dealloc>free_something</dealloc> + <alloc init="false">AllocWilma</alloc> + <alloc init="true">CAllocWilma</alloc> + <dealloc>CloseWilma</dealloc> </memory> - <ignore>do_something</ignore> -</def> - Running Cppcheck now: + <resource> + <alloc>Lock</alloc> + <dealloc>Unlock</dealloc> + </resource> - # cppcheck --library=something.cfg test.c -Checking test.c... -[test.c:10]: (error) Memory leak: pIf the - do_something takes the allocated memory and - deallocates it later, then use <use> - instead: + <ignore>IsEqual</ignore> - <?xml version="1.0"?> -<def> - <memory> - <alloc>alloc_something</alloc> - <dealloc>free_something</dealloc> - <use>do_something</use> - </memory> -</def>Running Cppcheck now: - - # cppcheck --library=something.cfg test.c -Checking test.c... - - Cppcheck will often assume that functions "use" allocated memory. - By using <ignore> you can make Cppcheck detect more errors. By - using <use>, no extra errors are detected but Cppcheck will not - need to assume. -
- -
- allocate but not initialize - - Some allocation function initialize the data, others don't. Here - is a example code: - - void f() -{ - char *p = alloc_something(); - char c = *p; - free_something(); -} - - No error is reported: - - # cppcheck --library=something.cfg test.c -Checking test.c... - - Here is a configuration that tells cppcheck that alloc_something - doesn't initialize the data: - - <?xml version="1.0"?> -<def> - <memory> - <alloc init="false">alloc_something</alloc> - <dealloc>free_something</dealloc> - </memory> -</def> - - Now you will get this error message: - - # cppcheck --library=something.cfg test.c -Checking test.c... -[test.c:4]: (error) Memory is allocated but not initialized: p -
- -
- function arguments: null pointers - - You can define if a function parameter can be NULL or if it must - be non-NULL. - - Example code: - - void do_something(char *p); - -void f() -{ - do_something(NULL); -} - - Normally no error is reported for that code. - - But if the do_something() parameter should be non-NULL you can use - this configuration: - - <?xml version="1.0"?> -<def> - <function name="do_something"> + <function name="AssignFred"> + <noreturn>false</noreturn> <arg nr="1"> <not-null/> </arg> - </function> -</def> - - Now the output from cppcheck is: - - # cppcheck --library=something.cfg test1.c -Checking test1.c... -[test1.c:5]: (error) Null pointer dereference -
- -
- Function arguments: uninitialized data - - Here is example code: - - void do_something(char *p); - -void f() -{ - char str[10]; - do_something(str); -} - - Normally Cppcheck doesn't report any error - message for that. However if the parameter must be initialized there is - a problem. Here is a configuration that says that the parameter must be - initialized: - - <?xml version="1.0"?> -<def> - <function name="do_something"> - <arg nr="1"> + <arg nr="2"> <not-uninit/> </arg> </function> -</def>Now the cppcheck output is: - - # cppcheck --library=something.cfg test1.c -Checking test1.c... -[test1.c:6]: (error) Uninitialized variable: str -
- -
- no return - - You can define if a function is "noreturn" or not. Example - code: - - int f(int x) -{ - int a; - if (x == 3) - a = 1; - else - do_something(); - return a; // a is uninitialized if do_something() is called and it returns -} - - The output is: - - # cppcheck test.c -Checking test.c... - - To tell Cppcheck that do_something is not a - noreturn function, use such configuration: - - <?xml version="1.0"?> -<def> - <function name="do_something"> - <noreturn>false</noreturn> - </function> </def> - Now Cppcheck will be able to detect the error: + In the <memory> and + <resource> the allocation and deallocation + functions are configured. Putting allocation and deallocation functions in + different <memory> and + <resource> blocks means they are mismatching - + you'll get a warning message if you allocate memory with + CreateFred and try to close it with + CloseWilma. - cppcheck --library=something.cfg test.c -Checking test.c... -[test.c:8]: (error) Uninitialized variable: a + The <use> and + <ignore> elements are used to control the leaks + checking. If it should be ignored that a function is called, use + <ignore>. If there is no leak whenever the memory + is passed to a function, use <use>. + + In the <function> block some useful info is + added about function behaviour. The <noreturn> + tells Cppcheck if the function is a no return function. + The <arg> is used to validate arguments. If it's + invalid to pass NULL, use <not-null>. If it's + invalid to pass uninitialized data, use + <not-uninit>. If the function takes a pointer + argument then it is always invalid to pass a uninitialized/dead pointer. + The <not-uninit> will then mean that the data + that the pointer points at must be initialized. + +
+ Example: strcpy() + + No configuration is necessary for the standard functions. The + strcpy() was chosen in this example for demonstration purposes because + its behaviour is well-known. + + The proper configuration for the standard strcpy() function would + be: + + <function name="strcpy"> + <noreturn>false</noreturn> + <arg nr="1"> + <not-null/> + </arg> + <arg nr="2"> + <not-null/> + <not-uninit/> + </arg> + </function> + + The <noreturn> is optional. But it's + recommended. + + The first parameter that the function takes is a pointer. It must + not be a null pointer, a uninitialized pointer nor a dead pointer. It + must point at some data, this data can be initialized but it is not + wrong if it isn't. Using <not-null> is correct. + Cppcheck will check by default that the pointer is + not uninitialized nor dead. + + The second parameter 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.