Skip to content

Commit c071d75

Browse files
danmardanmar
committed
Manual: Made chapter about library configuration shorter
1 parent fa7f8dd commit c071d75

1 file changed

Lines changed: 77 additions & 221 deletions

File tree

‎man/manual.docbook‎

Lines changed: 77 additions & 221 deletions
Original file line numberDiff line numberDiff line change
@@ -449,47 +449,47 @@ gui/test.cpp,16,error,mismatchAllocDealloc,Mismatching allocation and deallocati
449449
<term>callstack</term>
450450

451451
<listitem>
452-
callstack - if available
452+
callstack - if available
453453
</listitem>
454454
</varlistentry>
455455

456456
<varlistentry>
457457
<term>file</term>
458458

459459
<listitem>
460-
filename
460+
filename
461461
</listitem>
462462
</varlistentry>
463463

464464
<varlistentry>
465465
<term>id</term>
466466

467467
<listitem>
468-
message id
468+
message id
469469
</listitem>
470470
</varlistentry>
471471

472472
<varlistentry>
473473
<term>line</term>
474474

475475
<listitem>
476-
line number
476+
line number
477477
</listitem>
478478
</varlistentry>
479479

480480
<varlistentry>
481481
<term>message</term>
482482

483483
<listitem>
484-
verbose message text
484+
verbose message text
485485
</listitem>
486486
</varlistentry>
487487

488488
<varlistentry>
489489
<term>severity</term>
490490

491491
<listitem>
492-
severity
492+
severity
493493
</listitem>
494494
</varlistentry>
495495
</variablelist>
@@ -731,246 +731,102 @@ Checking test.c...
731731
&lt;def&gt;
732732
&lt;/def&gt;</programlisting>
733733

734-
<section>
735-
<title>&lt;alloc&gt; and &lt;dealloc&gt;</title>
736-
737-
<para>Allocation and deallocation is defined <literal>using
738-
&lt;alloc&gt; and &lt;dealloc&gt;. These are used inside inside
739-
<literal>&lt;memory&gt;</literal> or
740-
<literal>&lt;resource&gt;.</literal></literal></para>
741-
742-
<para>Here is example code:</para>
743-
744-
<programlisting>void ok()
745-
{
746-
char *p = alloc_something();
747-
free_something(p);
748-
}
749-
750-
void leak()
751-
{
752-
char *p = alloc_something();
753-
}</programlisting>
754-
755-
<para>Cppcheck doesn't normally report any errors for that:</para>
756-
757-
<programlisting># cppcheck test.c
758-
Checking test.c...</programlisting>
759-
760-
<para>Example configuration:</para>
761-
762-
<programlisting>&lt;?xml version="1.0"?&gt;
763-
&lt;def&gt;
764-
&lt;memory&gt;
765-
&lt;alloc&gt;alloc_something&lt;/alloc&gt;
766-
&lt;dealloc&gt;free_something&lt;/dealloc&gt;
767-
&lt;/memory&gt;
768-
&lt;/def&gt;</programlisting>
769-
770-
<para>That tells Cppcheck that <literal>alloc_something</literal>
771-
allocates memory and that the matching deallocation function is
772-
<literal>free_something</literal>.</para>
773-
774-
<para>Output from <literal>Cppcheck</literal>:</para>
775-
776-
<programlisting># cppcheck --library=something.cfg test.c
777-
Checking test.c...
778-
[test.c:10]: (error) Memory leak: p</programlisting>
779-
</section>
780-
781-
<section>
782-
<title>&lt;ignore&gt; and &lt;use&gt;</title>
783-
784-
<para>The <literal>&lt;ignore&gt;</literal> and
785-
<literal>&lt;use&gt;</literal> tells Cppcheck how functions uses
786-
allocated memory. Example code:</para>
734+
<para>This configuration file is filled up with various options:</para>
787735

788-
<programlisting>void f()
789-
{
790-
char *p = alloc_something();
791-
do_something(p);
792-
*p = 0;
793-
}</programlisting>
794-
795-
<para>If you want that the <literal>do_something</literal> function call
796-
is ignored, use &lt;ignore&gt;:</para>
797-
798-
<programlisting>&lt;?xml version="1.0"?&gt;
736+
<programlisting>&lt;?xml version="1.0"?&gt;
799737
&lt;def&gt;
800738
&lt;memory&gt;
801-
&lt;alloc&gt;alloc_something&lt;/alloc&gt;
802-
&lt;dealloc&gt;free_something&lt;/dealloc&gt;
803-
&lt;/memory&gt;
804-
&lt;ignore&gt;do_something&lt;/ignore&gt;
805-
&lt;/def&gt;</programlisting>
739+
&lt;alloc&gt;CreateFred&lt;/alloc&gt;
740+
&lt;dealloc&gt;CloseFred&lt;/dealloc&gt;
806741

807-
<para>Running <literal>Cppcheck</literal> now:</para>
808-
809-
<para><programlisting># cppcheck --library=something.cfg test.c
810-
Checking test.c...
811-
[test.c:10]: (error) Memory leak: p</programlisting>If the
812-
<literal>do_something</literal> takes the allocated memory and
813-
deallocates it later, then use <literal>&lt;use&gt;</literal>
814-
instead:</para>
815-
816-
<para><programlisting>&lt;?xml version="1.0"?&gt;
817-
&lt;def&gt;
818-
&lt;memory&gt;
819-
&lt;alloc&gt;alloc_something&lt;/alloc&gt;
820-
&lt;dealloc&gt;free_something&lt;/dealloc&gt;
821-
&lt;use&gt;do_something&lt;/use&gt;
742+
&lt;use&gt;AppendFred&lt;/use&gt;
822743
&lt;/memory&gt;
823-
&lt;/def&gt;</programlisting>Running Cppcheck now:</para>
824-
825-
<programlisting># cppcheck --library=something.cfg test.c
826-
Checking test.c...</programlisting>
827744

828-
<para>Cppcheck will often assume that functions "use" allocated memory.
829-
By using &lt;ignore&gt; you can make Cppcheck detect more errors. By
830-
using &lt;use&gt;, no extra errors are detected but Cppcheck will not
831-
need to assume.</para>
832-
</section>
833-
834-
<section>
835-
<title>allocate but not initialize</title>
836-
837-
<para>Some allocation function initialize the data, others don't. Here
838-
is a example code:</para>
839-
840-
<programlisting>void f()
841-
{
842-
char *p = alloc_something();
843-
char c = *p;
844-
free_something();
845-
}</programlisting>
846-
847-
<para>No error is reported:</para>
848-
849-
<programlisting># cppcheck --library=something.cfg test.c
850-
Checking test.c...</programlisting>
851-
852-
<para>Here is a configuration that tells cppcheck that alloc_something
853-
doesn't initialize the data:</para>
854-
855-
<programlisting>&lt;?xml version="1.0"?&gt;
856-
&lt;def&gt;
857745
&lt;memory&gt;
858-
&lt;alloc init="false"&gt;alloc_something&lt;/alloc&gt;
859-
&lt;dealloc&gt;free_something&lt;/dealloc&gt;
746+
&lt;alloc init="false"&gt;AllocWilma&lt;/alloc&gt;
747+
&lt;alloc init="true"&gt;CAllocWilma&lt;/alloc&gt;
748+
&lt;dealloc&gt;CloseWilma&lt;/dealloc&gt;
860749
&lt;/memory&gt;
861-
&lt;/def&gt;</programlisting>
862-
863-
<para>Now you will get this error message:</para>
864-
865-
<programlisting># cppcheck --library=something.cfg test.c
866-
Checking test.c...
867-
[test.c:4]: (error) Memory is allocated but not initialized: p</programlisting>
868-
</section>
869-
870-
<section>
871-
<title>function arguments: null pointers</title>
872-
873-
<para>You can define if a function parameter can be NULL or if it must
874-
be non-NULL.</para>
875-
876-
<para>Example code:</para>
877-
878-
<programlisting>void do_something(char *p);
879-
880-
void f()
881-
{
882-
do_something(NULL);
883-
}</programlisting>
884750

885-
<para>Normally no error is reported for that code.</para>
751+
&lt;resource&gt;
752+
&lt;alloc&gt;Lock&lt;/alloc&gt;
753+
&lt;dealloc&gt;Unlock&lt;/dealloc&gt;
754+
&lt;/resource&gt;
886755

887-
<para>But if the do_something() parameter should be non-NULL you can use
888-
this configuration:</para>
756+
&lt;ignore&gt;IsEqual&lt;/ignore&gt;
889757

890-
<programlisting>&lt;?xml version="1.0"?&gt;
891-
&lt;def&gt;
892-
&lt;function name="do_something"&gt;
758+
&lt;function name="AssignFred"&gt;
759+
&lt;noreturn&gt;false&lt;/noreturn&gt;
893760
&lt;arg nr="1"&gt;
894761
&lt;not-null/&gt;
895762
&lt;/arg&gt;
763+
&lt;arg nr="2"&gt;
764+
&lt;not-uninit/&gt;
765+
&lt;/arg&gt;
896766
&lt;/function&gt;
897767
&lt;/def&gt;</programlisting>
898768

899-
<para>Now the output from cppcheck is:</para>
900-
901-
<programlisting># cppcheck --library=something.cfg test1.c
902-
Checking test1.c...
903-
[test1.c:5]: (error) Null pointer dereference</programlisting>
904-
</section>
769+
<para>In the <literal>&lt;memory&gt;</literal> and
770+
<literal>&lt;resource&gt;</literal> the allocation and deallocation
771+
functions are configured. Putting allocation and deallocation functions in
772+
different <literal>&lt;memory&gt;</literal> and
773+
<literal>&lt;resource&gt;</literal> blocks means they are mismatching -
774+
you'll get a warning message if you allocate memory with
775+
<literal>CreateFred</literal> and try to close it with
776+
<literal>CloseWilma</literal>.</para>
777+
778+
<para>The <literal>&lt;use&gt;</literal> and
779+
<literal>&lt;ignore&gt;</literal> elements are used to control the leaks
780+
checking. If it should be ignored that a function is called, use
781+
<literal>&lt;ignore&gt;</literal>. If there is no leak whenever the memory
782+
is passed to a function, use <literal>&lt;use&gt;</literal>.</para>
783+
784+
<para>In the <literal>&lt;function&gt;</literal> block some useful info is
785+
added about function behaviour. The <literal>&lt;noreturn&gt;</literal>
786+
tells <literal>Cppcheck</literal> if the function is a no return function.
787+
The <literal>&lt;arg&gt;</literal> is used to validate arguments. If it's
788+
invalid to pass NULL, use <literal>&lt;not-null&gt;</literal>. If it's
789+
invalid to pass uninitialized data, use
790+
<literal>&lt;not-uninit&gt;</literal>. If the function takes a pointer
791+
argument then it is always invalid to pass a uninitialized/dead pointer.
792+
The <literal>&lt;not-uninit&gt;</literal> will then mean that the data
793+
that the pointer points at must be initialized.</para>
905794

906795
<section>
907-
<title>Function arguments: uninitialized data</title>
796+
<title>Example: strcpy()</title>
908797

909-
<para>Here is example code:</para>
798+
<para>No configuration is necessary for the standard functions. The
799+
strcpy() was chosen in this example for demonstration purposes because
800+
its behaviour is well-known. </para>
910801

911-
<programlisting>void do_something(char *p);
802+
<para>The proper configuration for the standard strcpy() function would
803+
be:</para>
912804

913-
void f()
914-
{
915-
char str[10];
916-
do_something(str);
917-
}</programlisting>
918-
919-
<para>Normally <literal>Cppcheck</literal> doesn't report any error
920-
message for that. However if the parameter must be initialized there is
921-
a problem. Here is a configuration that says that the parameter must be
922-
initialized:</para>
923-
924-
<para><programlisting>&lt;?xml version="1.0"?&gt;
925-
&lt;def&gt;
926-
&lt;function name="do_something"&gt;
805+
<programlisting> &lt;function name="strcpy"&gt;
806+
&lt;noreturn&gt;false&lt;/noreturn&gt;
927807
&lt;arg nr="1"&gt;
808+
&lt;not-null/&gt;
809+
&lt;/arg&gt;
810+
&lt;arg nr="2"&gt;
811+
&lt;not-null/&gt;
928812
&lt;not-uninit/&gt;
929813
&lt;/arg&gt;
930-
&lt;/function&gt;
931-
&lt;/def&gt;</programlisting>Now the cppcheck output is:</para>
932-
933-
<programlisting># cppcheck --library=something.cfg test1.c
934-
Checking test1.c...
935-
[test1.c:6]: (error) Uninitialized variable: str</programlisting>
936-
</section>
937-
938-
<section>
939-
<title>no return</title>
940-
941-
<para>You can define if a function is "noreturn" or not. Example
942-
code:</para>
943-
944-
<programlisting>int f(int x)
945-
{
946-
int a;
947-
if (x == 3)
948-
a = 1;
949-
else
950-
do_something();
951-
return a; // a is uninitialized if do_something() is called and it returns
952-
}</programlisting>
953-
954-
<para>The output is:</para>
955-
956-
<programlisting># cppcheck test.c
957-
Checking test.c...</programlisting>
958-
959-
<para>To tell Cppcheck that <literal>do_something</literal> is not a
960-
<literal>noreturn</literal> function, use such configuration:</para>
961-
962-
<programlisting>&lt;?xml version="1.0"?&gt;
963-
&lt;def&gt;
964-
&lt;function name="do_something"&gt;
965-
&lt;noreturn&gt;false&lt;/noreturn&gt;
966-
&lt;/function&gt;
967-
&lt;/def&gt;</programlisting>
968-
969-
<para>Now Cppcheck will be able to detect the error:</para>
970-
971-
<programlisting>cppcheck --library=something.cfg test.c
972-
Checking test.c...
973-
[test.c:8]: (error) Uninitialized variable: a</programlisting>
814+
&lt;/function&gt;</programlisting>
815+
816+
<para>The <literal>&lt;noreturn&gt;</literal> is optional. But it's
817+
recommended.</para>
818+
819+
<para>The first parameter that the function takes is a pointer. It must
820+
not be a null pointer, a uninitialized pointer nor a dead pointer. It
821+
must point at some data, this data can be initialized but it is not
822+
wrong if it isn't. Using <literal>&lt;not-null&gt;</literal> is correct.
823+
<literal>Cppcheck</literal> will check by default that the pointer is
824+
not uninitialized nor dead.</para>
825+
826+
<para>The second parameter the function takes is a pointer. It must not
827+
be null. And it must point at initialized data. Using
828+
<literal>&lt;not-null&gt;</literal> and
829+
<literal>&lt;not-uninit&gt;</literal> is correct.</para>
974830
</section>
975831
</chapter>
976832

0 commit comments

Comments
 (0)