1 <?xml version="1.0"?> <!-- -*- sgml -*- -->
2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
4 [ <!ENTITY % vg-entities SYSTEM "../../docs/xml/vg-entities.xml"> %vg-entities; ]>
7 <chapter id="mc-manual" xreflabel="Memcheck: a memory error detector">
8 <title>Memcheck: a memory error detector</title>
10 <para>To use this tool, you may specify <option>--tool=memcheck</option>
11 on the Valgrind command line. You don't have to, though, since Memcheck
12 is the default tool.</para>
15 <sect1 id="mc-manual.overview" xreflabel="Overview">
16 <title>Overview</title>
18 <para>Memcheck is a memory error detector. It can detect the following
19 problems that are common in C and C++ programs.</para>
23 <para>Accessing memory you shouldn't, e.g. overrunning and underrunning
24 heap blocks, overrunning the top of the stack, and accessing memory after
25 it has been freed.</para>
29 <para>Using undefined values, i.e. values that have not been initialised,
30 or that have been derived from other undefined values.</para>
34 <para>Incorrect freeing of heap memory, such as double-freeing heap
35 blocks, or mismatched use of
36 <function>malloc</function>/<computeroutput>new</computeroutput>/<computeroutput>new[]</computeroutput>
38 <function>free</function>/<computeroutput>delete</computeroutput>/<computeroutput>delete[]</computeroutput></para>
42 <para>Overlapping <computeroutput>src</computeroutput> and
43 <computeroutput>dst</computeroutput> pointers in
44 <computeroutput>memcpy</computeroutput> and related
49 <para>Passing a fishy (presumably negative) value to the
50 <computeroutput>size</computeroutput> parameter of a memory
51 allocation function.</para>
55 <para>Using a <computeroutput>size</computeroutput> value of 0
60 <para>Memory leaks.</para>
64 <para>Problems like these can be difficult to find by other means,
65 often remaining undetected for long periods, then causing occasional,
66 difficult-to-diagnose crashes.</para>
68 <para>Memcheck also provides <xref linkend="&vg-xtree-id;"/> memory
69 profiling using the command line
70 option <computeroutput>--xtree-memory</computeroutput> and the monitor command
71 <computeroutput>xtmemory</computeroutput>.</para>
76 <sect1 id="mc-manual.errormsgs"
77 xreflabel="Explanation of error messages from Memcheck">
78 <title>Explanation of error messages from Memcheck</title>
80 <para>Memcheck issues a range of error messages. This section presents a
81 quick summary of what error messages mean. The precise behaviour of the
82 error-checking machinery is described in <xref
83 linkend="mc-manual.machine"/>.</para>
86 <sect2 id="mc-manual.badrw"
87 xreflabel="Illegal read / Illegal write errors">
88 <title>Illegal read / Illegal write errors</title>
90 <para>For example:</para>
91 <programlisting><![CDATA[
92 Invalid read of size 4
93 at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9)
94 by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9)
95 by 0x40B07FF4: read_png_image(QImageIO *) (kernel/qpngio.cpp:326)
96 by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
97 Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd
100 <para>This happens when your program reads or writes memory at a place
101 which Memcheck reckons it shouldn't. In this example, the program did a
102 4-byte read at address 0xBFFFF0E0, somewhere within the system-supplied
103 library libpng.so.2.1.0.9, which was called from somewhere else in the
104 same library, called from line 326 of <filename>qpngio.cpp</filename>,
107 <para>Memcheck tries to establish what the illegal address might relate
108 to, since that's often useful. So, if it points into a block of memory
109 which has already been freed, you'll be informed of this, and also where
110 the block was freed. Likewise, if it should turn out to be just off
111 the end of a heap block, a common result of off-by-one-errors in
112 array subscripting, you'll be informed of this fact, and also where the
113 block was allocated. If you use the <option><link
114 linkend="opt.read-var-info">--read-var-info</link></option> option
115 Memcheck will run more slowly
116 but may give a more detailed description of any illegal address.</para>
118 <para>In this example, Memcheck can't identify the address. Actually
119 the address is on the stack, but, for some reason, this is not a valid
120 stack address -- it is below the stack pointer and that isn't allowed.
121 In this particular case it's probably caused by GCC generating invalid
122 code, a known bug in some ancient versions of GCC.</para>
124 <para>Note that Memcheck only tells you that your program is about to
125 access memory at an illegal address. It can't stop the access from
126 happening. So, if your program makes an access which normally would
127 result in a segmentation fault, you program will still suffer the same
128 fate -- but you will get a message from Memcheck immediately prior to
129 this. In this particular example, reading junk on the stack is
130 non-fatal, and the program stays alive.</para>
136 <sect2 id="mc-manual.uninitvals"
137 xreflabel="Use of uninitialised values">
138 <title>Use of uninitialised values</title>
140 <para>For example:</para>
141 <programlisting><![CDATA[
142 Conditional jump or move depends on uninitialised value(s)
143 at 0x402DFA94: _IO_vfprintf (_itoa.h:49)
144 by 0x402E8476: _IO_printf (printf.c:36)
145 by 0x8048472: main (tests/manuel1.c:8)
148 <para>An uninitialised-value use error is reported when your program
149 uses a value which hasn't been initialised -- in other words, is
150 undefined. Here, the undefined value is used somewhere inside the
151 <function>printf</function> machinery of the C library. This error was
152 reported when running the following small program:</para>
153 <programlisting><![CDATA[
157 printf ("x = %d\n", x);
158 }]]></programlisting>
160 <para>It is important to understand that your program can copy around
161 junk (uninitialised) data as much as it likes. Memcheck observes this
162 and keeps track of the data, but does not complain. A complaint is
163 issued only when your program attempts to make use of uninitialised
164 data in a way that might affect your program's externally-visible behaviour.
165 In this example, <varname>x</varname> is uninitialised. Memcheck observes
166 the value being passed to <function>_IO_printf</function> and thence to
167 <function>_IO_vfprintf</function>, but makes no comment. However,
168 <function>_IO_vfprintf</function> has to examine the value of
169 <varname>x</varname> so it can turn it into the corresponding ASCII string,
170 and it is at this point that Memcheck complains.</para>
172 <para>Sources of uninitialised data tend to be:</para>
175 <para>Local variables in procedures which have not been initialised,
176 as in the example above.</para>
179 <para>The contents of heap blocks (allocated with
180 <function>malloc</function>, <function>new</function>, or a similar
181 function) before you (or a constructor) write something there.
186 <para>To see information on the sources of uninitialised data in your
187 program, use the <option>--track-origins=yes</option> option. This
188 makes Memcheck run more slowly, but can make it much easier to track down
189 the root causes of uninitialised value errors.</para>
195 <sect2 id="mc-manual.bad-syscall-args"
196 xreflabel="Use of uninitialised or unaddressable values in system
198 <title>Use of uninitialised or unaddressable values in system
201 <para>Memcheck checks all parameters to system calls:
204 <para>It checks all the direct parameters themselves, whether they are
208 <para>Also, if a system call needs to read from a buffer provided by
209 your program, Memcheck checks that the entire buffer is addressable
210 and its contents are initialised.</para>
213 <para>Also, if the system call needs to write to a user-supplied
214 buffer, Memcheck checks that the buffer is addressable.</para>
219 <para>After the system call, Memcheck updates its tracked information to
220 precisely reflect any changes in memory state caused by the system
223 <para>Here's an example of two system calls with invalid parameters:</para>
224 <programlisting><![CDATA[
229 char* arr = malloc(10);
230 int* arr2 = malloc(sizeof(int));
231 write( 1 /* stdout */, arr, 10 );
236 <para>You get these complaints ...</para>
237 <programlisting><![CDATA[
238 Syscall param write(buf) points to uninitialised byte(s)
239 at 0x25A48723: __write_nocancel (in /lib/tls/libc-2.3.3.so)
240 by 0x259AFAD3: __libc_start_main (in /lib/tls/libc-2.3.3.so)
241 by 0x8048348: (within /auto/homes/njn25/grind/head4/a.out)
242 Address 0x25AB8028 is 0 bytes inside a block of size 10 alloc'd
243 at 0x259852B0: malloc (vg_replace_malloc.c:130)
244 by 0x80483F1: main (a.c:5)
246 Syscall param exit(error_code) contains uninitialised byte(s)
247 at 0x25A21B44: __GI__exit (in /lib/tls/libc-2.3.3.so)
248 by 0x8048426: main (a.c:8)
251 <para>... because the program has (a) written uninitialised junk
252 from the heap block to the standard output, and (b) passed an
253 uninitialised value to <function>exit</function>. Note that the first
254 error refers to the memory pointed to by
255 <computeroutput>buf</computeroutput> (not
256 <computeroutput>buf</computeroutput> itself), but the second error
257 refers directly to <computeroutput>exit</computeroutput>'s argument
258 <computeroutput>arr2[0]</computeroutput>.</para>
263 <sect2 id="mc-manual.badfrees" xreflabel="Illegal frees">
264 <title>Illegal frees</title>
266 <para>For example:</para>
267 <programlisting><![CDATA[
269 at 0x4004FFDF: free (vg_clientmalloc.c:577)
270 by 0x80484C7: main (tests/doublefree.c:10)
271 Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd
272 at 0x4004FFDF: free (vg_clientmalloc.c:577)
273 by 0x80484C7: main (tests/doublefree.c:10)
276 <para>Memcheck keeps track of the blocks allocated by your program
277 with <function>malloc</function>/<computeroutput>new</computeroutput>,
278 so it can know exactly whether or not the argument to
279 <function>free</function>/<computeroutput>delete</computeroutput> is
280 legitimate or not. Here, this test program has freed the same block
281 twice. As with the illegal read/write errors, Memcheck attempts to
282 make sense of the address freed. If, as here, the address is one
283 which has previously been freed, you wil be told that -- making
284 duplicate frees of the same block easy to spot. You will also get this
285 message if you try to free a pointer that doesn't point to the start of a
291 <sect2 id="mc-manual.rudefn"
292 xreflabel="When a heap block is freed with an inappropriate deallocation
294 <title>When a heap block is freed with an inappropriate deallocation
297 <para>In the following example, a block allocated with
298 <function>new[]</function> has wrongly been deallocated with
299 <function>free</function>:</para>
300 <programlisting><![CDATA[
301 Mismatched free() / delete / delete []
302 at 0x40043249: free (vg_clientfuncs.c:171)
303 by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149)
304 by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60)
305 by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44)
306 Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd
307 at 0x4004318C: operator new[](unsigned int) (vg_clientfuncs.c:152)
308 by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314)
309 by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
310 by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)
313 <para>In <literal>C++</literal> it's important to deallocate memory in a
314 way compatible with how it was allocated. The deal is:</para>
317 <para>If allocated with
318 <function>malloc</function>,
319 <function>calloc</function>,
320 <function>realloc</function>,
321 <function>valloc</function> or
322 <function>memalign</function>, you must
323 deallocate with <function>free</function>.</para>
326 <para>If allocated with <function>new</function>, you must deallocate
327 with <function>delete</function>.</para>
330 <para>If allocated with <function>new[]</function>, you must
331 deallocate with <function>delete[]</function>.</para>
335 <para>The worst thing is that on Linux apparently it doesn't matter if
336 you do mix these up, but the same program may then crash on a
337 different platform, Solaris for example. So it's best to fix it
338 properly. According to the KDE folks "it's amazing how many C++
339 programmers don't know this".</para>
341 <para>The reason behind the requirement is as follows. In some C++
342 implementations, <function>delete[]</function> must be used for
343 objects allocated by <function>new[]</function> because the compiler
344 stores the size of the array and the pointer-to-member to the
345 destructor of the array's content just before the pointer actually
346 returned. <function>delete</function> doesn't account for this and will get
347 confused, possibly corrupting the heap.</para>
353 <sect2 id="mc-manual.overlap"
354 xreflabel="Overlapping source and destination blocks">
355 <title>Overlapping source and destination blocks</title>
357 <para>The following C library functions copy some data from one
358 memory block to another (or something similar):
359 <function>memcpy</function>,
360 <function>strcpy</function>,
361 <function>strncpy</function>,
362 <function>strcat</function>,
363 <function>strncat</function>.
364 The blocks pointed to by their <computeroutput>src</computeroutput> and
365 <computeroutput>dst</computeroutput> pointers aren't allowed to overlap.
366 The POSIX standards have wording along the lines "If copying takes place
367 between objects that overlap, the behavior is undefined." Therefore,
368 Memcheck checks for this.
371 <para>For example:</para>
372 <programlisting><![CDATA[
373 ==27492== Source and destination overlap in memcpy(0xbffff294, 0xbffff280, 21)
374 ==27492== at 0x40026CDC: memcpy (mc_replace_strmem.c:71)
375 ==27492== by 0x804865A: main (overlap.c:40)
378 <para>You don't want the two blocks to overlap because one of them could
379 get partially overwritten by the copying.</para>
381 <para>You might think that Memcheck is being overly pedantic reporting
382 this in the case where <computeroutput>dst</computeroutput> is less than
383 <computeroutput>src</computeroutput>. For example, the obvious way to
384 implement <function>memcpy</function> is by copying from the first
385 byte to the last. However, the optimisation guides of some
386 architectures recommend copying from the last byte down to the first.
387 Also, some implementations of <function>memcpy</function> zero
388 <computeroutput>dst</computeroutput> before copying, because zeroing the
389 destination's cache line(s) can improve performance.</para>
391 <para>The moral of the story is: if you want to write truly portable
392 code, don't make any assumptions about the language
393 implementation.</para>
398 <sect2 id="mc-manual.fishyvalue"
399 xreflabel="Fishy argument values">
400 <title>Fishy argument values</title>
402 <para>All memory allocation functions take an argument specifying the
403 size of the memory block that should be allocated. Clearly, the requested
404 size should be a non-negative value and is typically not excessively large.
405 For instance, it is extremely unlikly that the size of an allocation
406 request exceeds 2**63 bytes on a 64-bit machine. It is much more likely that
407 such a value is the result of an erroneous size calculation and is in effect
408 a negative value (that just happens to appear excessively large because
409 the bit pattern is interpreted as an unsigned integer).
410 Such a value is called a "fishy value".
412 The <varname>size</varname> argument of the following allocation functions
413 is checked for being fishy:
414 <function>malloc</function>,
415 <function>calloc</function>,
416 <function>realloc</function>,
417 <function>memalign</function>,
418 <function>new</function>,
419 <function>new []</function>.
420 <function>__builtin_new</function>,
421 <function>__builtin_vec_new</function>,
422 For <function>calloc</function> both arguments are being checked.
425 <para>For example:</para>
426 <programlisting><![CDATA[
427 ==32233== Argument 'size' of function malloc has a fishy (possibly negative) value: -3
428 ==32233== at 0x4C2CFA7: malloc (vg_replace_malloc.c:298)
429 ==32233== by 0x400555: foo (fishy.c:15)
430 ==32233== by 0x400583: main (fishy.c:23)
433 <para>In earlier Valgrind versions those values were being referred to
434 as "silly arguments" and no back-trace was included.
439 <sect2 id="mc-manual.realocsizezero"
440 xreflabel="Realloc size zero">
441 <title>Realloc size zero</title>
443 <para>The (ab)use or realloc to also do the job of <function>free</function>
444 has been poorly understood for a long time. In the C17 standard
445 ISO/IEC 9899:2017] the behaviour of realloc when the size argument
446 is zero is specified as implementation defined. Memcheck warns about
447 the non-portable use or realloc.</para>
449 <para>For example:</para>
450 <programlisting><![CDATA[
451 ==77609== realloc() with size 0
452 ==77609== at 0x48502B8: realloc (vg_replace_malloc.c:1450)
453 ==77609== by 0x201989: main (realloczero.c:8)
454 ==77609== Address 0x5464040 is 0 bytes inside a block of size 4 alloc'd
455 ==77609== at 0x484CBB4: malloc (vg_replace_malloc.c:397)
456 ==77609== by 0x201978: main (realloczero.c:7)
462 <sect2 id="mc-manual.leaks" xreflabel="Memory leak detection">
463 <title>Memory leak detection</title>
465 <para>Memcheck keeps track of all heap blocks issued in response to
467 <function>malloc</function>/<function>new</function> et al.
468 So when the program exits, it knows which blocks have not been freed.
471 <para>If <option>--leak-check</option> is set appropriately, for each
472 remaining block, Memcheck determines if the block is reachable from pointers
473 within the root-set. The root-set consists of (a) general purpose registers
474 of all threads, and (b) initialised, aligned, pointer-sized data words in
475 accessible client memory, including stacks.</para>
477 <para>There are two ways a block can be reached. The first is with a
478 "start-pointer", i.e. a pointer to the start of the block. The second is with
479 an "interior-pointer", i.e. a pointer to the middle of the block. There are
480 several ways we know of that an interior-pointer can occur:</para>
484 <para>The pointer might have originally been a start-pointer and have been
485 moved along deliberately (or not deliberately) by the program. In
486 particular, this can happen if your program uses tagged pointers, i.e.
487 if it uses the bottom one, two or three bits of a pointer, which are
488 normally always zero due to alignment, in order to store extra
493 <para>It might be a random junk value in memory, entirely unrelated, just
494 a coincidence.</para>
498 <para>It might be a pointer to the inner char array of a C++
499 <computeroutput>std::string</computeroutput>. For example, some
500 compilers add 3 words at the beginning of the std::string to
501 store the length, the capacity and a reference count before the
502 memory containing the array of characters. They return a pointer
503 just after these 3 words, pointing at the char array.</para>
507 <para>Some code might allocate a block of memory, and use the first 8
508 bytes to store (block size - 8) as a 64bit number.
509 <computeroutput>sqlite3MemMalloc</computeroutput> does this.</para>
513 <para>It might be a pointer to an array of C++ objects (which possess
514 destructors) allocated with <computeroutput>new[]</computeroutput>. In
515 this case, some compilers store a "magic cookie" containing the array
516 length at the start of the allocated block, and return a pointer to just
517 past that magic cookie, i.e. an interior-pointer.
518 See <ulink url="https://docs.freebsd.org/info/gxxint/gxxint.info.Free_Store.html">this
519 page</ulink> for more information.</para>
523 <para>It might be a pointer to an inner part of a C++ object using
524 multiple inheritance. </para>
528 <para>You can optionally activate heuristics to use during the leak
529 search to detect the interior pointers corresponding to
530 the <computeroutput>stdstring</computeroutput>,
531 <computeroutput>length64</computeroutput>,
532 <computeroutput>newarray</computeroutput>
533 and <computeroutput>multipleinheritance</computeroutput> cases. If the
534 heuristic detects that an interior pointer corresponds to such a case,
535 the block will be considered as reachable by the interior
536 pointer. In other words, the interior pointer will be treated
537 as if it were a start pointer.</para>
540 <para>With that in mind, consider the nine possible cases described by the
541 following figure.</para>
543 <programlisting><![CDATA[
544 Pointer chain AAA Leak Case BBB Leak Case
545 ------------- ------------- -------------
546 (1) RRR ------------> BBB DR
547 (2) RRR ---> AAA ---> BBB DR IR
549 (4) RRR AAA ---> BBB DL IL
550 (5) RRR ------?-----> BBB (y)DR, (n)DL
551 (6) RRR ---> AAA -?-> BBB DR (y)IR, (n)DL
552 (7) RRR -?-> AAA ---> BBB (y)DR, (n)DL (y)IR, (n)IL
553 (8) RRR -?-> AAA -?-> BBB (y)DR, (n)DL (y,y)IR, (n,y)IL, (_,n)DL
554 (9) RRR AAA -?-> BBB DL (y)IL, (n)DL
556 Pointer chain legend:
557 - RRR: a root set node or DR block
558 - AAA, BBB: heap blocks
559 - --->: a start-pointer
560 - -?->: an interior-pointer
563 - DR: Directly reachable
564 - IR: Indirectly reachable
566 - IL: Indirectly lost
567 - (y)XY: it's XY if the interior-pointer is a real pointer
568 - (n)XY: it's XY if the interior-pointer is not a real pointer
569 - (_)XY: it's XY in either case
572 <para>Every possible case can be reduced to one of the above nine. Memcheck
573 merges some of these cases in its output, resulting in the following four
580 <para>"Still reachable". This covers cases 1 and 2 (for the BBB blocks)
581 above. A start-pointer or chain of start-pointers to the block is
582 found. Since the block is still pointed at, the programmer could, at
583 least in principle, have freed it before program exit. "Still reachable"
584 blocks are very common and arguably not a problem. So, by default,
585 Memcheck won't report such blocks individually.</para>
589 <para>"Definitely lost". This covers case 3 (for the BBB blocks) above.
590 This means that no pointer to the block can be found. The block is
591 classified as "lost", because the programmer could not possibly have
592 freed it at program exit, since no pointer to it exists. This is likely
593 a symptom of having lost the pointer at some earlier point in the
594 program. Such cases should be fixed by the programmer.</para>
598 <para>"Indirectly lost". This covers cases 4 and 9 (for the BBB blocks)
599 above. This means that the block is lost, not because there are no
600 pointers to it, but rather because all the blocks that point to it are
601 themselves lost. For example, if you have a binary tree and the root
602 node is lost, all its children nodes will be indirectly lost. Because
603 the problem will disappear if the definitely lost block that caused the
604 indirect leak is fixed, Memcheck won't report such blocks individually
609 <para>"Possibly lost". This covers cases 5--8 (for the BBB blocks)
610 above. This means that a chain of one or more pointers to the block has
611 been found, but at least one of the pointers is an interior-pointer.
612 This could just be a random value in memory that happens to point into a
613 block, and so you shouldn't consider this ok unless you know you have
614 interior-pointers.</para>
619 <para>(Note: This mapping of the nine possible cases onto four leak kinds is
620 not necessarily the best way that leaks could be reported; in particular,
621 interior-pointers are treated inconsistently. It is possible the
622 categorisation may be improved in the future.)</para>
624 <para>Furthermore, if suppressions exists for a block, it will be reported
625 as "suppressed" no matter what which of the above four kinds it belongs
629 <para>The following is an example leak summary.</para>
631 <programlisting><![CDATA[
633 definitely lost: 48 bytes in 3 blocks.
634 indirectly lost: 32 bytes in 2 blocks.
635 possibly lost: 96 bytes in 6 blocks.
636 still reachable: 64 bytes in 4 blocks.
637 suppressed: 0 bytes in 0 blocks.
640 <para>If heuristics have been used to consider some blocks as
641 reachable, the leak summary details the heuristically reachable subset
642 of 'still reachable:' per heuristic. In the below example, of the 95
643 bytes still reachable, 87 bytes (56+7+8+16) have been considered
644 heuristically reachable.
647 <programlisting><![CDATA[
649 definitely lost: 4 bytes in 1 blocks
650 indirectly lost: 0 bytes in 0 blocks
651 possibly lost: 0 bytes in 0 blocks
652 still reachable: 95 bytes in 6 blocks
653 of which reachable via heuristic:
654 stdstring : 56 bytes in 2 blocks
655 length64 : 16 bytes in 1 blocks
656 newarray : 7 bytes in 1 blocks
657 multipleinheritance: 8 bytes in 1 blocks
658 suppressed: 0 bytes in 0 blocks
661 <para>If <option>--leak-check=full</option> is specified,
662 Memcheck will give details for each definitely lost or possibly lost block,
663 including where it was allocated. (Actually, it merges results for all
664 blocks that have the same leak kind and sufficiently similar stack traces
665 into a single "loss record". The
666 <option>--leak-resolution</option> lets you control the
667 meaning of "sufficiently similar".) It cannot tell you when or how or why
668 the pointer to a leaked block was lost; you have to work that out for
669 yourself. In general, you should attempt to ensure your programs do not
670 have any definitely lost or possibly lost blocks at exit.</para>
672 <para>For example:</para>
673 <programlisting><![CDATA[
674 8 bytes in 1 blocks are definitely lost in loss record 1 of 14
675 at 0x........: malloc (vg_replace_malloc.c:...)
676 by 0x........: mk (leak-tree.c:11)
677 by 0x........: main (leak-tree.c:39)
679 88 (8 direct, 80 indirect) bytes in 1 blocks are definitely lost in loss record 13 of 14
680 at 0x........: malloc (vg_replace_malloc.c:...)
681 by 0x........: mk (leak-tree.c:11)
682 by 0x........: main (leak-tree.c:25)
685 <para>The first message describes a simple case of a single 8 byte block
686 that has been definitely lost. The second case mentions another 8 byte
687 block that has been definitely lost; the difference is that a further 80
688 bytes in other blocks are indirectly lost because of this lost block.
689 The loss records are not presented in any notable order, so the loss record
690 numbers aren't particularly meaningful. The loss record numbers can be used
691 in the Valgrind gdbserver to list the addresses of the leaked blocks and/or give
692 more details about how a block is still reachable.</para>
694 <para>The option <option>--show-leak-kinds=<set></option>
695 controls the set of leak kinds to show
696 when <option>--leak-check=full</option> is specified. </para>
698 <para>The <option><set></option> of leak kinds is specified
699 in one of the following ways:
702 <listitem><para>a comma separated list of one or more of
703 <option>definite indirect possible reachable</option>.</para>
706 <listitem><para><option>all</option> to specify the complete set (all leak kinds).</para>
709 <listitem><para><option>none</option> for the empty set.</para>
715 <para> The default value for the leak kinds to show is
716 <option>--show-leak-kinds=definite,possible</option>.
719 <para>To also show the reachable and indirectly lost blocks in
720 addition to the definitely and possibly lost blocks, you can
721 use <option>--show-leak-kinds=all</option>. To only show the
722 reachable and indirectly lost blocks, use
723 <option>--show-leak-kinds=indirect,reachable</option>. The reachable
724 and indirectly lost blocks will then be presented as shown in
725 the following two examples.</para>
727 <programlisting><![CDATA[
728 64 bytes in 4 blocks are still reachable in loss record 2 of 4
729 at 0x........: malloc (vg_replace_malloc.c:177)
730 by 0x........: mk (leak-cases.c:52)
731 by 0x........: main (leak-cases.c:74)
733 32 bytes in 2 blocks are indirectly lost in loss record 1 of 4
734 at 0x........: malloc (vg_replace_malloc.c:177)
735 by 0x........: mk (leak-cases.c:52)
736 by 0x........: main (leak-cases.c:80)
739 <para>Because there are different kinds of leaks with different
740 severities, an interesting question is: which leaks should be
741 counted as true "errors" and which should not?
744 <para> The answer to this question affects the numbers printed in
745 the <computeroutput>ERROR SUMMARY</computeroutput> line, and also the
746 effect of the <option>--error-exitcode</option> option. First, a leak
747 is only counted as a true "error"
748 if <option>--leak-check=full</option> is specified. Then, the
749 option <option>--errors-for-leak-kinds=<set></option> controls
750 the set of leak kinds to consider as errors. The default value
751 is <option>--errors-for-leak-kinds=definite,possible</option>
760 <sect1 id="mc-manual.options"
761 xreflabel="Memcheck Command-Line Options">
762 <title>Memcheck Command-Line Options</title>
764 <!-- start of xi:include in the manpage -->
765 <variablelist id="mc.opts.list">
767 <varlistentry id="opt.leak-check" xreflabel="--leak-check">
769 <option><![CDATA[--leak-check=<no|summary|yes|full> [default: summary] ]]></option>
772 <para>When enabled, search for memory leaks when the client
773 program finishes. If set to <varname>summary</varname>, it says how
774 many leaks occurred. If set to <varname>full</varname> or
775 <varname>yes</varname>, each individual leak will be shown
776 in detail and/or counted as an error, as specified by the options
777 <option>--show-leak-kinds</option> and
778 <option>--errors-for-leak-kinds</option>. </para>
779 <para>If <varname>--xml=yes</varname> is given, memcheck will
780 automatically use the value <varname>--leak-check=full</varname>.
781 You can use <option>--show-leak-kinds=none</option> to reduce
782 the size of the xml output if you are not interested in the leak
787 <varlistentry id="opt.leak-resolution" xreflabel="--leak-resolution">
789 <option><![CDATA[--leak-resolution=<low|med|high> [default: high] ]]></option>
792 <para>When doing leak checking, determines how willing
793 Memcheck is to consider different backtraces to
794 be the same for the purposes of merging multiple leaks into a single
795 leak report. When set to <varname>low</varname>, only the first
796 two entries need match. When <varname>med</varname>, four entries
797 have to match. When <varname>high</varname>, all entries need to
800 <para>For hardcore leak debugging, you probably want to use
801 <option>--leak-resolution=high</option> together with
802 <option>--num-callers=40</option> or some such large number.
805 <para>Note that the <option>--leak-resolution</option> setting
806 does not affect Memcheck's ability to find
807 leaks. It only changes how the results are presented.</para>
811 <varlistentry id="opt.show-leak-kinds" xreflabel="--show-leak-kinds">
813 <option><![CDATA[--show-leak-kinds=<set> [default: definite,possible] ]]></option>
816 <para>Specifies the leak kinds to show in a <varname>full</varname>
817 leak search, in one of the following ways: </para>
820 <listitem><para>a comma separated list of one or more of
821 <option>definite indirect possible reachable</option>.</para>
824 <listitem><para><option>all</option> to specify the complete set (all leak kinds).
826 <option>--show-leak-kinds=definite,indirect,possible,reachable</option>.</para>
829 <listitem><para><option>none</option> for the empty set.</para>
836 <varlistentry id="opt.errors-for-leak-kinds" xreflabel="--errors-for-leak-kinds">
838 <option><![CDATA[--errors-for-leak-kinds=<set> [default: definite,possible] ]]></option>
841 <para>Specifies the leak kinds to count as errors in a
842 <varname>full</varname> leak search. The
843 <option><![CDATA[<set>]]></option> is specified similarly to
844 <option>--show-leak-kinds</option>
850 <varlistentry id="opt.leak-check-heuristics" xreflabel="--leak-check-heuristics">
852 <option><![CDATA[--leak-check-heuristics=<set> [default: all] ]]></option>
855 <para>Specifies the set of leak check heuristics to be used
856 during leak searches. The heuristics control which interior pointers
857 to a block cause it to be considered as reachable.
858 The heuristic set is specified in one of the following ways:</para>
861 <listitem><para>a comma separated list of one or more of
862 <option>stdstring length64 newarray multipleinheritance</option>.</para>
865 <listitem><para><option>all</option> to activate the complete set of
868 <option>--leak-check-heuristics=stdstring,length64,newarray,multipleinheritance</option>.</para>
871 <listitem><para><option>none</option> for the empty set.</para>
874 <para>Note that these heuristics are dependent on the layout of
875 the objects produced by the C++ compiler. They have been
876 tested with some gcc versions (e.g. 4.4 and 4.7). They might
877 not work properly with other C++ compilers.
882 <varlistentry id="opt.show-reachable" xreflabel="--show-reachable">
884 <option><![CDATA[--show-reachable=<yes|no> ]]></option>
887 <option><![CDATA[--show-possibly-lost=<yes|no> ]]></option>
890 <para>These options provide an alternative way to specify the leak kinds to show:
895 <option>--show-reachable=no --show-possibly-lost=yes</option> is equivalent to
896 <option>--show-leak-kinds=definite,possible</option>.
901 <option>--show-reachable=no --show-possibly-lost=no</option> is equivalent to
902 <option>--show-leak-kinds=definite</option>.
907 <option>--show-reachable=yes</option> is equivalent to
908 <option>--show-leak-kinds=all</option>.
912 <para> Note that <option>--show-possibly-lost=no</option> has no
913 effect if <option>--show-reachable=yes</option> is
918 <varlistentry id="opt.xtree-leak" xreflabel="--xtree-leak">
920 <option><![CDATA[--xtree-leak=<no|yes> [no] ]]></option>
923 <para>If set to yes, the results for the leak search done at exit will be
924 output in a 'Callgrind Format' execution tree file. Note that this
925 automatically sets the options <option>--leak-check=full</option>
926 and <option>--show-leak-kinds=all</option>, to allow
927 xtree visualisation tools such as kcachegrind to select what kind
928 to leak to visualise.
929 The produced file will contain the following events:</para>
931 <listitem><para><option>RB</option> : Reachable Bytes</para></listitem>
932 <listitem><para><option>PB</option> : Possibly lost Bytes</para></listitem>
933 <listitem><para><option>IB</option> : Indirectly lost Bytes</para></listitem>
934 <listitem><para><option>DB</option> : Definitely lost Bytes (direct plus indirect)</para></listitem>
935 <listitem><para><option>DIB</option> : Definitely Indirectly lost Bytes (subset of DB)</para></listitem>
936 <listitem><para><option>RBk</option> : reachable Blocks</para></listitem>
937 <listitem><para><option>PBk</option> : Possibly lost Blocks</para></listitem>
938 <listitem><para><option>IBk</option> : Indirectly lost Blocks</para></listitem>
939 <listitem><para><option>DBk</option> : Definitely lost Blocks</para></listitem>
942 <para>The increase or decrease for all events above will also be output in
943 the file to provide the delta (increase or decrease) between 2
944 successive leak searches. For example, <option>iRB</option> is the
945 increase of the <option>RB</option> event, <option>dPBk</option> is the
946 decrease of <option>PBk</option> event. The values for the increase and
947 decrease events will be zero for the first leak search done.</para>
949 <para>See <xref linkend="&vg-xtree-id;"/> for a detailed explanation
950 about execution trees.</para>
954 <varlistentry id="opt.xtree-leak-file" xreflabel="--xtree-leak-file">
956 <option><![CDATA[--xtree-leak-file=<filename> [default:
957 xtleak.kcg.%p] ]]></option>
960 <para>Specifies that Valgrind should produce the xtree leak
961 report in the specified file. Any <option>%p</option>,
962 <option>%q</option> or <option>%n</option> sequences appearing in
963 the filename are expanded
964 in exactly the same way as they are for <option>--log-file</option>.
965 See the description of <xref linkend="opt.log-file"/>
967 <para>See <xref linkend="&vg-xtree-id;"/>
968 for a detailed explanation about execution trees formats. </para>
972 <varlistentry id="opt.undef-value-errors" xreflabel="--undef-value-errors">
974 <option><![CDATA[--undef-value-errors=<yes|no> [default: yes] ]]></option>
977 <para>Controls whether Memcheck reports
978 uses of undefined value errors. Set this to
979 <varname>no</varname> if you don't want to see undefined value
980 errors. It also has the side effect of speeding up Memcheck somewhat.
981 AddrCheck (removed in Valgrind 3.1.0) functioned like Memcheck with
982 <option>--undef-value-errors=no</option>.
987 <varlistentry id="opt.track-origins" xreflabel="--track-origins">
989 <option><![CDATA[--track-origins=<yes|no> [default: no] ]]></option>
992 <para>Controls whether Memcheck tracks
993 the origin of uninitialised values. By default, it does not,
994 which means that although it can tell you that an
995 uninitialised value is being used in a dangerous way, it
996 cannot tell you where the uninitialised value came from. This
997 often makes it difficult to track down the root problem.
1000 to <varname>yes</varname>, Memcheck keeps
1001 track of the origins of all uninitialised values. Then, when
1002 an uninitialised value error is
1003 reported, Memcheck will try to show the
1004 origin of the value. An origin can be one of the following
1005 four places: a heap block, a stack allocation, a client
1006 request, or miscellaneous other sources (eg, a call
1007 to <varname>brk</varname>).
1009 <para>For uninitialised values originating from a heap
1010 block, Memcheck shows where the block was
1011 allocated. For uninitialised values originating from a stack
1012 allocation, Memcheck can tell you which
1013 function allocated the value, but no more than that -- typically
1014 it shows you the source location of the opening brace of the
1015 function. So you should carefully check that all of the
1016 function's local variables are initialised properly.
1018 <para>Performance overhead: origin tracking is expensive. It
1019 halves Memcheck's speed and increases
1020 memory use by a minimum of 100MB, and possibly more.
1021 Nevertheless it can drastically reduce the effort required to
1022 identify the root cause of uninitialised value errors, and so
1023 is often a programmer productivity win, despite running
1026 <para>Accuracy: Memcheck tracks origins
1027 quite accurately. To avoid very large space and time
1028 overheads, some approximations are made. It is possible,
1029 although unlikely, that Memcheck will report an incorrect origin, or
1030 not be able to identify any origin.
1032 <para>Note that the combination
1033 <option>--track-origins=yes</option>
1034 and <option>--undef-value-errors=no</option> is
1035 nonsensical. Memcheck checks for and
1036 rejects this combination at startup.
1041 <varlistentry id="opt.partial-loads-ok" xreflabel="--partial-loads-ok">
1043 <option><![CDATA[--partial-loads-ok=<yes|no> [default: yes] ]]></option>
1046 <para>Controls how Memcheck handles 32-, 64-, 128- and 256-bit
1047 naturally aligned loads from addresses for which some bytes are
1048 addressable and others are not. When <varname>yes</varname>, such
1049 loads do not produce an address error. Instead, loaded bytes
1050 originating from illegal addresses are marked as uninitialised, and
1051 those corresponding to legal addresses are handled in the normal
1054 <para>When <varname>no</varname>, loads from partially invalid
1055 addresses are treated the same as loads from completely invalid
1056 addresses: an illegal-address error is issued, and the resulting
1057 bytes are marked as initialised.</para>
1059 <para>Note that code that behaves in this way is in violation of
1060 the ISO C/C++ standards, and should be considered broken. If
1061 at all possible, such code should be fixed.</para>
1065 <varlistentry id="opt.expensive-definedness-checks" xreflabel="--expensive-definedness-checks">
1067 <option><![CDATA[--expensive-definedness-checks=<no|auto|yes> [default: auto] ]]></option>
1070 <para>Controls whether Memcheck should employ more precise but also
1071 more expensive (time consuming) instrumentation when checking the
1072 definedness of certain values. In particular, this affects the
1073 instrumentation of integer adds, subtracts and equality
1075 <para>Selecting <option>--expensive-definedness-checks=yes</option>
1076 causes Memcheck to use the most accurate analysis possible. This
1077 minimises false error rates but can cause up to 30% performance
1079 <para>Selecting <option>--expensive-definedness-checks=no</option>
1080 causes Memcheck to use the cheapest instrumentation possible. This
1081 maximises performance but will normally give an unusably high false
1084 setting, <option>--expensive-definedness-checks=auto</option>, is
1085 strongly recommended. This causes Memcheck to use the minimum of
1086 expensive instrumentation needed to achieve the same false error
1087 rate as <option>--expensive-definedness-checks=yes</option>. It
1088 also enables an instrumentation-time analysis pass which aims to
1089 further reduce the costs of accurate instrumentation. Overall, the
1090 performance loss is generally around 5% relative to
1091 <option>--expensive-definedness-checks=no</option>, although this is
1092 strongly workload dependent. Note that the exact instrumentation
1093 settings in this mode are architecture dependent.</para>
1097 <varlistentry id="opt.keep-stacktraces" xreflabel="--keep-stacktraces">
1099 <option><![CDATA[--keep-stacktraces=alloc|free|alloc-and-free|alloc-then-free|none [default: alloc-and-free] ]]></option>
1102 <para>Controls which stack trace(s) to keep for malloc'd and/or
1106 <para>With <varname>alloc-then-free</varname>, a stack trace is
1107 recorded at allocation time, and is associated with the block.
1108 When the block is freed, a second stack trace is recorded, and
1109 this replaces the allocation stack trace. As a result, any "use
1110 after free" errors relating to this block can only show a stack
1111 trace for where the block was freed.
1114 <para>With <varname>alloc-and-free</varname>, both allocation
1115 and the deallocation stack traces for the block are stored.
1116 Hence a "use after free" error will
1117 show both, which may make the error easier to diagnose.
1118 Compared to <varname>alloc-then-free</varname>, this setting
1119 slightly increases Valgrind's memory use as the block contains two
1120 references instead of one.
1123 <para>With <varname>alloc</varname>, only the allocation stack
1124 trace is recorded (and reported). With <varname>free</varname>,
1125 only the deallocation stack trace is recorded (and reported).
1126 These values somewhat decrease Valgrind's memory and cpu usage.
1127 They can be useful depending on the error types you are
1128 searching for and the level of detail you need to analyse
1129 them. For example, if you are only interested in memory leak
1130 errors, it is sufficient to record the allocation stack traces.
1133 <para>With <varname>none</varname>, no stack traces are recorded
1134 for malloc and free operations. If your program allocates a lot
1135 of blocks and/or allocates/frees from many different stack
1136 traces, this can significantly decrease cpu and/or memory
1137 required. Of course, few details will be reported for errors
1138 related to heap blocks.
1141 <para>Note that once a stack trace is recorded, Valgrind keeps
1142 the stack trace in memory even if it is not referenced by any
1143 block. Some programs (for example, recursive algorithms) can
1144 generate a huge number of stack traces. If Valgrind uses too
1145 much memory in such circumstances, you can reduce the memory
1146 required with the options <varname>--keep-stacktraces</varname>
1147 and/or by using a smaller value for the
1148 option <varname>--num-callers</varname>.
1151 <para>If you want to use
1152 <computeroutput>--xtree-memory=full</computeroutput> memory profiling
1153 (see <xref linkend="&vg-xtree-id;"/>), then you cannot
1154 specify <varname>--keep-stacktraces=free</varname>
1155 or <varname>--keep-stacktraces=none</varname>.</para>
1160 <varlistentry id="opt.freelist-vol" xreflabel="--freelist-vol">
1162 <option><![CDATA[--freelist-vol=<number> [default: 20000000] ]]></option>
1165 <para>When the client program releases memory using
1166 <function>free</function> (in <literal>C</literal>) or
1167 <computeroutput>delete</computeroutput>
1168 (<literal>C++</literal>), that memory is not immediately made
1169 available for re-allocation. Instead, it is marked inaccessible
1170 and placed in a queue of freed blocks. The purpose is to defer as
1171 long as possible the point at which freed-up memory comes back
1172 into circulation. This increases the chance that
1173 Memcheck will be able to detect invalid
1174 accesses to blocks for some significant period of time after they
1175 have been freed.</para>
1177 <para>This option specifies the maximum total size, in bytes, of the
1178 blocks in the queue. The default value is twenty million bytes.
1179 Increasing this increases the total amount of memory used by
1180 Memcheck but may detect invalid uses of freed
1181 blocks which would otherwise go undetected.</para>
1185 <varlistentry id="opt.freelist-big-blocks" xreflabel="--freelist-big-blocks">
1187 <option><![CDATA[--freelist-big-blocks=<number> [default: 1000000] ]]></option>
1190 <para>When making blocks from the queue of freed blocks available
1191 for re-allocation, Memcheck will in priority re-circulate the blocks
1192 with a size greater or equal to <option>--freelist-big-blocks</option>.
1193 This ensures that freeing big blocks (in particular freeing blocks bigger than
1194 <option>--freelist-vol</option>) does not immediately lead to a re-circulation
1195 of all (or a lot of) the small blocks in the free list. In other words,
1196 this option increases the likelihood to discover dangling pointers
1197 for the "small" blocks, even when big blocks are freed.</para>
1198 <para>Setting a value of 0 means that all the blocks are re-circulated
1199 in a FIFO order. </para>
1203 <varlistentry id="opt.workaround-gcc296-bugs" xreflabel="--workaround-gcc296-bugs">
1205 <option><![CDATA[--workaround-gcc296-bugs=<yes|no> [default: no] ]]></option>
1208 <para>When enabled, assume that reads and writes some small
1209 distance below the stack pointer are due to bugs in GCC 2.96, and
1210 does not report them. The "small distance" is 256 bytes by
1211 default. Note that GCC 2.96 is the default compiler on some ancient
1212 Linux distributions (RedHat 7.X) and so you may need to use this
1213 option. Do not use it if you do not have to, as it can cause real
1214 errors to be overlooked. A better alternative is to use a more
1215 recent GCC in which this bug is fixed.</para>
1217 <para>You may also need to use this option when working with
1218 GCC 3.X or 4.X on 32-bit PowerPC Linux. This is because
1219 GCC generates code which occasionally accesses below the
1220 stack pointer, particularly for floating-point to/from integer
1221 conversions. This is in violation of the 32-bit PowerPC ELF
1222 specification, which makes no provision for locations below the
1223 stack pointer to be accessible.</para>
1225 <para>This option is deprecated as of version 3.12 and may be
1226 removed from future versions. You should instead use
1227 <option>--ignore-range-below-sp</option> to specify the exact
1228 range of offsets below the stack pointer that should be ignored.
1229 A suitable equivalent
1230 is <option>--ignore-range-below-sp=1024-1</option>.
1235 <varlistentry id="opt.ignore-range-below-sp"
1236 xreflabel="--ignore-range-below-sp">
1238 <option><![CDATA[--ignore-range-below-sp=<number>-<number> ]]></option>
1241 <para>This is a more general replacement for the deprecated
1242 <option>--workaround-gcc296-bugs</option> option. When
1243 specified, it causes Memcheck not to report errors for accesses
1244 at the specified offsets below the stack pointer. The two
1245 offsets must be positive decimal numbers and -- somewhat
1246 counterintuitively -- the first one must be larger, in order to
1247 imply a non-wraparound address range to ignore. For example,
1248 to ignore 4 byte accesses at 8192 bytes below the stack
1250 use <option>--ignore-range-below-sp=8192-8189</option>. Only
1251 one range may be specified.
1256 <varlistentry id="opt.show-mismatched-frees"
1257 xreflabel="--show-mismatched-frees">
1259 <option><![CDATA[--show-mismatched-frees=<yes|no> [default: yes] ]]></option>
1262 <para>When enabled, Memcheck checks that heap blocks are
1263 deallocated using a function that matches the allocating
1264 function. That is, it expects <varname>free</varname> to be
1265 used to deallocate blocks allocated
1266 by <varname>malloc</varname>, <varname>delete</varname> for
1267 blocks allocated by <varname>new</varname>,
1268 and <varname>delete[]</varname> for blocks allocated
1269 by <varname>new[]</varname>. If a mismatch is detected, an
1270 error is reported. This is in general important because in some
1271 environments, freeing with a non-matching function can cause
1274 <para>There is however a scenario where such mismatches cannot
1275 be avoided. That is when the user provides implementations of
1276 <varname>new</varname>/<varname>new[]</varname> that
1277 call <varname>malloc</varname> and
1278 of <varname>delete</varname>/<varname>delete[]</varname> that
1279 call <varname>free</varname>, and these functions are
1280 asymmetrically inlined. For example, imagine
1281 that <varname>delete[]</varname> is inlined
1282 but <varname>new[]</varname> is not. The result is that
1283 Memcheck "sees" all <varname>delete[]</varname> calls as direct
1284 calls to <varname>free</varname>, even when the program source
1285 contains no mismatched calls.</para>
1287 <para>This causes a lot of confusing and irrelevant error
1288 reports. <varname>--show-mismatched-frees=no</varname> disables
1289 these checks. It is not generally advisable to disable them,
1290 though, because you may miss real errors as a result.</para>
1294 <varlistentry id="opt.ignore-ranges" xreflabel="--ignore-ranges">
1296 <option><![CDATA[--ignore-ranges=0xPP-0xQQ[,0xRR-0xSS] ]]></option>
1299 <para>Any ranges listed in this option (and multiple ranges can be
1300 specified, separated by commas) will be ignored by Memcheck's
1301 addressability checking.</para>
1305 <varlistentry id="opt.malloc-fill" xreflabel="--malloc-fill">
1307 <option><![CDATA[--malloc-fill=<hexnumber> ]]></option>
1310 <para>Fills blocks allocated
1311 by <computeroutput>malloc</computeroutput>,
1312 <computeroutput>new</computeroutput>, etc, but not
1313 by <computeroutput>calloc</computeroutput>, with the specified
1314 byte. This can be useful when trying to shake out obscure
1315 memory corruption problems. The allocated area is still
1316 regarded by Memcheck as undefined -- this option only affects its
1317 contents. Note that <option>--malloc-fill</option> does not
1318 affect a block of memory when it is used as argument
1319 to client requests VALGRIND_MEMPOOL_ALLOC or
1320 VALGRIND_MALLOCLIKE_BLOCK.
1325 <varlistentry id="opt.free-fill" xreflabel="--free-fill">
1327 <option><![CDATA[--free-fill=<hexnumber> ]]></option>
1330 <para>Fills blocks freed
1331 by <computeroutput>free</computeroutput>,
1332 <computeroutput>delete</computeroutput>, etc, with the
1333 specified byte value. This can be useful when trying to shake out
1334 obscure memory corruption problems. The freed area is still
1335 regarded by Memcheck as not valid for access -- this option only
1336 affects its contents. Note that <option>--free-fill</option> does not
1337 affect a block of memory when it is used as argument to
1338 client requests VALGRIND_MEMPOOL_FREE or VALGRIND_FREELIKE_BLOCK.
1344 <!-- end of xi:include in the manpage -->
1349 <sect1 id="mc-manual.suppfiles" xreflabel="Writing suppression files">
1350 <title>Writing suppression files</title>
1352 <para>The basic suppression format is described in
1353 <xref linkend="manual-core.suppress"/>.</para>
1355 <para>The suppression-type (second) line should have the form:</para>
1356 <programlisting><![CDATA[
1357 Memcheck:suppression_type]]></programlisting>
1359 <para>The Memcheck suppression types are as follows:</para>
1363 <para><varname>Value1</varname>,
1364 <varname>Value2</varname>,
1365 <varname>Value4</varname>,
1366 <varname>Value8</varname>,
1367 <varname>Value16</varname>,
1368 meaning an uninitialised-value error when
1369 using a value of 1, 2, 4, 8 or 16 bytes.</para>
1373 <para><varname>Cond</varname> (or its old
1374 name, <varname>Value0</varname>), meaning use
1375 of an uninitialised CPU condition code.</para>
1379 <para><varname>Addr1</varname>,
1380 <varname>Addr2</varname>,
1381 <varname>Addr4</varname>,
1382 <varname>Addr8</varname>,
1383 <varname>Addr16</varname>,
1384 meaning an invalid address during a
1385 memory access of 1, 2, 4, 8 or 16 bytes respectively.</para>
1389 <para><varname>Jump</varname>, meaning an
1390 jump to an unaddressable location error.</para>
1394 <para><varname>Param</varname>, meaning an
1395 invalid system call parameter error.</para>
1399 <para><varname>Free</varname>, meaning an
1400 invalid or mismatching free.</para>
1404 <para><varname>Overlap</varname>, meaning a
1405 <computeroutput>src</computeroutput> /
1406 <computeroutput>dst</computeroutput> overlap in
1407 <function>memcpy</function> or a similar function.</para>
1411 <para><varname>Leak</varname>, meaning
1412 a memory leak.</para>
1417 <para><computeroutput>Param</computeroutput> errors have a mandatory extra
1418 information line at this point, which is the name of the offending
1419 system call parameter. </para>
1421 <para><computeroutput>Leak</computeroutput> errors have an optional
1422 extra information line, with the following format:</para>
1423 <programlisting><![CDATA[
1424 match-leak-kinds:<set>]]></programlisting>
1425 <para>where <computeroutput><set></computeroutput> specifies which
1426 leak kinds are matched by this suppression entry.
1427 <computeroutput><set></computeroutput> is specified in the
1428 same way as with the option <option>--show-leak-kinds</option>, that is,
1429 one of the following:</para>
1431 <listitem><para>a comma separated list of one or more of
1432 <option>definite indirect possible reachable</option>.</para>
1435 <listitem><para><option>all</option> to specify the complete set
1436 (all leak kinds).</para>
1439 <listitem><para><option>none</option> for the empty set.</para>
1442 <para>If this optional extra line is not present, the suppression
1443 entry will match all leak kinds.</para>
1445 <para>Be aware that leak suppressions that are created using
1446 <option>--gen-suppressions</option> will contain this optional extra
1447 line, and therefore may match fewer leaks than you expect. You may
1448 want to remove the line before using the generated
1449 suppressions.</para>
1451 <para>The other Memcheck error kinds do not have extra lines.</para>
1454 If you give the <option>-v</option> option, Valgrind will print
1455 the list of used suppressions at the end of execution.
1456 For a leak suppression, this output gives the number of different
1457 loss records that match the suppression, and the number of bytes
1458 and blocks suppressed by the suppression.
1459 If the run contains multiple leak checks, the number of bytes and blocks
1460 are reset to zero before each new leak check. Note that the number of different
1461 loss records is not reset to zero.</para>
1462 <para>In the example below, in the last leak search, 7 blocks and 96 bytes have
1463 been suppressed by a suppression with the name
1464 <option>some_leak_suppression</option>:</para>
1465 <programlisting><![CDATA[
1466 --21041-- used_suppression: 10 some_other_leak_suppression s.supp:14 suppressed: 12,400 bytes in 1 blocks
1467 --21041-- used_suppression: 39 some_leak_suppression s.supp:2 suppressed: 96 bytes in 7 blocks
1468 ]]></programlisting>
1470 <para>For <varname>ValueN</varname> and <varname>AddrN</varname>
1471 errors, the first line of the calling context is either the name of
1472 the function in which the error occurred, or, failing that, the full
1473 path of the <filename>.so</filename> file or executable containing the
1474 error location. For <varname>Free</varname> errors, the first line is
1475 the name of the function doing the freeing (eg,
1476 <function>free</function>, <function>__builtin_vec_delete</function>,
1477 etc). For <varname>Overlap</varname> errors, the first line is the name of the
1478 function with the overlapping arguments (eg.
1479 <function>memcpy</function>, <function>strcpy</function>, etc).</para>
1481 <para>The last part of any suppression specifies the rest of the
1482 calling context that needs to be matched.</para>
1488 <sect1 id="mc-manual.machine"
1489 xreflabel="Details of Memcheck's checking machinery">
1490 <title>Details of Memcheck's checking machinery</title>
1492 <para>Read this section if you want to know, in detail, exactly
1493 what and how Memcheck is checking.</para>
1496 <sect2 id="mc-manual.value" xreflabel="Valid-value (V) bit">
1497 <title>Valid-value (V) bits</title>
1499 <para>It is simplest to think of Memcheck implementing a synthetic CPU
1500 which is identical to a real CPU, except for one crucial detail. Every
1501 bit (literally) of data processed, stored and handled by the real CPU
1502 has, in the synthetic CPU, an associated "valid-value" bit, which says
1503 whether or not the accompanying bit has a legitimate value. In the
1504 discussions which follow, this bit is referred to as the V (valid-value)
1507 <para>Each byte in the system therefore has a 8 V bits which follow it
1508 wherever it goes. For example, when the CPU loads a word-size item (4
1509 bytes) from memory, it also loads the corresponding 32 V bits from a
1510 bitmap which stores the V bits for the process' entire address space.
1511 If the CPU should later write the whole or some part of that value to
1512 memory at a different address, the relevant V bits will be stored back
1513 in the V-bit bitmap.</para>
1515 <para>In short, each bit in the system has (conceptually) an associated V
1516 bit, which follows it around everywhere, even inside the CPU. Yes, all the
1517 CPU's registers (integer, floating point, vector and condition registers)
1518 have their own V bit vectors. For this to work, Memcheck uses a great deal
1519 of compression to represent the V bits compactly.</para>
1521 <para>Copying values around does not cause Memcheck to check for, or
1522 report on, errors. However, when a value is used in a way which might
1523 conceivably affect your program's externally-visible behaviour,
1524 the associated V bits are immediately checked. If any of these indicate
1525 that the value is undefined (even partially), an error is reported.</para>
1527 <para>Here's an (admittedly nonsensical) example:</para>
1528 <programlisting><![CDATA[
1531 for ( i = 0; i < 10; i++ ) {
1534 }]]></programlisting>
1536 <para>Memcheck emits no complaints about this, since it merely copies
1537 uninitialised values from <varname>a[]</varname> into
1538 <varname>b[]</varname>, and doesn't use them in a way which could
1539 affect the behaviour of the program. However, if
1540 the loop is changed to:</para>
1541 <programlisting><![CDATA[
1542 for ( i = 0; i < 10; i++ ) {
1546 printf("hello there\n");
1547 ]]></programlisting>
1549 <para>then Memcheck will complain, at the
1550 <computeroutput>if</computeroutput>, that the condition depends on
1551 uninitialised values. Note that it <command>doesn't</command> complain
1552 at the <varname>j += a[i];</varname>, since at that point the
1553 undefinedness is not "observable". It's only when a decision has to be
1554 made as to whether or not to do the <function>printf</function> -- an
1555 observable action of your program -- that Memcheck complains.</para>
1557 <para>Most low level operations, such as adds, cause Memcheck to use the
1558 V bits for the operands to calculate the V bits for the result. Even if
1559 the result is partially or wholly undefined, it does not
1562 <para>Checks on definedness only occur in three places: when a value is
1563 used to generate a memory address, when control flow decision needs to
1564 be made, and when a system call is detected, Memcheck checks definedness
1565 of parameters as required.</para>
1567 <para>If a check should detect undefinedness, an error message is
1568 issued. The resulting value is subsequently regarded as well-defined.
1569 To do otherwise would give long chains of error messages. In other
1570 words, once Memcheck reports an undefined value error, it tries to
1571 avoid reporting further errors derived from that same undefined
1574 <para>This sounds overcomplicated. Why not just check all reads from
1575 memory, and complain if an undefined value is loaded into a CPU
1576 register? Well, that doesn't work well, because perfectly legitimate C
1577 programs routinely copy uninitialised values around in memory, and we
1578 don't want endless complaints about that. Here's the canonical example.
1579 Consider a struct like this:</para>
1580 <programlisting><![CDATA[
1581 struct S { int x; char c; };
1586 ]]></programlisting>
1588 <para>The question to ask is: how large is <varname>struct S</varname>,
1589 in bytes? An <varname>int</varname> is 4 bytes and a
1590 <varname>char</varname> one byte, so perhaps a <varname>struct
1591 S</varname> occupies 5 bytes? Wrong. All non-toy compilers we know
1592 of will round the size of <varname>struct S</varname> up to a whole
1593 number of words, in this case 8 bytes. Not doing this forces compilers
1594 to generate truly appalling code for accessing arrays of
1595 <varname>struct S</varname>'s on some architectures.</para>
1597 <para>So <varname>s1</varname> occupies 8 bytes, yet only 5 of them will
1598 be initialised. For the assignment <varname>s2 = s1</varname>, GCC
1599 generates code to copy all 8 bytes wholesale into <varname>s2</varname>
1600 without regard for their meaning. If Memcheck simply checked values as
1601 they came out of memory, it would yelp every time a structure assignment
1602 like this happened. So the more complicated behaviour described above
1603 is necessary. This allows GCC to copy
1604 <varname>s1</varname> into <varname>s2</varname> any way it likes, and a
1605 warning will only be emitted if the uninitialised values are later
1608 <para>As explained above, Memcheck maintains 8 V bits for each byte in your
1609 process, including for bytes that are in shared memory. However, the same piece
1610 of shared memory can be mapped multiple times, by several processes or even by
1611 the same process (for example, if the process wants a read-only and a read-write
1612 mapping of the same page). For such multiple mappings, Memcheck tracks the V
1613 bits for each mapping independently. This can lead to false positive errors, as
1614 the shared memory can be initialised via a first mapping, and accessed via
1615 another mapping. The access via this other mapping will have its own V bits,
1616 which have not been changed when the memory was initialised via the first
1617 mapping. The bypass for these false positives is to use Memcheck's client
1618 requests <varname>VALGRIND_MAKE_MEM_DEFINED</varname> and
1619 <varname>VALGRIND_MAKE_MEM_UNDEFINED</varname> to inform
1620 Memcheck about what your program does (or what another process does)
1621 to these shared memory mappings.
1627 <sect2 id="mc-manual.vaddress" xreflabel=" Valid-address (A) bits">
1628 <title>Valid-address (A) bits</title>
1630 <para>Notice that the previous subsection describes how the validity of
1631 values is established and maintained without having to say whether the
1632 program does or does not have the right to access any particular memory
1633 location. We now consider the latter question.</para>
1635 <para>As described above, every bit in memory or in the CPU has an
1636 associated valid-value (V) bit. In addition, all bytes in memory, but
1637 not in the CPU, have an associated valid-address (A) bit. This
1638 indicates whether or not the program can legitimately read or write that
1639 location. It does not give any indication of the validity of the data
1640 at that location -- that's the job of the V bits -- only whether or not
1641 the location may be accessed.</para>
1643 <para>Every time your program reads or writes memory, Memcheck checks
1644 the A bits associated with the address. If any of them indicate an
1645 invalid address, an error is emitted. Note that the reads and writes
1646 themselves do not change the A bits, only consult them.</para>
1648 <para>So how do the A bits get set/cleared? Like this:</para>
1652 <para>When the program starts, all the global data areas are
1653 marked as accessible.</para>
1657 <para>When the program does
1658 <function>malloc</function>/<computeroutput>new</computeroutput>,
1659 the A bits for exactly the area allocated, and not a byte more,
1660 are marked as accessible. Upon freeing the area the A bits are
1661 changed to indicate inaccessibility.</para>
1665 <para>When the stack pointer register (<literal>SP</literal>) moves
1666 up or down, A bits are set. The rule is that the area from
1667 <literal>SP</literal> up to the base of the stack is marked as
1668 accessible, and below <literal>SP</literal> is inaccessible. (If
1669 that sounds illogical, bear in mind that the stack grows down, not
1670 up, on almost all Unix systems, including GNU/Linux.) Tracking
1671 <literal>SP</literal> like this has the useful side-effect that the
1672 section of stack used by a function for local variables etc is
1673 automatically marked accessible on function entry and inaccessible
1678 <para>When doing system calls, A bits are changed appropriately.
1679 For example, <literal>mmap</literal>
1680 magically makes files appear in the process'
1681 address space, so the A bits must be updated if <literal>mmap</literal>
1686 <para>Optionally, your program can tell Memcheck about such changes
1687 explicitly, using the client request mechanism described
1696 <sect2 id="mc-manual.together" xreflabel="Putting it all together">
1697 <title>Putting it all together</title>
1699 <para>Memcheck's checking machinery can be summarised as
1704 <para>Each byte in memory has 8 associated V (valid-value) bits,
1705 saying whether or not the byte has a defined value, and a single A
1706 (valid-address) bit, saying whether or not the program currently has
1707 the right to read/write that address. As mentioned above, heavy
1708 use of compression means the overhead is typically around 25%.</para>
1712 <para>When memory is read or written, the relevant A bits are
1713 consulted. If they indicate an invalid address, Memcheck emits an
1714 Invalid read or Invalid write error.</para>
1718 <para>When memory is read into the CPU's registers, the relevant V
1719 bits are fetched from memory and stored in the simulated CPU. They
1720 are not consulted.</para>
1724 <para>When a register is written out to memory, the V bits for that
1725 register are written back to memory too.</para>
1729 <para>When values in CPU registers are used to generate a memory
1730 address, or to determine the outcome of a conditional branch, the V
1731 bits for those values are checked, and an error emitted if any of
1732 them are undefined.</para>
1736 <para>When values in CPU registers are used for any other purpose,
1737 Memcheck computes the V bits for the result, but does not check
1742 <para>Once the V bits for a value in the CPU have been checked, they
1743 are then set to indicate validity. This avoids long chains of
1748 <para>When values are loaded from memory, Memcheck checks the A bits
1749 for that location and issues an illegal-address warning if needed.
1750 In that case, the V bits loaded are forced to indicate Valid,
1751 despite the location being invalid.</para>
1753 <para>This apparently strange choice reduces the amount of confusing
1754 information presented to the user. It avoids the unpleasant
1755 phenomenon in which memory is read from a place which is both
1756 unaddressable and contains invalid values, and, as a result, you get
1757 not only an invalid-address (read/write) error, but also a
1758 potentially large set of uninitialised-value errors, one for every
1759 time the value is used.</para>
1761 <para>There is a hazy boundary case to do with multi-byte loads from
1762 addresses which are partially valid and partially invalid. See
1763 details of the option <option>--partial-loads-ok</option> for details.
1770 <para>Memcheck intercepts calls to <function>malloc</function>,
1771 <function>calloc</function>, <function>realloc</function>,
1772 <function>valloc</function>, <function>memalign</function>,
1773 <function>free</function>, <computeroutput>new</computeroutput>,
1774 <computeroutput>new[]</computeroutput>,
1775 <computeroutput>delete</computeroutput> and
1776 <computeroutput>delete[]</computeroutput>. The behaviour you get
1782 <para><function>malloc</function>/<function>new</function>/<computeroutput>new[]</computeroutput>:
1783 the returned memory is marked as addressable but not having valid
1784 values. This means you have to write to it before you can read
1789 <para><function>calloc</function>: returned memory is marked both
1790 addressable and valid, since <function>calloc</function> clears
1791 the area to zero.</para>
1795 <para><function>realloc</function>: if the new size is larger than
1796 the old, the new section is addressable but invalid, as with
1797 <function>malloc</function>. If the new size is smaller, the
1798 dropped-off section is marked as unaddressable. You may only pass to
1799 <function>realloc</function> a pointer previously issued to you by
1800 <function>malloc</function>/<function>calloc</function>/<function>realloc</function>.</para>
1804 <para><function>free</function>/<computeroutput>delete</computeroutput>/<computeroutput>delete[]</computeroutput>:
1805 you may only pass to these functions a pointer previously issued
1806 to you by the corresponding allocation function. Otherwise,
1807 Memcheck complains. If the pointer is indeed valid, Memcheck
1808 marks the entire area it points at as unaddressable, and places
1809 the block in the freed-blocks-queue. The aim is to defer as long
1810 as possible reallocation of this block. Until that happens, all
1811 attempts to access it will elicit an invalid-address error, as you
1820 <sect1 id="mc-manual.monitor-commands" xreflabel="Memcheck Monitor Commands">
1821 <title>Memcheck Monitor Commands</title>
1822 <para>The Memcheck tool provides monitor commands handled by Valgrind's built-in
1823 gdbserver (see <xref linkend="manual-core-adv.gdbserver-commandhandling"/>).
1824 Valgrind python code provides GDB front end commands giving an easier usage of
1825 the memcheck monitor commands (see
1826 <xref linkend="manual-core-adv.gdbserver-gdbmonitorfrontend"/>). To launch a
1827 memcheck monitor command via its GDB front end command, instead of prefixing
1828 the command with "monitor", you must use the GDB <varname>memcheck</varname>
1829 command (or the shorter aliases <varname>mc</varname>). Using the memcheck
1830 GDB front end command provide a more flexible usage, such as evaluation of
1831 address and length arguments by GDB. In GDB, you can use <varname>help
1832 memcheck</varname> to get help about the memcheck front end monitor commands
1833 and you can use <varname>apropos memcheck</varname> to get all the commands
1834 mentionning the word "memcheck" in their name or on-line help.
1839 <para><varname>xb <addr> [<len>]</varname>
1840 shows the definedness (V) bits and values for <len> (default 1)
1841 bytes starting at <addr>.
1842 For each 8 bytes, two lines are output.
1845 The first line shows the validity bits for 8 bytes.
1846 The definedness of each byte in the range is given using two hexadecimal
1847 digits. These hexadecimal digits encode the validity of each bit of the
1849 using 0 if the bit is defined and 1 if the bit is undefined.
1850 If a byte is not addressable, its validity bits are replaced
1851 by <varname>__</varname> (a double underscore).
1854 The second line shows the values of the bytes below the corresponding
1855 validity bits. The format used to show the bytes data is similar to the
1856 GDB command 'x /<len>xb <addr>'. The value for a non
1857 addressable bytes is shown as ?? (two question marks).
1860 In the following example, <varname>string10</varname> is an array
1861 of 10 characters, in which the even numbered bytes are
1862 undefined. In the below example, the byte corresponding
1863 to <varname>string10[5]</varname> is not addressable.
1865 <programlisting><![CDATA[
1867 $4 = (char (*)[10]) 0x804a2f0
1868 (gdb) mo xb 0x804a2f0 10
1869 ff 00 ff 00 ff __ ff 00
1870 0x804A2F0: 0x3f 0x6e 0x3f 0x65 0x3f 0x?? 0x3f 0x65
1872 0x804A2F8: 0x3f 0x00
1873 Address 0x804A2F0 len 10 has 1 bytes unaddressable
1875 ]]></programlisting>
1877 <para>The GDB memcheck front end command <varname>memcheck xb ADDR
1878 [LEN]</varname> accepts any address expression for its first ADDR
1879 argument. The second optional argument is any integer expression. Note
1880 that these 2 arguments must be separated by a space.
1881 The following example shows how to get the definedness of
1882 <varname>string10</varname> using the memcheck xb front end command.
1884 <programlisting><![CDATA[
1885 (gdb) mc xb &string10 sizeof(string10)
1886 ff 00 ff 00 ff __ ff 00
1887 0x804A2F0: 0x3f 0x6e 0x3f 0x65 0x3f 0x?? 0x3f 0x65
1889 0x804A2F8: 0x3f 0x00
1890 Address 0x804A2F0 len 10 has 1 bytes unaddressable
1892 ]]></programlisting>
1894 <para> The command xb cannot be used with registers. To get
1895 the validity bits of a register, you must start Valgrind with the
1896 option <option>--vgdb-shadow-registers=yes</option>. The validity
1897 bits of a register can then be obtained by printing the 'shadow 1'
1898 corresponding register. In the below x86 example, the register
1899 eax has all its bits undefined, while the register ebx is fully
1902 <programlisting><![CDATA[
1908 ]]></programlisting>
1913 <para><varname>get_vbits <addr> [<len>]</varname>
1914 shows the definedness (V) bits for <len> (default 1) bytes
1915 starting at <addr> using the same convention as the
1916 <varname>xb</varname> command. <varname>get_vbits</varname> only
1917 shows the V bits (grouped by 4 bytes). It does not show the values.
1918 If you want to associate V bits with the corresponding byte values, the
1919 <varname>xb</varname> command will be easier to use, in particular
1920 on little endian computers when associating undefined parts of an integer
1921 with their V bits values.
1924 The following example shows the result of <varname>get_vbits</varname> on
1925 the <varname>string10</varname> used in the <varname>xb</varname> command
1926 explanation. The GDB memcheck equivalent front end command <varname>memcheck
1927 get_vbits ADDR [LEN]</varname>accepts any ADDR expression and any LEN
1928 expression (separated by a space).
1930 <programlisting><![CDATA[
1931 (gdb) monitor get_vbits 0x804a2f0 10
1932 ff00ff00 ff__ff00 ff00
1933 Address 0x804A2F0 len 10 has 1 bytes unaddressable
1934 (gdb) memcheck get_vbits &string10 sizeof(string10)
1935 ff00ff00 ff__ff00 ff00
1936 Address 0x804A2F0 len 10 has 1 bytes unaddressable
1937 ]]></programlisting>
1942 <para><varname>make_memory
1943 [noaccess|undefined|defined|Definedifaddressable] <addr>
1944 [<len>]</varname> marks the range of <len> (default 1)
1945 bytes at <addr> as having the given status. Parameter
1946 <varname>noaccess</varname> marks the range as non-accessible, so
1947 Memcheck will report an error on any access to it.
1948 <varname>undefined</varname> or <varname>defined</varname> mark
1949 the area as accessible, but Memcheck regards the bytes in it
1950 respectively as having undefined or defined values.
1951 <varname>Definedifaddressable</varname> marks as defined, bytes in
1952 the range which are already addressible, but makes no change to
1953 the status of bytes in the range which are not addressible. Note
1954 that the first letter of <varname>Definedifaddressable</varname>
1955 is an uppercase D to avoid confusion with <varname>defined</varname>.
1958 <para>The GDB equivalent memcheck front end commands <varname>memcheck
1959 make_memory [noaccess|undefined|defined|Definedifaddressable] ADDR
1960 [LEN]</varname> accept any address expression for their first ADDR
1961 argument. The second optional argument is any integer expression. Note
1962 that these 2 arguments must be separated by a space.
1966 In the following example, the first byte of the
1967 <varname>string10</varname> is marked as defined and then is marked
1970 <programlisting><![CDATA[
1971 (gdb) monitor make_memory defined 0x8049e28 1
1972 (gdb) monitor get_vbits 0x8049e28 10
1973 0000ff00 ff00ff00 ff00
1974 (gdb) memcheck make_memory noaccess &string10[0]
1975 (gdb) memcheck get_vbits &string10 sizeof(string10)
1976 __00ff00 ff00ff00 ff00
1977 Address 0x8049E28 len 10 has 1 bytes unaddressable
1979 ]]></programlisting>
1983 <para><varname>check_memory [addressable|defined] <addr>
1984 [<len>]</varname> checks that the range of <len>
1985 (default 1) bytes at <addr> has the specified accessibility.
1986 It then outputs a description of <addr>. In the following
1987 example, a detailed description is available because the
1988 option <option>--read-var-info=yes</option> was given at Valgrind
1991 <programlisting><![CDATA[
1992 (gdb) monitor check_memory defined 0x8049e28 1
1993 Address 0x8049E28 len 1 defined
1994 ==14698== Location 0x8049e28 is 0 bytes inside string10[0],
1995 ==14698== declared at prog.c:10, in frame #0 of thread 1
1997 ]]></programlisting>
1998 <para>The GDB equivalent memcheck front end commands <varname>memcheck
1999 check_memory [addressable|defined] ADDR [LEN]</varname> accept any address
2000 expression for their first ADDR argument. The second optional argument is
2001 any integer expression. Note that these 2 arguments must be separated by a
2008 <para><varname>leak_check [full*|summary|xtleak]
2009 [kinds <set>|reachable|possibleleak*|definiteleak]
2010 [heuristics heur1,heur2,...]
2011 [new|increased*|changed|any]
2012 [unlimited*|limited <max_loss_records_output>]
2014 performs a leak check. The <varname>*</varname> in the arguments
2015 indicates the default values. </para>
2017 <para> If the <varname>[full*|summary|xtleak]</varname> argument is
2018 <varname>summary</varname>, only a summary of the leak search is given;
2019 otherwise a full leak report is produced. A full leak report gives
2020 detailed information for each leak: the stack trace where the leaked blocks
2021 were allocated, the number of blocks leaked and their total size. When a
2022 full report is requested, the next two arguments further specify what
2023 kind of leaks to report. A leak's details are shown if they match
2024 both the second and third argument. A full leak report might
2025 output detailed information for many leaks. The nr of leaks for
2026 which information is output can be controlled using
2027 the <varname>limited</varname> argument followed by the maximum nr
2028 of leak records to output. If this maximum is reached, the leak
2029 search outputs the records with the biggest number of bytes.
2031 <para>The value <varname>xtleak</varname> also produces a full leak report,
2032 but output it as an xtree in a file xtleak.kcg.%p.%n (see <xref linkend="opt.log-file"/>).
2033 See <xref linkend="&vg-xtree-id;"/>
2034 for a detailed explanation about execution trees formats.
2035 See <xref linkend="opt.xtree-leak"/> for the description of the events
2036 in a xtree leak file.
2039 <para>The <varname>kinds</varname> argument controls what kind of blocks
2040 are shown for a <varname>full</varname> leak search. The set of leak kinds
2041 to show can be specified using a <varname><set></varname> similarly
2042 to the command line option <option>--show-leak-kinds</option>.
2043 Alternatively, the value <varname>definiteleak</varname>
2044 is equivalent to <varname>kinds definite</varname>, the
2045 value <varname>possibleleak</varname> is equivalent to
2046 <varname>kinds definite,possible</varname> : it will also show
2047 possibly leaked blocks, .i.e those for which only an interior
2048 pointer was found. The value <varname>reachable</varname> will
2049 show all block categories (i.e. is equivalent to <varname>kinds
2053 <para>The <varname>heuristics</varname> argument controls the heuristics
2054 used during the leak search. The set of heuristics to use can be specified
2055 using a <varname><set></varname> similarly
2056 to the command line option <option>--leak-check-heuristics</option>.
2057 The default value for the <varname>heuristics</varname> argument is
2058 <varname>heuristics none</varname>.
2061 <para>The <varname>[new|increased*|changed|any]</varname> argument controls
2062 what kinds of changes are shown for a <varname>full</varname> leak search.
2063 The value <varname>increased</varname> specifies that only block
2064 allocation stacks with an increased number of leaked bytes or
2065 blocks since the previous leak check should be shown. The
2066 value <varname>changed</varname> specifies that allocation stacks
2067 with any change since the previous leak check should be shown.
2068 The value <varname>new</varname> specifies to show only the block
2069 allocation stacks that are new since the previous leak search.
2070 The value <varname>any</varname> specifies that all leak entries
2071 should be shown, regardless of any increase or decrease.
2072 If <varname>new</varname> or <varname>increased</varname> or
2073 <varname>changed</varname> are specified, the leak report entries will show
2074 the delta relative to the previous leak report and the new loss records
2075 will have a "new" marker (even when <varname>increased</varname> or
2076 <varname>changed</varname> were specified).
2079 <para>The following example shows usage of the
2080 <varname>leak_check</varname> monitor command on
2081 the <varname>memcheck/tests/leak-cases.c</varname> regression
2082 test. The first command outputs one entry having an increase in
2083 the leaked bytes. The second command is the same as the first
2084 command, but uses the abbreviated forms accepted by GDB and the
2085 Valgrind gdbserver. It only outputs the summary information, as
2086 there was no increase since the previous leak search.</para>
2087 <programlisting><![CDATA[
2088 (gdb) monitor leak_check full possibleleak increased
2089 ==19520== 16 (+16) bytes in 1 (+1) blocks are possibly lost in new loss record 9 of 12
2090 ==19520== at 0x40070B4: malloc (vg_replace_malloc.c:263)
2091 ==19520== by 0x80484D5: mk (leak-cases.c:52)
2092 ==19520== by 0x804855F: f (leak-cases.c:81)
2093 ==19520== by 0x80488E0: main (leak-cases.c:107)
2095 ==19520== LEAK SUMMARY:
2096 ==19520== definitely lost: 32 (+0) bytes in 2 (+0) blocks
2097 ==19520== indirectly lost: 16 (+0) bytes in 1 (+0) blocks
2098 ==19520== possibly lost: 32 (+16) bytes in 2 (+1) blocks
2099 ==19520== still reachable: 96 (+16) bytes in 6 (+1) blocks
2100 ==19520== suppressed: 0 (+0) bytes in 0 (+0) blocks
2101 ==19520== Reachable blocks (those to which a pointer was found) are not shown.
2102 ==19520== To see them, add 'reachable any' args to leak_check
2105 ==19520== LEAK SUMMARY:
2106 ==19520== definitely lost: 32 (+0) bytes in 2 (+0) blocks
2107 ==19520== indirectly lost: 16 (+0) bytes in 1 (+0) blocks
2108 ==19520== possibly lost: 32 (+0) bytes in 2 (+0) blocks
2109 ==19520== still reachable: 96 (+0) bytes in 6 (+0) blocks
2110 ==19520== suppressed: 0 (+0) bytes in 0 (+0) blocks
2111 ==19520== Reachable blocks (those to which a pointer was found) are not shown.
2112 ==19520== To see them, add 'reachable any' args to leak_check
2115 ]]></programlisting>
2116 <para>Note that when using Valgrind's gdbserver, it is not
2118 with <option>--leak-check=full</option>
2119 <option>--show-reachable=yes</option> to see the reachable
2120 blocks. You can obtain the same information without rerunning by
2121 using the GDB command <computeroutput>monitor leak_check full
2122 reachable any</computeroutput> (or, using
2123 abbreviation: <computeroutput>mo l f r a</computeroutput>).
2126 <para>The GDB equivalent memcheck front end command <varname>memcheck
2127 leak_check</varname> auto-completes the user input by providing the full
2128 list of keywords still relevant according to what is already typed. For
2129 example, if the "summary" keyword has been provided, the following TABs to
2130 auto-complete other items will not propose anymore "full" and "xtleak".
2131 Note that KIND and HEUR values are not part of auto-completed elements.
2137 <para><varname>block_list <loss_record_nr>|<loss_record_nr_from>..<loss_record_nr_to>
2138 [unlimited*|limited <max_blocks>]
2139 [heuristics heur1,heur2,...]
2141 shows the list of blocks belonging to
2142 <varname><loss_record_nr></varname> (or to the loss records range
2143 <varname><loss_record_nr_from>..<loss_record_nr_to></varname>).
2144 The nr of blocks to print can be controlled using the
2145 <varname>limited</varname> argument followed by the maximum nr
2146 of blocks to output.
2147 If one or more heuristics are given, only prints the loss records
2148 and blocks found via one of the given <varname>heur1,heur2,...</varname>
2152 <para> A leak search merges the allocated blocks in loss records :
2153 a loss record re-groups all blocks having the same state (for
2154 example, Definitely Lost) and the same allocation backtrace.
2155 Each loss record is identified in the leak search result
2156 by a loss record number.
2157 The <varname>block_list</varname> command shows the loss record information
2158 followed by the addresses and sizes of the blocks which have been
2159 merged in the loss record. If a block was found using an heuristic, the block size
2160 is followed by the heuristic.
2163 <para> If a directly lost block causes some other blocks to be indirectly
2164 lost, the block_list command will also show these indirectly lost blocks.
2165 The indirectly lost blocks will be indented according to the level of indirection
2166 between the directly lost block and the indirectly lost block(s).
2167 Each indirectly lost block is followed by the reference of its loss record.
2170 <para> The block_list command can be used on the results of a leak search as long
2171 as no block has been freed after this leak search: as soon as the program frees
2172 a block, a new leak search is needed before block_list can be used again.
2176 In the below example, the program leaks a tree structure by losing the pointer to
2177 the block A (top of the tree).
2178 So, the block A is directly lost, causing an indirect
2179 loss of blocks B to G. The first block_list command shows the loss record of A
2180 (a definitely lost block with address 0x4028028, size 16). The addresses and sizes
2181 of the indirectly lost blocks due to block A are shown below the block A.
2182 The second command shows the details of one of the indirect loss records output
2183 by the first command.
2185 <programlisting><![CDATA[
2191 ]]></programlisting>
2193 <programlisting><![CDATA[
2195 #0 main () at leak-tree.c:69
2196 (gdb) monitor leak_check full any
2197 ==19552== 112 (16 direct, 96 indirect) bytes in 1 blocks are definitely lost in loss record 7 of 7
2198 ==19552== at 0x40070B4: malloc (vg_replace_malloc.c:263)
2199 ==19552== by 0x80484D5: mk (leak-tree.c:28)
2200 ==19552== by 0x80484FC: f (leak-tree.c:41)
2201 ==19552== by 0x8048856: main (leak-tree.c:63)
2203 ==19552== LEAK SUMMARY:
2204 ==19552== definitely lost: 16 bytes in 1 blocks
2205 ==19552== indirectly lost: 96 bytes in 6 blocks
2206 ==19552== possibly lost: 0 bytes in 0 blocks
2207 ==19552== still reachable: 0 bytes in 0 blocks
2208 ==19552== suppressed: 0 bytes in 0 blocks
2210 (gdb) monitor block_list 7
2211 ==19552== 112 (16 direct, 96 indirect) bytes in 1 blocks are definitely lost in loss record 7 of 7
2212 ==19552== at 0x40070B4: malloc (vg_replace_malloc.c:263)
2213 ==19552== by 0x80484D5: mk (leak-tree.c:28)
2214 ==19552== by 0x80484FC: f (leak-tree.c:41)
2215 ==19552== by 0x8048856: main (leak-tree.c:63)
2216 ==19552== 0x4028028[16]
2217 ==19552== 0x4028068[16] indirect loss record 1
2218 ==19552== 0x40280E8[16] indirect loss record 3
2219 ==19552== 0x4028128[16] indirect loss record 4
2220 ==19552== 0x40280A8[16] indirect loss record 2
2221 ==19552== 0x4028168[16] indirect loss record 5
2222 ==19552== 0x40281A8[16] indirect loss record 6
2224 ==19552== 16 bytes in 1 blocks are indirectly lost in loss record 2 of 7
2225 ==19552== at 0x40070B4: malloc (vg_replace_malloc.c:263)
2226 ==19552== by 0x80484D5: mk (leak-tree.c:28)
2227 ==19552== by 0x8048519: f (leak-tree.c:43)
2228 ==19552== by 0x8048856: main (leak-tree.c:63)
2229 ==19552== 0x40280A8[16]
2230 ==19552== 0x4028168[16] indirect loss record 5
2231 ==19552== 0x40281A8[16] indirect loss record 6
2234 ]]></programlisting>
2239 <para><varname>who_points_at <addr> [<len>]</varname>
2240 shows all the locations where a pointer to addr is found.
2241 If len is equal to 1, the command only shows the locations pointing
2242 exactly at addr (i.e. the "start pointers" to addr).
2243 If len is > 1, "interior pointers" pointing at the len first bytes
2247 <para>The locations searched for are the same as the locations
2248 used in the leak search. So, <varname>who_points_at</varname> can a.o.
2249 be used to show why the leak search still can reach a block, or can
2250 search for dangling pointers to a freed block.
2251 Each location pointing at addr (or pointing inside addr if interior pointers
2252 are being searched for) will be described.
2255 <para>The GDB equivalent memcheck front end command <varname>memcheck
2256 who_points_at ADDR [LEN]</varname> accept any address expression for its
2257 first ADDR argument. The second optional argument is any integer
2258 expression. Note that these 2 arguments must be separated by a space.
2261 <para>In the below example, the pointers to the 'tree block A' (see example
2262 in command <varname>block_list</varname>) is shown before the tree was leaked.
2263 The descriptions are detailed as the option <option>--read-var-info=yes</option>
2264 was given at Valgrind startup. The second call shows the pointers (start and interior
2265 pointers) to block G. The block G (0x40281A8) is reachable via block C (0x40280a8)
2266 and register ECX of tid 1 (tid is the Valgrind thread id).
2267 It is "interior reachable" via the register EBX.
2270 <programlisting><![CDATA[
2271 (gdb) monitor who_points_at 0x4028028
2272 ==20852== Searching for pointers to 0x4028028
2273 ==20852== *0x8049e20 points at 0x4028028
2274 ==20852== Location 0x8049e20 is 0 bytes inside global var "t"
2275 ==20852== declared at leak-tree.c:35
2276 (gdb) monitor who_points_at 0x40281A8 16
2277 ==20852== Searching for pointers pointing in 16 bytes from 0x40281a8
2278 ==20852== *0x40280ac points at 0x40281a8
2279 ==20852== Address 0x40280ac is 4 bytes inside a block of size 16 alloc'd
2280 ==20852== at 0x40070B4: malloc (vg_replace_malloc.c:263)
2281 ==20852== by 0x80484D5: mk (leak-tree.c:28)
2282 ==20852== by 0x8048519: f (leak-tree.c:43)
2283 ==20852== by 0x8048856: main (leak-tree.c:63)
2284 ==20852== tid 1 register ECX points at 0x40281a8
2285 ==20852== tid 1 register EBX interior points at 2 bytes inside 0x40281a8
2287 ]]></programlisting>
2289 <para> When <varname>who_points_at</varname> finds an interior pointer,
2290 it will report the heuristic(s) with which this interior pointer
2291 will be considered as reachable. Note that this is done independently
2292 of the value of the option <option>--leak-check-heuristics</option>.
2293 In the below example, the loss record 6 indicates a possibly lost
2294 block. <varname>who_points_at</varname> reports that there is an interior
2295 pointer pointing in this block, and that the block can be considered
2296 reachable using the heuristic
2297 <computeroutput>multipleinheritance</computeroutput>.
2300 <programlisting><![CDATA[
2301 (gdb) monitor block_list 6
2302 ==3748== 8 bytes in 1 blocks are possibly lost in loss record 6 of 7
2303 ==3748== at 0x4007D77: operator new(unsigned int) (vg_replace_malloc.c:313)
2304 ==3748== by 0x8048954: main (leak_cpp_interior.cpp:43)
2305 ==3748== 0x402A0E0[8]
2306 (gdb) monitor who_points_at 0x402A0E0 8
2307 ==3748== Searching for pointers pointing in 8 bytes from 0x402a0e0
2308 ==3748== *0xbe8ee078 interior points at 4 bytes inside 0x402a0e0
2309 ==3748== Address 0xbe8ee078 is on thread 1's stack
2310 ==3748== block at 0x402a0e0 considered reachable by ptr 0x402a0e4 using multipleinheritance heuristic
2312 ]]></programlisting>
2317 <para><varname>xtmemory [<filename> default xtmemory.kcg.%p.%n]</varname>
2318 requests Memcheck tool to produce an xtree heap memory report.
2319 See <xref linkend="&vg-xtree-id;"/> for
2320 a detailed explanation about execution trees. </para>
2327 <sect1 id="mc-manual.clientreqs" xreflabel="Client requests">
2328 <title>Client Requests</title>
2330 <para>The following client requests are defined in
2331 <filename>memcheck.h</filename>.
2332 See <filename>memcheck.h</filename> for exact details of their
2338 <para><varname>VALGRIND_MAKE_MEM_NOACCESS</varname>,
2339 <varname>VALGRIND_MAKE_MEM_UNDEFINED</varname> and
2340 <varname>VALGRIND_MAKE_MEM_DEFINED</varname>.
2341 These mark address ranges as completely inaccessible,
2342 accessible but containing undefined data, and accessible and
2343 containing defined data, respectively. They return -1, when
2344 run on Valgrind and 0 otherwise.</para>
2348 <para><varname>VALGRIND_MAKE_MEM_DEFINED_IF_ADDRESSABLE</varname>.
2349 This is just like <varname>VALGRIND_MAKE_MEM_DEFINED</varname> but only
2350 affects those bytes that are already addressable.</para>
2354 <para><varname>VALGRIND_CHECK_MEM_IS_ADDRESSABLE</varname> and
2355 <varname>VALGRIND_CHECK_MEM_IS_DEFINED</varname>: check immediately
2356 whether or not the given address range has the relevant property,
2357 and if not, print an error message. Also, for the convenience of
2358 the client, returns zero if the relevant property holds; otherwise,
2359 the returned value is the address of the first byte for which the
2360 property is not true. Always returns 0 when not run on
2365 <para><varname>VALGRIND_CHECK_VALUE_IS_DEFINED</varname>: a quick and easy
2366 way to find out whether Valgrind thinks a particular value
2367 (lvalue, to be precise) is addressable and defined. Prints an error
2368 message if not. It has no return value.</para>
2372 <para><varname>VALGRIND_DO_LEAK_CHECK</varname>: does a full memory leak
2373 check (like <option>--leak-check=full</option>) right now.
2374 This is useful for incrementally checking for leaks between arbitrary
2375 places in the program's execution. It has no return value.</para>
2379 <para><varname>VALGRIND_DO_ADDED_LEAK_CHECK</varname>: same as
2380 <varname> VALGRIND_DO_LEAK_CHECK</varname> but only shows the
2381 entries for which there was an increase in leaked bytes or leaked
2382 number of blocks since the previous leak search. It has no return
2387 <para><varname>VALGRIND_DO_CHANGED_LEAK_CHECK</varname>: same as
2388 <varname>VALGRIND_DO_LEAK_CHECK</varname> but only shows the
2389 entries for which there was an increase or decrease in leaked
2390 bytes or leaked number of blocks since the previous leak search. It
2391 has no return value.</para>
2395 <para><varname>VALGRIND_DO_NEW_LEAK_CHECK</varname>: same as
2396 <varname> VALGRIND_DO_LEAK_CHECK</varname> but only shows the new
2397 entries since the previous leak search. It has no return value.</para>
2401 <para><varname>VALGRIND_DO_QUICK_LEAK_CHECK</varname>: like
2402 <varname>VALGRIND_DO_LEAK_CHECK</varname>, except it produces only a leak
2403 summary (like <option>--leak-check=summary</option>).
2404 It has no return value.</para>
2408 <para><varname>VALGRIND_COUNT_LEAKS</varname>: fills in the four
2409 arguments with the number of bytes of memory found by the previous
2410 leak check to be leaked (i.e. the sum of direct leaks and indirect leaks),
2411 dubious, reachable and suppressed. This is useful in test harness code,
2412 after calling <varname>VALGRIND_DO_LEAK_CHECK</varname> or
2413 <varname>VALGRIND_DO_QUICK_LEAK_CHECK</varname>.</para>
2417 <para><varname>VALGRIND_COUNT_LEAK_BLOCKS</varname>: identical to
2418 <varname>VALGRIND_COUNT_LEAKS</varname> except that it returns the
2419 number of blocks rather than the number of bytes in each
2424 <para><varname>VALGRIND_GET_VBITS</varname> and
2425 <varname>VALGRIND_SET_VBITS</varname>: allow you to get and set the
2426 V (validity) bits for an address range. You should probably only
2427 set V bits that you have got with
2428 <varname>VALGRIND_GET_VBITS</varname>. Only for those who really
2429 know what they are doing.</para>
2433 <para><varname>VALGRIND_CREATE_BLOCK</varname> and
2434 <varname>VALGRIND_DISCARD</varname>. <varname>VALGRIND_CREATE_BLOCK</varname>
2435 takes an address, a number of bytes and a character string. The
2436 specified address range is then associated with that string. When
2437 Memcheck reports an invalid access to an address in the range, it
2438 will describe it in terms of this block rather than in terms of
2439 any other block it knows about. Note that the use of this macro
2440 does not actually change the state of memory in any way -- it
2441 merely gives a name for the range.
2444 <para>At some point you may want Memcheck to stop reporting errors
2445 in terms of the block named
2446 by <varname>VALGRIND_CREATE_BLOCK</varname>. To make this
2447 possible, <varname>VALGRIND_CREATE_BLOCK</varname> returns a
2448 "block handle", which is a C <varname>int</varname> value. You
2449 can pass this block handle to <varname>VALGRIND_DISCARD</varname>.
2450 After doing so, Valgrind will no longer relate addressing errors
2451 in the specified range to the block. Passing invalid handles to
2452 <varname>VALGRIND_DISCARD</varname> is harmless.
2463 <sect1 id="mc-manual.mempools" xreflabel="Memory Pools">
2464 <title>Memory Pools: describing and working with custom allocators</title>
2466 <para>Some programs use custom memory allocators, often for performance
2467 reasons. Left to itself, Memcheck is unable to understand the
2468 behaviour of custom allocation schemes as well as it understands the
2469 standard allocators, and so may miss errors and leaks in your program. What
2470 this section describes is a way to give Memcheck enough of a description of
2471 your custom allocator that it can make at least some sense of what is
2474 <para>There are many different sorts of custom allocator, so Memcheck
2475 attempts to reason about them using a loose, abstract model. We
2476 use the following terminology when describing custom allocation
2481 <para>Custom allocation involves a set of independent "memory pools".
2485 <para>Memcheck's notion of a a memory pool consists of a single "anchor
2486 address" and a set of non-overlapping "chunks" associated with the
2487 anchor address.</para>
2490 <para>Typically a pool's anchor address is the address of a
2491 book-keeping "header" structure.</para>
2494 <para>Typically the pool's chunks are drawn from a contiguous
2495 "superblock" acquired through the system
2496 <function>malloc</function> or
2497 <function>mmap</function>.</para>
2502 <para>Keep in mind that the last two points above say "typically": the
2503 Valgrind mempool client request API is intentionally vague about the
2504 exact structure of a mempool. There is no specific mention made of
2505 headers or superblocks. Nevertheless, the following picture may help
2506 elucidate the intention of the terms in the API:</para>
2508 <programlisting><![CDATA[
2518 +------+---+--------------+---+------------------+
2519 | |rzB| allocation |rzB| |
2520 +------+---+--------------+---+------------------+
2523 "addr" "addr"+"size"
2524 ]]></programlisting>
2527 Note that the header and the superblock may be contiguous or
2528 discontiguous, and there may be multiple superblocks associated with a
2529 single header; such variations are opaque to Memcheck. The API
2530 only requires that your allocation scheme can present sensible values
2531 of "pool", "addr" and "size".</para>
2534 Typically, before making client requests related to mempools, a client
2535 program will have allocated such a header and superblock for their
2536 mempool, and marked the superblock NOACCESS using the
2537 <varname>VALGRIND_MAKE_MEM_NOACCESS</varname> client request.</para>
2540 When dealing with mempools, the goal is to maintain a particular
2541 invariant condition: that Memcheck believes the unallocated portions
2542 of the pool's superblock (including redzones) are NOACCESS. To
2543 maintain this invariant, the client program must ensure that the
2544 superblock starts out in that state; Memcheck cannot make it so, since
2545 Memcheck never explicitly learns about the superblock of a pool, only
2546 the allocated chunks within the pool.</para>
2549 Once the header and superblock for a pool are established and properly
2550 marked, there are a number of client requests programs can use to
2551 inform Memcheck about changes to the state of a mempool:</para>
2557 <varname>VALGRIND_CREATE_MEMPOOL(pool, rzB, is_zeroed)</varname>:
2558 This request registers the address <varname>pool</varname> as the anchor
2559 address for a memory pool. It also provides a size
2560 <varname>rzB</varname>, specifying how large the redzones placed around
2561 chunks allocated from the pool should be. Finally, it provides an
2562 <varname>is_zeroed</varname> argument that specifies whether the pool's
2563 chunks are zeroed (more precisely: defined) when allocated.
2566 Upon completion of this request, no chunks are associated with the
2567 pool. The request simply tells Memcheck that the pool exists, so that
2568 subsequent calls can refer to it as a pool.
2573 <!-- Note: the below is mostly a copy of valgrind.h. Keep in sync! -->
2575 <varname>VALGRIND_CREATE_MEMPOOL_EXT(pool, rzB, is_zeroed, flags)</varname>:
2576 Create a memory pool with some flags (that can
2577 be OR-ed together) specifying extended behaviour. When flags is
2578 zero, the behaviour is identical to
2579 <varname>VALGRIND_CREATE_MEMPOOL</varname>.</para>
2582 <para> The flag <varname>VALGRIND_MEMPOOL_METAPOOL</varname>
2583 specifies that the pieces of memory associated with the pool
2584 using <varname>VALGRIND_MEMPOOL_ALLOC</varname> will be used
2585 by the application as superblocks to dole out MALLOC_LIKE
2586 blocks using <varname>VALGRIND_MALLOCLIKE_BLOCK</varname>.
2587 In other words, a meta pool is a "2 levels" pool : first
2588 level is the blocks described
2589 by <varname>VALGRIND_MEMPOOL_ALLOC</varname>. The second
2590 level blocks are described
2591 using <varname>VALGRIND_MALLOCLIKE_BLOCK</varname>. Note
2592 that the association between the pool and the second level
2593 blocks is implicit : second level blocks will be located
2594 inside first level blocks. It is necessary to use
2595 the <varname>VALGRIND_MEMPOOL_METAPOOL</varname> flag for
2596 such 2 levels pools, as otherwise valgrind will detect
2597 overlapping memory blocks, and will abort execution
2598 (e.g. during leak search).
2603 <varname>VALGRIND_MEMPOOL_AUTO_FREE</varname>. Such a meta
2604 pool can also be marked as an 'auto free' pool using the
2605 flag <varname>VALGRIND_MEMPOOL_AUTO_FREE</varname>, which
2606 must be OR-ed together with
2607 the <varname>VALGRIND_MEMPOOL_METAPOOL</varname>. For an
2608 'auto free' pool, <varname>VALGRIND_MEMPOOL_FREE</varname>
2609 will automatically free the second level blocks that are
2610 contained inside the first level block freed
2611 with <varname>VALGRIND_MEMPOOL_FREE</varname>. In other
2612 words, calling <varname>VALGRIND_MEMPOOL_FREE</varname> will
2613 cause implicit calls
2614 to <varname>VALGRIND_FREELIKE_BLOCK</varname> for all the
2615 second level blocks included in the first level block.
2616 Note: it is an error to use
2617 the <varname>VALGRIND_MEMPOOL_AUTO_FREE</varname> flag
2619 <varname>VALGRIND_MEMPOOL_METAPOOL</varname> flag.
2626 <para><varname>VALGRIND_DESTROY_MEMPOOL(pool)</varname>:
2627 This request tells Memcheck that a pool is being torn down. Memcheck
2628 then removes all records of chunks associated with the pool, as well
2629 as its record of the pool's existence. While destroying its records of
2630 a mempool, Memcheck resets the redzones of any live chunks in the pool
2636 <para><varname>VALGRIND_MEMPOOL_ALLOC(pool, addr, size)</varname>:
2637 This request informs Memcheck that a <varname>size</varname>-byte chunk
2638 has been allocated at <varname>addr</varname>, and associates the chunk with the
2640 <varname>pool</varname>. If the pool was created with nonzero
2641 <varname>rzB</varname> redzones, Memcheck will mark the
2642 <varname>rzB</varname> bytes before and after the chunk as NOACCESS. If
2643 the pool was created with the <varname>is_zeroed</varname> argument set,
2644 Memcheck will mark the chunk as DEFINED, otherwise Memcheck will mark
2645 the chunk as UNDEFINED.
2650 <para><varname>VALGRIND_MEMPOOL_FREE(pool, addr)</varname>:
2651 This request informs Memcheck that the chunk at <varname>addr</varname>
2652 should no longer be considered allocated. Memcheck will mark the chunk
2653 associated with <varname>addr</varname> as NOACCESS, and delete its
2654 record of the chunk's existence.
2659 <para><varname>VALGRIND_MEMPOOL_TRIM(pool, addr, size)</varname>:
2660 This request trims the chunks associated with <varname>pool</varname>.
2661 The request only operates on chunks associated with
2662 <varname>pool</varname>. Trimming is formally defined as:</para>
2665 <para> All chunks entirely inside the range
2666 <varname>addr..(addr+size-1)</varname> are preserved.</para>
2669 <para>All chunks entirely outside the range
2670 <varname>addr..(addr+size-1)</varname> are discarded, as though
2671 <varname>VALGRIND_MEMPOOL_FREE</varname> was called on them. </para>
2674 <para>All other chunks must intersect with the range
2675 <varname>addr..(addr+size-1)</varname>; areas outside the
2676 intersection are marked as NOACCESS, as though they had been
2677 independently freed with
2678 <varname>VALGRIND_MEMPOOL_FREE</varname>.</para>
2681 <para>This is a somewhat rare request, but can be useful in
2682 implementing the type of mass-free operations common in custom
2683 LIFO allocators.</para>
2687 <para><varname>VALGRIND_MOVE_MEMPOOL(poolA, poolB)</varname>: This
2688 request informs Memcheck that the pool previously anchored at
2689 address <varname>poolA</varname> has moved to anchor address
2690 <varname>poolB</varname>. This is a rare request, typically only needed
2691 if you <function>realloc</function> the header of a mempool.</para>
2692 <para>No memory-status bits are altered by this request.</para>
2697 <varname>VALGRIND_MEMPOOL_CHANGE(pool, addrA, addrB,
2698 size)</varname>: This request informs Memcheck that the chunk
2699 previously allocated at address <varname>addrA</varname> within
2700 <varname>pool</varname> has been moved and/or resized, and should be
2701 changed to cover the region <varname>addrB..(addrB+size-1)</varname>. This
2702 is a rare request, typically only needed if you
2703 <function>realloc</function> a superblock or wish to extend a chunk
2704 without changing its memory-status bits.
2706 <para>No memory-status bits are altered by this request.
2711 <para><varname>VALGRIND_MEMPOOL_EXISTS(pool)</varname>:
2712 This request informs the caller whether or not Memcheck is currently
2713 tracking a mempool at anchor address <varname>pool</varname>. It
2714 evaluates to 1 when there is a mempool associated with that address, 0
2715 otherwise. This is a rare request, only useful in circumstances when
2716 client code might have lost track of the set of active mempools.
2730 <sect1 id="mc-manual.mpiwrap" xreflabel="MPI Wrappers">
2731 <title>Debugging MPI Parallel Programs with Valgrind</title>
2733 <para>Memcheck supports debugging of distributed-memory applications
2734 which use the MPI message passing standard. This support consists of a
2735 library of wrapper functions for the
2736 <computeroutput>PMPI_*</computeroutput> interface. When incorporated
2737 into the application's address space, either by direct linking or by
2738 <computeroutput>LD_PRELOAD</computeroutput>, the wrappers intercept
2739 calls to <computeroutput>PMPI_Send</computeroutput>,
2740 <computeroutput>PMPI_Recv</computeroutput>, etc. They then
2741 use client requests to inform Memcheck of memory state changes caused
2742 by the function being wrapped. This reduces the number of false
2743 positives that Memcheck otherwise typically reports for MPI
2744 applications.</para>
2746 <para>The wrappers also take the opportunity to carefully check
2747 size and definedness of buffers passed as arguments to MPI functions, hence
2748 detecting errors such as passing undefined data to
2749 <computeroutput>PMPI_Send</computeroutput>, or receiving data into a
2750 buffer which is too small.</para>
2752 <para>Unlike most of the rest of Valgrind, the wrapper library is subject to a
2753 BSD-style license, so you can link it into any code base you like.
2754 See the top of <computeroutput>mpi/libmpiwrap.c</computeroutput>
2755 for license details.</para>
2758 <sect2 id="mc-manual.mpiwrap.build" xreflabel="Building MPI Wrappers">
2759 <title>Building and installing the wrappers</title>
2761 <para> The wrapper library will be built automatically if possible.
2762 Valgrind's configure script will look for a suitable
2763 <computeroutput>mpicc</computeroutput> to build it with. This must be
2764 the same <computeroutput>mpicc</computeroutput> you use to build the
2765 MPI application you want to debug. By default, Valgrind tries
2766 <computeroutput>mpicc</computeroutput>, but you can specify a
2767 different one by using the configure-time option
2768 <option>--with-mpicc</option>. Currently the
2769 wrappers are only buildable with
2770 <computeroutput>mpicc</computeroutput>s which are based on GNU
2771 GCC or Intel's C++ Compiler.</para>
2773 <para>Check that the configure script prints a line like this:</para>
2775 <programlisting><![CDATA[
2776 checking for usable MPI2-compliant mpicc and mpi.h... yes, mpicc
2777 ]]></programlisting>
2779 <para>If it says <computeroutput>... no</computeroutput>, your
2780 <computeroutput>mpicc</computeroutput> has failed to compile and link
2781 a test MPI2 program.</para>
2783 <para>If the configure test succeeds, continue in the usual way with
2784 <computeroutput>make</computeroutput> and <computeroutput>make
2785 install</computeroutput>. The final install tree should then contain
2786 <computeroutput>libmpiwrap-<platform>.so</computeroutput>.
2789 <para>Compile up a test MPI program (eg, MPI hello-world) and try
2792 <programlisting><![CDATA[
2793 LD_PRELOAD=$prefix/lib/valgrind/libmpiwrap-<platform>.so \
2794 mpirun [args] $prefix/bin/valgrind ./hello
2795 ]]></programlisting>
2797 <para>You should see something similar to the following</para>
2799 <programlisting><![CDATA[
2800 valgrind MPI wrappers 31901: Active for pid 31901
2801 valgrind MPI wrappers 31901: Try MPIWRAP_DEBUG=help for possible options
2802 ]]></programlisting>
2804 <para>repeated for every process in the group. If you do not see
2805 these, there is an build/installation problem of some kind.</para>
2807 <para> The MPI functions to be wrapped are assumed to be in an ELF
2808 shared object with soname matching
2809 <computeroutput>libmpi.so*</computeroutput>. This is known to be
2810 correct at least for Open MPI and Quadrics MPI, and can easily be
2811 changed if required.</para>
2815 <sect2 id="mc-manual.mpiwrap.gettingstarted"
2816 xreflabel="Getting started with MPI Wrappers">
2817 <title>Getting started</title>
2819 <para>Compile your MPI application as usual, taking care to link it
2820 using the same <computeroutput>mpicc</computeroutput> that your
2821 Valgrind build was configured with.</para>
2824 Use the following basic scheme to run your application on Valgrind with
2825 the wrappers engaged:</para>
2827 <programlisting><![CDATA[
2828 MPIWRAP_DEBUG=[wrapper-args] \
2829 LD_PRELOAD=$prefix/lib/valgrind/libmpiwrap-<platform>.so \
2830 mpirun [mpirun-args] \
2831 $prefix/bin/valgrind [valgrind-args] \
2832 [application] [app-args]
2833 ]]></programlisting>
2835 <para>As an alternative to
2836 <computeroutput>LD_PRELOAD</computeroutput>ing
2837 <computeroutput>libmpiwrap-<platform>.so</computeroutput>, you can
2838 simply link it to your application if desired. This should not disturb
2839 native behaviour of your application in any way.</para>
2843 <sect2 id="mc-manual.mpiwrap.controlling"
2844 xreflabel="Controlling the MPI Wrappers">
2845 <title>Controlling the wrapper library</title>
2847 <para>Environment variable
2848 <computeroutput>MPIWRAP_DEBUG</computeroutput> is consulted at
2849 startup. The default behaviour is to print a starting banner</para>
2851 <programlisting><![CDATA[
2852 valgrind MPI wrappers 16386: Active for pid 16386
2853 valgrind MPI wrappers 16386: Try MPIWRAP_DEBUG=help for possible options
2854 ]]></programlisting>
2856 <para> and then be relatively quiet.</para>
2858 <para>You can give a list of comma-separated options in
2859 <computeroutput>MPIWRAP_DEBUG</computeroutput>. These are</para>
2863 <para><computeroutput>verbose</computeroutput>:
2864 show entries/exits of all wrappers. Also show extra
2865 debugging info, such as the status of outstanding
2866 <computeroutput>MPI_Request</computeroutput>s resulting
2867 from uncompleted <computeroutput>MPI_Irecv</computeroutput>s.</para>
2870 <para><computeroutput>quiet</computeroutput>:
2871 opposite of <computeroutput>verbose</computeroutput>, only print
2872 anything when the wrappers want
2873 to report a detected programming error, or in case of catastrophic
2874 failure of the wrappers.</para>
2877 <para><computeroutput>warn</computeroutput>:
2878 by default, functions which lack proper wrappers
2879 are not commented on, just silently
2880 ignored. This causes a warning to be printed for each unwrapped
2881 function used, up to a maximum of three warnings per function.</para>
2884 <para><computeroutput>strict</computeroutput>:
2885 print an error message and abort the program if
2886 a function lacking a wrapper is used.</para>
2890 <para> If you want to use Valgrind's XML output facility
2891 (<option>--xml=yes</option>), you should pass
2892 <computeroutput>quiet</computeroutput> in
2893 <computeroutput>MPIWRAP_DEBUG</computeroutput> so as to get rid of any
2894 extraneous printing from the wrappers.</para>
2899 <sect2 id="mc-manual.mpiwrap.limitations.functions"
2900 xreflabel="Functions: Abilities and Limitations">
2901 <title>Functions</title>
2903 <para>All MPI2 functions except
2904 <computeroutput>MPI_Wtick</computeroutput>,
2905 <computeroutput>MPI_Wtime</computeroutput> and
2906 <computeroutput>MPI_Pcontrol</computeroutput> have wrappers. The
2907 first two are not wrapped because they return a
2908 <computeroutput>double</computeroutput>, which Valgrind's
2909 function-wrap mechanism cannot handle (but it could easily be
2910 extended to do so). <computeroutput>MPI_Pcontrol</computeroutput> cannot be
2911 wrapped as it has variable arity:
2912 <computeroutput>int MPI_Pcontrol(const int level, ...)</computeroutput></para>
2914 <para>Most functions are wrapped with a default wrapper which does
2915 nothing except complain or abort if it is called, depending on
2916 settings in <computeroutput>MPIWRAP_DEBUG</computeroutput> listed
2917 above. The following functions have "real", do-something-useful
2920 <programlisting><![CDATA[
2921 PMPI_Send PMPI_Bsend PMPI_Ssend PMPI_Rsend
2923 PMPI_Recv PMPI_Get_count
2925 PMPI_Isend PMPI_Ibsend PMPI_Issend PMPI_Irsend
2928 PMPI_Wait PMPI_Waitall
2929 PMPI_Test PMPI_Testall
2931 PMPI_Iprobe PMPI_Probe
2937 PMPI_Type_commit PMPI_Type_free
2939 PMPI_Pack PMPI_Unpack
2941 PMPI_Bcast PMPI_Gather PMPI_Scatter PMPI_Alltoall
2942 PMPI_Reduce PMPI_Allreduce PMPI_Op_create
2944 PMPI_Comm_create PMPI_Comm_dup PMPI_Comm_free PMPI_Comm_rank PMPI_Comm_size
2947 PMPI_Init PMPI_Initialized PMPI_Finalize
2948 ]]></programlisting>
2950 <para> A few functions such as
2951 <computeroutput>PMPI_Address</computeroutput> are listed as
2952 <computeroutput>HAS_NO_WRAPPER</computeroutput>. They have no wrapper
2953 at all as there is nothing worth checking, and giving a no-op wrapper
2954 would reduce performance for no reason.</para>
2956 <para> Note that the wrapper library itself can itself generate large
2957 numbers of calls to the MPI implementation, especially when walking
2958 complex types. The most common functions called are
2959 <computeroutput>PMPI_Extent</computeroutput>,
2960 <computeroutput>PMPI_Type_get_envelope</computeroutput>,
2961 <computeroutput>PMPI_Type_get_contents</computeroutput>, and
2962 <computeroutput>PMPI_Type_free</computeroutput>. </para>
2965 <sect2 id="mc-manual.mpiwrap.limitations.types"
2966 xreflabel="Types: Abilities and Limitations">
2967 <title>Types</title>
2969 <para> MPI-1.1 structured types are supported, and walked exactly.
2970 The currently supported combiners are
2971 <computeroutput>MPI_COMBINER_NAMED</computeroutput>,
2972 <computeroutput>MPI_COMBINER_CONTIGUOUS</computeroutput>,
2973 <computeroutput>MPI_COMBINER_VECTOR</computeroutput>,
2974 <computeroutput>MPI_COMBINER_HVECTOR</computeroutput>
2975 <computeroutput>MPI_COMBINER_INDEXED</computeroutput>,
2976 <computeroutput>MPI_COMBINER_HINDEXED</computeroutput> and
2977 <computeroutput>MPI_COMBINER_STRUCT</computeroutput>. This should
2978 cover all MPI-1.1 types. The mechanism (function
2979 <computeroutput>walk_type</computeroutput>) should extend easily to
2980 cover MPI2 combiners.</para>
2982 <para>MPI defines some named structured types
2983 (<computeroutput>MPI_FLOAT_INT</computeroutput>,
2984 <computeroutput>MPI_DOUBLE_INT</computeroutput>,
2985 <computeroutput>MPI_LONG_INT</computeroutput>,
2986 <computeroutput>MPI_2INT</computeroutput>,
2987 <computeroutput>MPI_SHORT_INT</computeroutput>,
2988 <computeroutput>MPI_LONG_DOUBLE_INT</computeroutput>) which are pairs
2989 of some basic type and a C <computeroutput>int</computeroutput>.
2990 Unfortunately the MPI specification makes it impossible to look inside
2991 these types and see where the fields are. Therefore these wrappers
2992 assume the types are laid out as <computeroutput>struct { float val;
2993 int loc; }</computeroutput> (for
2994 <computeroutput>MPI_FLOAT_INT</computeroutput>), etc, and act
2995 accordingly. This appears to be correct at least for Open MPI 1.0.2
2996 and for Quadrics MPI.</para>
2998 <para>If <computeroutput>strict</computeroutput> is an option specified
2999 in <computeroutput>MPIWRAP_DEBUG</computeroutput>, the application
3000 will abort if an unhandled type is encountered. Otherwise, the
3001 application will print a warning message and continue.</para>
3003 <para>Some effort is made to mark/check memory ranges corresponding to
3004 arrays of values in a single pass. This is important for performance
3005 since asking Valgrind to mark/check any range, no matter how small,
3006 carries quite a large constant cost. This optimisation is applied to
3007 arrays of primitive types (<computeroutput>double</computeroutput>,
3008 <computeroutput>float</computeroutput>,
3009 <computeroutput>int</computeroutput>,
3010 <computeroutput>long</computeroutput>, <computeroutput>long
3011 long</computeroutput>, <computeroutput>short</computeroutput>,
3012 <computeroutput>char</computeroutput>, and <computeroutput>long
3013 double</computeroutput> on platforms where <computeroutput>sizeof(long
3014 double) == 8</computeroutput>). For arrays of all other types, the
3015 wrappers handle each element individually and so there can be a very
3016 large performance cost.</para>
3021 <sect2 id="mc-manual.mpiwrap.writingwrappers"
3022 xreflabel="Writing new MPI Wrappers">
3023 <title>Writing new wrappers</title>
3026 For the most part the wrappers are straightforward. The only
3027 significant complexity arises with nonblocking receives.</para>
3029 <para>The issue is that <computeroutput>MPI_Irecv</computeroutput>
3030 states the recv buffer and returns immediately, giving a handle
3031 (<computeroutput>MPI_Request</computeroutput>) for the transaction.
3032 Later the user will have to poll for completion with
3033 <computeroutput>MPI_Wait</computeroutput> etc, and when the
3034 transaction completes successfully, the wrappers have to paint the
3035 recv buffer. But the recv buffer details are not presented to
3036 <computeroutput>MPI_Wait</computeroutput> -- only the handle is. The
3037 library therefore maintains a shadow table which associates
3038 uncompleted <computeroutput>MPI_Request</computeroutput>s with the
3039 corresponding buffer address/count/type. When an operation completes,
3040 the table is searched for the associated address/count/type info, and
3041 memory is marked accordingly.</para>
3043 <para>Access to the table is guarded by a (POSIX pthreads) lock, so as
3044 to make the library thread-safe.</para>
3046 <para>The table is allocated with
3047 <computeroutput>malloc</computeroutput> and never
3048 <computeroutput>free</computeroutput>d, so it will show up in leak
3051 <para>Writing new wrappers should be fairly easy. The source file is
3052 <computeroutput>mpi/libmpiwrap.c</computeroutput>. If possible,
3053 find an existing wrapper for a function of similar behaviour to the
3054 one you want to wrap, and use it as a starting point. The wrappers
3055 are organised in sections in the same order as the MPI 1.1 spec, to
3056 aid navigation. When adding a wrapper, remember to comment out the
3057 definition of the default wrapper in the long list of defaults at the
3058 bottom of the file (do not remove it, just comment it out).</para>
3061 <sect2 id="mc-manual.mpiwrap.whattoexpect"
3062 xreflabel="What to expect with MPI Wrappers">
3063 <title>What to expect when using the wrappers</title>
3065 <para>The wrappers should reduce Memcheck's false-error rate on MPI
3066 applications. Because the wrapping is done at the MPI interface,
3067 there will still potentially be a large number of errors reported in
3068 the MPI implementation below the interface. The best you can do is
3069 try to suppress them.</para>
3071 <para>You may also find that the input-side (buffer
3072 length/definedness) checks find errors in your MPI use, for example
3073 passing too short a buffer to
3074 <computeroutput>MPI_Recv</computeroutput>.</para>
3076 <para>Functions which are not wrapped may increase the false
3077 error rate. A possible approach is to run with
3078 <computeroutput>MPI_DEBUG</computeroutput> containing
3079 <computeroutput>warn</computeroutput>. This will show you functions
3080 which lack proper wrappers but which are nevertheless used. You can
3081 then write wrappers for them.
3084 <para>A known source of potential false errors are the
3085 <computeroutput>PMPI_Reduce</computeroutput> family of functions, when
3086 using a custom (user-defined) reduction function. In a reduction
3087 operation, each node notionally sends data to a "central point" which
3088 uses the specified reduction function to merge the data items into a
3089 single item. Hence, in general, data is passed between nodes and fed
3090 to the reduction function, but the wrapper library cannot mark the
3091 transferred data as initialised before it is handed to the reduction
3092 function, because all that happens "inside" the
3093 <computeroutput>PMPI_Reduce</computeroutput> call. As a result you
3094 may see false positives reported in your reduction function.</para>