1 <?xml version="1.0"?> <!-- -*- sgml -*- -->
2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 <chapter id="mc-manual" xreflabel="Memcheck: a memory error detector">
7 <title>Memcheck: a memory error detector</title>
9 <para>To use this tool, you may specify <option>--tool=memcheck</option>
10 on the Valgrind command line. You don't have to, though, since Memcheck
11 is the default tool.</para>
14 <sect1 id="mc-manual.overview" xreflabel="Overview">
15 <title>Overview</title>
17 <para>Memcheck is a memory error detector. It can detect the following
18 problems that are common in C and C++ programs.</para>
22 <para>Accessing memory you shouldn't, e.g. overrunning and underrunning
23 heap blocks, overrunning the top of the stack, and accessing memory after
24 it has been freed.</para>
28 <para>Using undefined values, i.e. values that have not been initialised,
29 or that have been derived from other undefined values.</para>
33 <para>Incorrect freeing of heap memory, such as double-freeing heap
34 blocks, or mismatched use of
35 <function>malloc</function>/<computeroutput>new</computeroutput>/<computeroutput>new[]</computeroutput>
37 <function>free</function>/<computeroutput>delete</computeroutput>/<computeroutput>delete[]</computeroutput></para>
41 <para>Overlapping <computeroutput>src</computeroutput> and
42 <computeroutput>dst</computeroutput> pointers in
43 <computeroutput>memcpy</computeroutput> and related
48 <para>Memory leaks.</para>
52 <para>Problems like these can be difficult to find by other means,
53 often remaining undetected for long periods, then causing occasional,
54 difficult-to-diagnose crashes.</para>
60 <sect1 id="mc-manual.errormsgs"
61 xreflabel="Explanation of error messages from Memcheck">
62 <title>Explanation of error messages from Memcheck</title>
64 <para>Memcheck issues a range of error messages. This section presents a
65 quick summary of what error messages mean. The precise behaviour of the
66 error-checking machinery is described in <xref
67 linkend="mc-manual.machine"/>.</para>
70 <sect2 id="mc-manual.badrw"
71 xreflabel="Illegal read / Illegal write errors">
72 <title>Illegal read / Illegal write errors</title>
74 <para>For example:</para>
75 <programlisting><![CDATA[
76 Invalid read of size 4
77 at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9)
78 by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9)
79 by 0x40B07FF4: read_png_image(QImageIO *) (kernel/qpngio.cpp:326)
80 by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
81 Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd
84 <para>This happens when your program reads or writes memory at a place
85 which Memcheck reckons it shouldn't. In this example, the program did a
86 4-byte read at address 0xBFFFF0E0, somewhere within the system-supplied
87 library libpng.so.2.1.0.9, which was called from somewhere else in the
88 same library, called from line 326 of <filename>qpngio.cpp</filename>,
91 <para>Memcheck tries to establish what the illegal address might relate
92 to, since that's often useful. So, if it points into a block of memory
93 which has already been freed, you'll be informed of this, and also where
94 the block was freed. Likewise, if it should turn out to be just off
95 the end of a heap block, a common result of off-by-one-errors in
96 array subscripting, you'll be informed of this fact, and also where the
97 block was allocated. If you use the <option><xref
98 linkend="opt.read-var-info"/></option> option Memcheck will run more slowly
99 but may give a more detailed description of any illegal address.</para>
101 <para>In this example, Memcheck can't identify the address. Actually
102 the address is on the stack, but, for some reason, this is not a valid
103 stack address -- it is below the stack pointer and that isn't allowed.
104 In this particular case it's probably caused by GCC generating invalid
105 code, a known bug in some ancient versions of GCC.</para>
107 <para>Note that Memcheck only tells you that your program is about to
108 access memory at an illegal address. It can't stop the access from
109 happening. So, if your program makes an access which normally would
110 result in a segmentation fault, you program will still suffer the same
111 fate -- but you will get a message from Memcheck immediately prior to
112 this. In this particular example, reading junk on the stack is
113 non-fatal, and the program stays alive.</para>
119 <sect2 id="mc-manual.uninitvals"
120 xreflabel="Use of uninitialised values">
121 <title>Use of uninitialised values</title>
123 <para>For example:</para>
124 <programlisting><![CDATA[
125 Conditional jump or move depends on uninitialised value(s)
126 at 0x402DFA94: _IO_vfprintf (_itoa.h:49)
127 by 0x402E8476: _IO_printf (printf.c:36)
128 by 0x8048472: main (tests/manuel1.c:8)
131 <para>An uninitialised-value use error is reported when your program
132 uses a value which hasn't been initialised -- in other words, is
133 undefined. Here, the undefined value is used somewhere inside the
134 <function>printf</function> machinery of the C library. This error was
135 reported when running the following small program:</para>
136 <programlisting><![CDATA[
140 printf ("x = %d\n", x);
141 }]]></programlisting>
143 <para>It is important to understand that your program can copy around
144 junk (uninitialised) data as much as it likes. Memcheck observes this
145 and keeps track of the data, but does not complain. A complaint is
146 issued only when your program attempts to make use of uninitialised
147 data in a way that might affect your program's externally-visible behaviour.
148 In this example, <varname>x</varname> is uninitialised. Memcheck observes
149 the value being passed to <function>_IO_printf</function> and thence to
150 <function>_IO_vfprintf</function>, but makes no comment. However,
151 <function>_IO_vfprintf</function> has to examine the value of
152 <varname>x</varname> so it can turn it into the corresponding ASCII string,
153 and it is at this point that Memcheck complains.</para>
155 <para>Sources of uninitialised data tend to be:</para>
158 <para>Local variables in procedures which have not been initialised,
159 as in the example above.</para>
162 <para>The contents of heap blocks (allocated with
163 <function>malloc</function>, <function>new</function>, or a similar
164 function) before you (or a constructor) write something there.
169 <para>To see information on the sources of uninitialised data in your
170 program, use the <option>--track-origins=yes</option> option. This
171 makes Memcheck run more slowly, but can make it much easier to track down
172 the root causes of uninitialised value errors.</para>
178 <sect2 id="mc-manual.bad-syscall-args"
179 xreflabel="Use of uninitialised or unaddressable values in system
181 <title>Use of uninitialised or unaddressable values in system
184 <para>Memcheck checks all parameters to system calls:
187 <para>It checks all the direct parameters themselves, whether they are
191 <para>Also, if a system call needs to read from a buffer provided by
192 your program, Memcheck checks that the entire buffer is addressable
193 and its contents are initialised.</para>
196 <para>Also, if the system call needs to write to a user-supplied
197 buffer, Memcheck checks that the buffer is addressable.</para>
202 <para>After the system call, Memcheck updates its tracked information to
203 precisely reflect any changes in memory state caused by the system
206 <para>Here's an example of two system calls with invalid parameters:</para>
207 <programlisting><![CDATA[
212 char* arr = malloc(10);
213 int* arr2 = malloc(sizeof(int));
214 write( 1 /* stdout */, arr, 10 );
219 <para>You get these complaints ...</para>
220 <programlisting><![CDATA[
221 Syscall param write(buf) points to uninitialised byte(s)
222 at 0x25A48723: __write_nocancel (in /lib/tls/libc-2.3.3.so)
223 by 0x259AFAD3: __libc_start_main (in /lib/tls/libc-2.3.3.so)
224 by 0x8048348: (within /auto/homes/njn25/grind/head4/a.out)
225 Address 0x25AB8028 is 0 bytes inside a block of size 10 alloc'd
226 at 0x259852B0: malloc (vg_replace_malloc.c:130)
227 by 0x80483F1: main (a.c:5)
229 Syscall param exit(error_code) contains uninitialised byte(s)
230 at 0x25A21B44: __GI__exit (in /lib/tls/libc-2.3.3.so)
231 by 0x8048426: main (a.c:8)
234 <para>... because the program has (a) written uninitialised junk
235 from the heap block to the standard output, and (b) passed an
236 uninitialised value to <function>exit</function>. Note that the first
237 error refers to the memory pointed to by
238 <computeroutput>buf</computeroutput> (not
239 <computeroutput>buf</computeroutput> itself), but the second error
240 refers directly to <computeroutput>exit</computeroutput>'s argument
241 <computeroutput>arr2[0]</computeroutput>.</para>
246 <sect2 id="mc-manual.badfrees" xreflabel="Illegal frees">
247 <title>Illegal frees</title>
249 <para>For example:</para>
250 <programlisting><![CDATA[
252 at 0x4004FFDF: free (vg_clientmalloc.c:577)
253 by 0x80484C7: main (tests/doublefree.c:10)
254 Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd
255 at 0x4004FFDF: free (vg_clientmalloc.c:577)
256 by 0x80484C7: main (tests/doublefree.c:10)
259 <para>Memcheck keeps track of the blocks allocated by your program
260 with <function>malloc</function>/<computeroutput>new</computeroutput>,
261 so it can know exactly whether or not the argument to
262 <function>free</function>/<computeroutput>delete</computeroutput> is
263 legitimate or not. Here, this test program has freed the same block
264 twice. As with the illegal read/write errors, Memcheck attempts to
265 make sense of the address freed. If, as here, the address is one
266 which has previously been freed, you wil be told that -- making
267 duplicate frees of the same block easy to spot. You will also get this
268 message if you try to free a pointer that doesn't point to the start of a
274 <sect2 id="mc-manual.rudefn"
275 xreflabel="When a heap block is freed with an inappropriate deallocation
277 <title>When a heap block is freed with an inappropriate deallocation
280 <para>In the following example, a block allocated with
281 <function>new[]</function> has wrongly been deallocated with
282 <function>free</function>:</para>
283 <programlisting><![CDATA[
284 Mismatched free() / delete / delete []
285 at 0x40043249: free (vg_clientfuncs.c:171)
286 by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149)
287 by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60)
288 by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44)
289 Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd
290 at 0x4004318C: operator new[](unsigned int) (vg_clientfuncs.c:152)
291 by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314)
292 by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
293 by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)
296 <para>In <literal>C++</literal> it's important to deallocate memory in a
297 way compatible with how it was allocated. The deal is:</para>
300 <para>If allocated with
301 <function>malloc</function>,
302 <function>calloc</function>,
303 <function>realloc</function>,
304 <function>valloc</function> or
305 <function>memalign</function>, you must
306 deallocate with <function>free</function>.</para>
309 <para>If allocated with <function>new</function>, you must deallocate
310 with <function>delete</function>.</para>
313 <para>If allocated with <function>new[]</function>, you must
314 deallocate with <function>delete[]</function>.</para>
318 <para>The worst thing is that on Linux apparently it doesn't matter if
319 you do mix these up, but the same program may then crash on a
320 different platform, Solaris for example. So it's best to fix it
321 properly. According to the KDE folks "it's amazing how many C++
322 programmers don't know this".</para>
324 <para>The reason behind the requirement is as follows. In some C++
325 implementations, <function>delete[]</function> must be used for
326 objects allocated by <function>new[]</function> because the compiler
327 stores the size of the array and the pointer-to-member to the
328 destructor of the array's content just before the pointer actually
329 returned. <function>delete</function> doesn't account for this and will get
330 confused, possibly corrupting the heap.</para>
336 <sect2 id="mc-manual.overlap"
337 xreflabel="Overlapping source and destination blocks">
338 <title>Overlapping source and destination blocks</title>
340 <para>The following C library functions copy some data from one
341 memory block to another (or something similar):
342 <function>memcpy</function>,
343 <function>strcpy</function>,
344 <function>strncpy</function>,
345 <function>strcat</function>,
346 <function>strncat</function>.
347 The blocks pointed to by their <computeroutput>src</computeroutput> and
348 <computeroutput>dst</computeroutput> pointers aren't allowed to overlap.
349 The POSIX standards have wording along the lines "If copying takes place
350 between objects that overlap, the behavior is undefined." Therefore,
351 Memcheck checks for this.
354 <para>For example:</para>
355 <programlisting><![CDATA[
356 ==27492== Source and destination overlap in memcpy(0xbffff294, 0xbffff280, 21)
357 ==27492== at 0x40026CDC: memcpy (mc_replace_strmem.c:71)
358 ==27492== by 0x804865A: main (overlap.c:40)
361 <para>You don't want the two blocks to overlap because one of them could
362 get partially overwritten by the copying.</para>
364 <para>You might think that Memcheck is being overly pedantic reporting
365 this in the case where <computeroutput>dst</computeroutput> is less than
366 <computeroutput>src</computeroutput>. For example, the obvious way to
367 implement <function>memcpy</function> is by copying from the first
368 byte to the last. However, the optimisation guides of some
369 architectures recommend copying from the last byte down to the first.
370 Also, some implementations of <function>memcpy</function> zero
371 <computeroutput>dst</computeroutput> before copying, because zeroing the
372 destination's cache line(s) can improve performance.</para>
374 <para>The moral of the story is: if you want to write truly portable
375 code, don't make any assumptions about the language
376 implementation.</para>
381 <sect2 id="mc-manual.leaks" xreflabel="Memory leak detection">
382 <title>Memory leak detection</title>
384 <para>Memcheck keeps track of all heap blocks issued in response to
386 <function>malloc</function>/<function>new</function> et al.
387 So when the program exits, it knows which blocks have not been freed.
390 <para>If <option>--leak-check</option> is set appropriately, for each
391 remaining block, Memcheck determines if the block is reachable from pointers
392 within the root-set. The root-set consists of (a) general purpose registers
393 of all threads, and (b) initialised, aligned, pointer-sized data words in
394 accessible client memory, including stacks.</para>
396 <para>There are two ways a block can be reached. The first is with a
397 "start-pointer", i.e. a pointer to the start of the block. The second is with
398 an "interior-pointer", i.e. a pointer to the middle of the block. There are
399 three ways we know of that an interior-pointer can occur:</para>
403 <para>The pointer might have originally been a start-pointer and have been
404 moved along deliberately (or not deliberately) by the program. In
405 particular, this can happen if your program uses tagged pointers, i.e.
406 if it uses the bottom one, two or three bits of a pointer, which are
407 normally always zero due to alignment, in order to store extra
412 <para>It might be a random junk value in memory, entirely unrelated, just
413 a coincidence.</para>
417 <para>It might be a pointer to an array of C++ objects (which possess
418 destructors) allocated with <computeroutput>new[]</computeroutput>. In
419 this case, some compilers store a "magic cookie" containing the array
420 length at the start of the allocated block, and return a pointer to just
421 past that magic cookie, i.e. an interior-pointer.
422 See <ulink url="http://theory.uwinnipeg.ca/gnu/gcc/gxxint_14.html">this
423 page</ulink> for more information.</para>
427 <para>With that in mind, consider the nine possible cases described by the
428 following figure.</para>
430 <programlisting><![CDATA[
431 Pointer chain AAA Category BBB Category
432 ------------- ------------ ------------
433 (1) RRR ------------> BBB DR
434 (2) RRR ---> AAA ---> BBB DR IR
436 (4) RRR AAA ---> BBB DL IL
437 (5) RRR ------?-----> BBB (y)DR, (n)DL
438 (6) RRR ---> AAA -?-> BBB DR (y)IR, (n)DL
439 (7) RRR -?-> AAA ---> BBB (y)DR, (n)DL (y)IR, (n)IL
440 (8) RRR -?-> AAA -?-> BBB (y)DR, (n)DL (y,y)IR, (n,y)IL, (_,n)DL
441 (9) RRR AAA -?-> BBB DL (y)IL, (n)DL
443 Pointer chain legend:
444 - RRR: a root set node or DR block
445 - AAA, BBB: heap blocks
446 - --->: a start-pointer
447 - -?->: an interior-pointer
450 - DR: Directly reachable
451 - IR: Indirectly reachable
453 - IL: Indirectly lost
454 - (y)XY: it's XY if the interior-pointer is a real pointer
455 - (n)XY: it's XY if the interior-pointer is not a real pointer
456 - (_)XY: it's XY in either case
459 <para>Every possible case can be reduced to one of the above nine. Memcheck
460 merges some of these cases in its output, resulting in the following four
467 <para>"Still reachable". This covers cases 1 and 2 (for the BBB blocks)
468 above. A start-pointer or chain of start-pointers to the block is
469 found. Since the block is still pointed at, the programmer could, at
470 least in principle, have freed it before program exit. Because these
471 are very common and arguably not a problem, Memcheck won't report such
472 blocks individually unless <option>--show-reachable=yes</option> is
477 <para>"Definitely lost". This covers case 3 (for the BBB blocks) above.
478 This means that no pointer to the block can be found. The block is
479 classified as "lost", because the programmer could not possibly have
480 freed it at program exit, since no pointer to it exists. This is likely
481 a symptom of having lost the pointer at some earlier point in the
482 program. Such cases should be fixed by the programmer.</para>
486 <para>"Indirectly lost". This covers cases 4 and 9 (for the BBB blocks)
487 above. This means that the block is lost, not because there are no
488 pointers to it, but rather because all the blocks that point to it are
489 themselves lost. For example, if you have a binary tree and the root
490 node is lost, all its children nodes will be indirectly lost. Because
491 the problem will disappear if the definitely lost block that caused the
492 indirect leak is fixed, Memcheck won't report such blocks individually
493 unless <option>--show-reachable=yes</option> is specified.</para>
497 <para>"Possibly lost". This covers cases 5--8 (for the BBB blocks)
498 above. This means that a chain of one or more pointers to the block has
499 been found, but at least one of the pointers is an interior-pointer.
500 This could just be a random value in memory that happens to point into a
501 block, and so you shouldn't consider this ok unless you know you have
502 interior-pointers.</para>
507 <para>(Note: This mapping of the nine possible cases onto four categories is
508 not necessarily the best way that leaks could be reported; in particular,
509 interior-pointers are treated inconsistently. It is possible the
510 categorisation may be improved in the future.)</para>
512 <para>Furthermore, if suppressions exists for a block, it will be reported
513 as "suppressed" no matter what which of the above four categories it belongs
517 <para>The following is an example leak summary.</para>
519 <programlisting><![CDATA[
521 definitely lost: 48 bytes in 3 blocks.
522 indirectly lost: 32 bytes in 2 blocks.
523 possibly lost: 96 bytes in 6 blocks.
524 still reachable: 64 bytes in 4 blocks.
525 suppressed: 0 bytes in 0 blocks.
528 <para>If <option>--leak-check=full</option> is specified,
529 Memcheck will give details for each definitely lost or possibly lost block,
530 including where it was allocated. (Actually, it merges results for all
531 blocks that have the same category and sufficiently similar stack traces
532 into a single "loss record". The
533 <option>--leak-resolution</option> lets you control the
534 meaning of "sufficiently similar".) It cannot tell you when or how or why
535 the pointer to a leaked block was lost; you have to work that out for
536 yourself. In general, you should attempt to ensure your programs do not
537 have any definitely lost or possibly lost blocks at exit.</para>
539 <para>For example:</para>
540 <programlisting><![CDATA[
541 8 bytes in 1 blocks are definitely lost in loss record 1 of 14
542 at 0x........: malloc (vg_replace_malloc.c:...)
543 by 0x........: mk (leak-tree.c:11)
544 by 0x........: main (leak-tree.c:39)
546 88 (8 direct, 80 indirect) bytes in 1 blocks are definitely lost in loss record 13 of 14
547 at 0x........: malloc (vg_replace_malloc.c:...)
548 by 0x........: mk (leak-tree.c:11)
549 by 0x........: main (leak-tree.c:25)
552 <para>The first message describes a simple case of a single 8 byte block
553 that has been definitely lost. The second case mentions another 8 byte
554 block that has been definitely lost; the difference is that a further 80
555 bytes in other blocks are indirectly lost because of this lost block.
556 The loss records are not presented in any notable order, so the loss record
557 numbers aren't particularly meaningful.</para>
559 <para>If you specify <option>--show-reachable=yes</option>,
560 reachable and indirectly lost blocks will also be shown, as the following
561 two examples show.</para>
563 <programlisting><![CDATA[
564 64 bytes in 4 blocks are still reachable in loss record 2 of 4
565 at 0x........: malloc (vg_replace_malloc.c:177)
566 by 0x........: mk (leak-cases.c:52)
567 by 0x........: main (leak-cases.c:74)
569 32 bytes in 2 blocks are indirectly lost in loss record 1 of 4
570 at 0x........: malloc (vg_replace_malloc.c:177)
571 by 0x........: mk (leak-cases.c:52)
572 by 0x........: main (leak-cases.c:80)
575 <para>Because there are different kinds of leaks with different severities, an
576 interesting question is this: which leaks should be counted as true "errors"
577 and which should not? The answer to this question affects the numbers printed
578 in the <computeroutput>ERROR SUMMARY</computeroutput> line, and also the effect
579 of the <option>--error-exitcode</option> option. Memcheck uses the following
584 <para>First, a leak is only counted as a true "error" if
585 <option>--leak-check=full</option> is specified. In other words, an
586 unprinted leak is not considered a true "error". If this were not the
587 case, it would be possible to get a high error count but not have any
588 errors printed, which would be confusing.</para>
592 <para>After that, definitely lost and possibly lost blocks are counted as
593 true "errors". Indirectly lost and still reachable blocks are not counted
594 as true "errors", even if <option>--show-reachable=yes</option> is
595 specified and they are printed; this is because such blocks don't need
596 direct fixing by the programmer.
607 <sect1 id="mc-manual.options"
608 xreflabel="Memcheck Command-Line Options">
609 <title>Memcheck Command-Line Options</title>
611 <!-- start of xi:include in the manpage -->
612 <variablelist id="mc.opts.list">
614 <varlistentry id="opt.leak-check" xreflabel="--leak-check">
616 <option><![CDATA[--leak-check=<no|summary|yes|full> [default: summary] ]]></option>
619 <para>When enabled, search for memory leaks when the client
620 program finishes. If set to <varname>summary</varname>, it says how
621 many leaks occurred. If set to <varname>full</varname> or
622 <varname>yes</varname>, it also gives details of each individual
627 <varlistentry id="opt.show-possibly-lost" xreflabel="--show-possibly-lost">
629 <option><![CDATA[--show-possibly-lost=<yes|no> [default: yes] ]]></option>
632 <para>When disabled, the memory leak detector will not show "possibly lost" blocks.
637 <varlistentry id="opt.leak-resolution" xreflabel="--leak-resolution">
639 <option><![CDATA[--leak-resolution=<low|med|high> [default: high] ]]></option>
642 <para>When doing leak checking, determines how willing
643 Memcheck is to consider different backtraces to
644 be the same for the purposes of merging multiple leaks into a single
645 leak report. When set to <varname>low</varname>, only the first
646 two entries need match. When <varname>med</varname>, four entries
647 have to match. When <varname>high</varname>, all entries need to
650 <para>For hardcore leak debugging, you probably want to use
651 <option>--leak-resolution=high</option> together with
652 <option>--num-callers=40</option> or some such large number.
655 <para>Note that the <option>--leak-resolution</option> setting
656 does not affect Memcheck's ability to find
657 leaks. It only changes how the results are presented.</para>
661 <varlistentry id="opt.show-reachable" xreflabel="--show-reachable">
663 <option><![CDATA[--show-reachable=<yes|no> [default: no] ]]></option>
666 <para>When disabled, the memory leak detector only shows "definitely
667 lost" and "possibly lost" blocks. When enabled, the leak detector also
668 shows "reachable" and "indirectly lost" blocks. (In other words, it
669 shows all blocks, except suppressed ones, so
670 <option>--show-all</option> would be a better name for
675 <varlistentry id="opt.undef-value-errors" xreflabel="--undef-value-errors">
677 <option><![CDATA[--undef-value-errors=<yes|no> [default: yes] ]]></option>
680 <para>Controls whether Memcheck reports
681 uses of undefined value errors. Set this to
682 <varname>no</varname> if you don't want to see undefined value
683 errors. It also has the side effect of speeding up
689 <varlistentry id="opt.track-origins" xreflabel="--track-origins">
691 <option><![CDATA[--track-origins=<yes|no> [default: no] ]]></option>
694 <para>Controls whether Memcheck tracks
695 the origin of uninitialised values. By default, it does not,
696 which means that although it can tell you that an
697 uninitialised value is being used in a dangerous way, it
698 cannot tell you where the uninitialised value came from. This
699 often makes it difficult to track down the root problem.
702 to <varname>yes</varname>, Memcheck keeps
703 track of the origins of all uninitialised values. Then, when
704 an uninitialised value error is
705 reported, Memcheck will try to show the
706 origin of the value. An origin can be one of the following
707 four places: a heap block, a stack allocation, a client
708 request, or miscellaneous other sources (eg, a call
709 to <varname>brk</varname>).
711 <para>For uninitialised values originating from a heap
712 block, Memcheck shows where the block was
713 allocated. For uninitialised values originating from a stack
714 allocation, Memcheck can tell you which
715 function allocated the value, but no more than that -- typically
716 it shows you the source location of the opening brace of the
717 function. So you should carefully check that all of the
718 function's local variables are initialised properly.
720 <para>Performance overhead: origin tracking is expensive. It
721 halves Memcheck's speed and increases
722 memory use by a minimum of 100MB, and possibly more.
723 Nevertheless it can drastically reduce the effort required to
724 identify the root cause of uninitialised value errors, and so
725 is often a programmer productivity win, despite running
728 <para>Accuracy: Memcheck tracks origins
729 quite accurately. To avoid very large space and time
730 overheads, some approximations are made. It is possible,
731 although unlikely, that Memcheck will report an incorrect origin, or
732 not be able to identify any origin.
734 <para>Note that the combination
735 <option>--track-origins=yes</option>
736 and <option>--undef-value-errors=no</option> is
737 nonsensical. Memcheck checks for and
738 rejects this combination at startup.
743 <varlistentry id="opt.partial-loads-ok" xreflabel="--partial-loads-ok">
745 <option><![CDATA[--partial-loads-ok=<yes|no> [default: no] ]]></option>
748 <para>Controls how Memcheck handles word-sized,
749 word-aligned loads from addresses for which some bytes are
750 addressable and others are not. When <varname>yes</varname>, such
751 loads do not produce an address error. Instead, loaded bytes
752 originating from illegal addresses are marked as uninitialised, and
753 those corresponding to legal addresses are handled in the normal
756 <para>When <varname>no</varname>, loads from partially invalid
757 addresses are treated the same as loads from completely invalid
758 addresses: an illegal-address error is issued, and the resulting
759 bytes are marked as initialised.</para>
761 <para>Note that code that behaves in this way is in violation of
762 the the ISO C/C++ standards, and should be considered broken. If
763 at all possible, such code should be fixed. This option should be
764 used only as a last resort.</para>
768 <varlistentry id="opt.freelist-vol" xreflabel="--freelist-vol">
770 <option><![CDATA[--freelist-vol=<number> [default: 20000000] ]]></option>
773 <para>When the client program releases memory using
774 <function>free</function> (in <literal>C</literal>) or
775 <computeroutput>delete</computeroutput>
776 (<literal>C++</literal>), that memory is not immediately made
777 available for re-allocation. Instead, it is marked inaccessible
778 and placed in a queue of freed blocks. The purpose is to defer as
779 long as possible the point at which freed-up memory comes back
780 into circulation. This increases the chance that
781 Memcheck will be able to detect invalid
782 accesses to blocks for some significant period of time after they
783 have been freed.</para>
785 <para>This option specifies the maximum total size, in bytes, of the
786 blocks in the queue. The default value is twenty million bytes.
787 Increasing this increases the total amount of memory used by
788 Memcheck but may detect invalid uses of freed
789 blocks which would otherwise go undetected.</para>
793 <varlistentry id="opt.workaround-gcc296-bugs" xreflabel="--workaround-gcc296-bugs">
795 <option><![CDATA[--workaround-gcc296-bugs=<yes|no> [default: no] ]]></option>
798 <para>When enabled, assume that reads and writes some small
799 distance below the stack pointer are due to bugs in GCC 2.96, and
800 does not report them. The "small distance" is 256 bytes by
801 default. Note that GCC 2.96 is the default compiler on some ancient
802 Linux distributions (RedHat 7.X) and so you may need to use this
803 option. Do not use it if you do not have to, as it can cause real
804 errors to be overlooked. A better alternative is to use a more
805 recent GCC in which this bug is fixed.</para>
807 <para>You may also need to use this option when working with
808 GCC 3.X or 4.X on 32-bit PowerPC Linux. This is because
809 GCC generates code which occasionally accesses below the
810 stack pointer, particularly for floating-point to/from integer
811 conversions. This is in violation of the 32-bit PowerPC ELF
812 specification, which makes no provision for locations below the
813 stack pointer to be accessible.</para>
817 <varlistentry id="opt.ignore-ranges" xreflabel="--ignore-ranges">
819 <option><![CDATA[--ignore-ranges=0xPP-0xQQ[,0xRR-0xSS] ]]></option>
822 <para>Any ranges listed in this option (and multiple ranges can be
823 specified, separated by commas) will be ignored by Memcheck's
824 addressability checking.</para>
828 <varlistentry id="opt.malloc-fill" xreflabel="--malloc-fill">
830 <option><![CDATA[--malloc-fill=<hexnumber> ]]></option>
833 <para>Fills blocks allocated
834 by <computeroutput>malloc</computeroutput>,
835 <computeroutput>new</computeroutput>, etc, but not
836 by <computeroutput>calloc</computeroutput>, with the specified
837 byte. This can be useful when trying to shake out obscure
838 memory corruption problems. The allocated area is still
839 regarded by Memcheck as undefined -- this option only affects its
845 <varlistentry id="opt.free-fill" xreflabel="--free-fill">
847 <option><![CDATA[--free-fill=<hexnumber> ]]></option>
850 <para>Fills blocks freed
851 by <computeroutput>free</computeroutput>,
852 <computeroutput>delete</computeroutput>, etc, with the
853 specified byte value. This can be useful when trying to shake out
854 obscure memory corruption problems. The freed area is still
855 regarded by Memcheck as not valid for access -- this option only
856 affects its contents.
862 <!-- end of xi:include in the manpage -->
867 <sect1 id="mc-manual.suppfiles" xreflabel="Writing suppression files">
868 <title>Writing suppression files</title>
870 <para>The basic suppression format is described in
871 <xref linkend="manual-core.suppress"/>.</para>
873 <para>The suppression-type (second) line should have the form:</para>
874 <programlisting><![CDATA[
875 Memcheck:suppression_type]]></programlisting>
877 <para>The Memcheck suppression types are as follows:</para>
881 <para><varname>Value1</varname>,
882 <varname>Value2</varname>,
883 <varname>Value4</varname>,
884 <varname>Value8</varname>,
885 <varname>Value16</varname>,
886 meaning an uninitialised-value error when
887 using a value of 1, 2, 4, 8 or 16 bytes.</para>
891 <para><varname>Cond</varname> (or its old
892 name, <varname>Value0</varname>), meaning use
893 of an uninitialised CPU condition code.</para>
897 <para><varname>Addr1</varname>,
898 <varname>Addr2</varname>,
899 <varname>Addr4</varname>,
900 <varname>Addr8</varname>,
901 <varname>Addr16</varname>,
902 meaning an invalid address during a
903 memory access of 1, 2, 4, 8 or 16 bytes respectively.</para>
907 <para><varname>Jump</varname>, meaning an
908 jump to an unaddressable location error.</para>
912 <para><varname>Param</varname>, meaning an
913 invalid system call parameter error.</para>
917 <para><varname>Free</varname>, meaning an
918 invalid or mismatching free.</para>
922 <para><varname>Overlap</varname>, meaning a
923 <computeroutput>src</computeroutput> /
924 <computeroutput>dst</computeroutput> overlap in
925 <function>memcpy</function> or a similar function.</para>
929 <para><varname>Leak</varname>, meaning
930 a memory leak.</para>
935 <para><computeroutput>Param</computeroutput> errors have an extra
936 information line at this point, which is the name of the offending
937 system call parameter. No other error kinds have this extra
940 <para>The first line of the calling context: for <varname>ValueN</varname>
941 and <varname>AddrN</varname> errors, it is either the name of the function
942 in which the error occurred, or, failing that, the full path of the
943 <filename>.so</filename> file
944 or executable containing the error location. For <varname>Free</varname> errors, is the name
945 of the function doing the freeing (eg, <function>free</function>,
946 <function>__builtin_vec_delete</function>, etc). For
947 <varname>Overlap</varname> errors, is the name of the function with the
948 overlapping arguments (eg. <function>memcpy</function>,
949 <function>strcpy</function>, etc).</para>
951 <para>Lastly, there's the rest of the calling context.</para>
957 <sect1 id="mc-manual.machine"
958 xreflabel="Details of Memcheck's checking machinery">
959 <title>Details of Memcheck's checking machinery</title>
961 <para>Read this section if you want to know, in detail, exactly
962 what and how Memcheck is checking.</para>
965 <sect2 id="mc-manual.value" xreflabel="Valid-value (V) bit">
966 <title>Valid-value (V) bits</title>
968 <para>It is simplest to think of Memcheck implementing a synthetic CPU
969 which is identical to a real CPU, except for one crucial detail. Every
970 bit (literally) of data processed, stored and handled by the real CPU
971 has, in the synthetic CPU, an associated "valid-value" bit, which says
972 whether or not the accompanying bit has a legitimate value. In the
973 discussions which follow, this bit is referred to as the V (valid-value)
976 <para>Each byte in the system therefore has a 8 V bits which follow it
977 wherever it goes. For example, when the CPU loads a word-size item (4
978 bytes) from memory, it also loads the corresponding 32 V bits from a
979 bitmap which stores the V bits for the process' entire address space.
980 If the CPU should later write the whole or some part of that value to
981 memory at a different address, the relevant V bits will be stored back
982 in the V-bit bitmap.</para>
984 <para>In short, each bit in the system has (conceptually) an associated V
985 bit, which follows it around everywhere, even inside the CPU. Yes, all the
986 CPU's registers (integer, floating point, vector and condition registers)
987 have their own V bit vectors. For this to work, Memcheck uses a great deal
988 of compression to represent the V bits compactly.</para>
990 <para>Copying values around does not cause Memcheck to check for, or
991 report on, errors. However, when a value is used in a way which might
992 conceivably affect your program's externally-visible behaviour,
993 the associated V bits are immediately checked. If any of these indicate
994 that the value is undefined (even partially), an error is reported.</para>
996 <para>Here's an (admittedly nonsensical) example:</para>
997 <programlisting><![CDATA[
1000 for ( i = 0; i < 10; i++ ) {
1003 }]]></programlisting>
1005 <para>Memcheck emits no complaints about this, since it merely copies
1006 uninitialised values from <varname>a[]</varname> into
1007 <varname>b[]</varname>, and doesn't use them in a way which could
1008 affect the behaviour of the program. However, if
1009 the loop is changed to:</para>
1010 <programlisting><![CDATA[
1011 for ( i = 0; i < 10; i++ ) {
1015 printf("hello there\n");
1016 ]]></programlisting>
1018 <para>then Memcheck will complain, at the
1019 <computeroutput>if</computeroutput>, that the condition depends on
1020 uninitialised values. Note that it <command>doesn't</command> complain
1021 at the <varname>j += a[i];</varname>, since at that point the
1022 undefinedness is not "observable". It's only when a decision has to be
1023 made as to whether or not to do the <function>printf</function> -- an
1024 observable action of your program -- that Memcheck complains.</para>
1026 <para>Most low level operations, such as adds, cause Memcheck to use the
1027 V bits for the operands to calculate the V bits for the result. Even if
1028 the result is partially or wholly undefined, it does not
1031 <para>Checks on definedness only occur in three places: when a value is
1032 used to generate a memory address, when control flow decision needs to
1033 be made, and when a system call is detected, Memcheck checks definedness
1034 of parameters as required.</para>
1036 <para>If a check should detect undefinedness, an error message is
1037 issued. The resulting value is subsequently regarded as well-defined.
1038 To do otherwise would give long chains of error messages. In other
1039 words, once Memcheck reports an undefined value error, it tries to
1040 avoid reporting further errors derived from that same undefined
1043 <para>This sounds overcomplicated. Why not just check all reads from
1044 memory, and complain if an undefined value is loaded into a CPU
1045 register? Well, that doesn't work well, because perfectly legitimate C
1046 programs routinely copy uninitialised values around in memory, and we
1047 don't want endless complaints about that. Here's the canonical example.
1048 Consider a struct like this:</para>
1049 <programlisting><![CDATA[
1050 struct S { int x; char c; };
1055 ]]></programlisting>
1057 <para>The question to ask is: how large is <varname>struct S</varname>,
1058 in bytes? An <varname>int</varname> is 4 bytes and a
1059 <varname>char</varname> one byte, so perhaps a <varname>struct
1060 S</varname> occupies 5 bytes? Wrong. All non-toy compilers we know
1061 of will round the size of <varname>struct S</varname> up to a whole
1062 number of words, in this case 8 bytes. Not doing this forces compilers
1063 to generate truly appalling code for accessing arrays of
1064 <varname>struct S</varname>'s on some architectures.</para>
1066 <para>So <varname>s1</varname> occupies 8 bytes, yet only 5 of them will
1067 be initialised. For the assignment <varname>s2 = s1</varname>, GCC
1068 generates code to copy all 8 bytes wholesale into <varname>s2</varname>
1069 without regard for their meaning. If Memcheck simply checked values as
1070 they came out of memory, it would yelp every time a structure assignment
1071 like this happened. So the more complicated behaviour described above
1072 is necessary. This allows GCC to copy
1073 <varname>s1</varname> into <varname>s2</varname> any way it likes, and a
1074 warning will only be emitted if the uninitialised values are later
1080 <sect2 id="mc-manual.vaddress" xreflabel=" Valid-address (A) bits">
1081 <title>Valid-address (A) bits</title>
1083 <para>Notice that the previous subsection describes how the validity of
1084 values is established and maintained without having to say whether the
1085 program does or does not have the right to access any particular memory
1086 location. We now consider the latter question.</para>
1088 <para>As described above, every bit in memory or in the CPU has an
1089 associated valid-value (V) bit. In addition, all bytes in memory, but
1090 not in the CPU, have an associated valid-address (A) bit. This
1091 indicates whether or not the program can legitimately read or write that
1092 location. It does not give any indication of the validity of the data
1093 at that location -- that's the job of the V bits -- only whether or not
1094 the location may be accessed.</para>
1096 <para>Every time your program reads or writes memory, Memcheck checks
1097 the A bits associated with the address. If any of them indicate an
1098 invalid address, an error is emitted. Note that the reads and writes
1099 themselves do not change the A bits, only consult them.</para>
1101 <para>So how do the A bits get set/cleared? Like this:</para>
1105 <para>When the program starts, all the global data areas are
1106 marked as accessible.</para>
1110 <para>When the program does
1111 <function>malloc</function>/<computeroutput>new</computeroutput>,
1112 the A bits for exactly the area allocated, and not a byte more,
1113 are marked as accessible. Upon freeing the area the A bits are
1114 changed to indicate inaccessibility.</para>
1118 <para>When the stack pointer register (<literal>SP</literal>) moves
1119 up or down, A bits are set. The rule is that the area from
1120 <literal>SP</literal> up to the base of the stack is marked as
1121 accessible, and below <literal>SP</literal> is inaccessible. (If
1122 that sounds illogical, bear in mind that the stack grows down, not
1123 up, on almost all Unix systems, including GNU/Linux.) Tracking
1124 <literal>SP</literal> like this has the useful side-effect that the
1125 section of stack used by a function for local variables etc is
1126 automatically marked accessible on function entry and inaccessible
1131 <para>When doing system calls, A bits are changed appropriately.
1132 For example, <literal>mmap</literal>
1133 magically makes files appear in the process'
1134 address space, so the A bits must be updated if <literal>mmap</literal>
1139 <para>Optionally, your program can tell Memcheck about such changes
1140 explicitly, using the client request mechanism described
1149 <sect2 id="mc-manual.together" xreflabel="Putting it all together">
1150 <title>Putting it all together</title>
1152 <para>Memcheck's checking machinery can be summarised as
1157 <para>Each byte in memory has 8 associated V (valid-value) bits,
1158 saying whether or not the byte has a defined value, and a single A
1159 (valid-address) bit, saying whether or not the program currently has
1160 the right to read/write that address. As mentioned above, heavy
1161 use of compression means the overhead is typically around 25%.</para>
1165 <para>When memory is read or written, the relevant A bits are
1166 consulted. If they indicate an invalid address, Memcheck emits an
1167 Invalid read or Invalid write error.</para>
1171 <para>When memory is read into the CPU's registers, the relevant V
1172 bits are fetched from memory and stored in the simulated CPU. They
1173 are not consulted.</para>
1177 <para>When a register is written out to memory, the V bits for that
1178 register are written back to memory too.</para>
1182 <para>When values in CPU registers are used to generate a memory
1183 address, or to determine the outcome of a conditional branch, the V
1184 bits for those values are checked, and an error emitted if any of
1185 them are undefined.</para>
1189 <para>When values in CPU registers are used for any other purpose,
1190 Memcheck computes the V bits for the result, but does not check
1195 <para>Once the V bits for a value in the CPU have been checked, they
1196 are then set to indicate validity. This avoids long chains of
1201 <para>When values are loaded from memory, Memcheck checks the A bits
1202 for that location and issues an illegal-address warning if needed.
1203 In that case, the V bits loaded are forced to indicate Valid,
1204 despite the location being invalid.</para>
1206 <para>This apparently strange choice reduces the amount of confusing
1207 information presented to the user. It avoids the unpleasant
1208 phenomenon in which memory is read from a place which is both
1209 unaddressable and contains invalid values, and, as a result, you get
1210 not only an invalid-address (read/write) error, but also a
1211 potentially large set of uninitialised-value errors, one for every
1212 time the value is used.</para>
1214 <para>There is a hazy boundary case to do with multi-byte loads from
1215 addresses which are partially valid and partially invalid. See
1216 details of the option <option>--partial-loads-ok</option> for details.
1223 <para>Memcheck intercepts calls to <function>malloc</function>,
1224 <function>calloc</function>, <function>realloc</function>,
1225 <function>valloc</function>, <function>memalign</function>,
1226 <function>free</function>, <computeroutput>new</computeroutput>,
1227 <computeroutput>new[]</computeroutput>,
1228 <computeroutput>delete</computeroutput> and
1229 <computeroutput>delete[]</computeroutput>. The behaviour you get
1235 <para><function>malloc</function>/<function>new</function>/<computeroutput>new[]</computeroutput>:
1236 the returned memory is marked as addressable but not having valid
1237 values. This means you have to write to it before you can read
1242 <para><function>calloc</function>: returned memory is marked both
1243 addressable and valid, since <function>calloc</function> clears
1244 the area to zero.</para>
1248 <para><function>realloc</function>: if the new size is larger than
1249 the old, the new section is addressable but invalid, as with
1250 <function>malloc</function>. If the new size is smaller, the
1251 dropped-off section is marked as unaddressable. You may only pass to
1252 <function>realloc</function> a pointer previously issued to you by
1253 <function>malloc</function>/<function>calloc</function>/<function>realloc</function>.</para>
1257 <para><function>free</function>/<computeroutput>delete</computeroutput>/<computeroutput>delete[]</computeroutput>:
1258 you may only pass to these functions a pointer previously issued
1259 to you by the corresponding allocation function. Otherwise,
1260 Memcheck complains. If the pointer is indeed valid, Memcheck
1261 marks the entire area it points at as unaddressable, and places
1262 the block in the freed-blocks-queue. The aim is to defer as long
1263 as possible reallocation of this block. Until that happens, all
1264 attempts to access it will elicit an invalid-address error, as you
1273 <sect1 id="mc-manual.monitor-commands" xreflabel="Memcheck Monitor Commands">
1274 <title>Memcheck Monitor Commands</title>
1275 <para>The Memcheck tool provides monitor commands handled by the Valgrind
1276 gdbserver (see <xref linkend="manual-core.gdbserver-commandhandling"/>).
1281 <para><varname>mc.get_vbits <addr> [<len>]</varname>
1282 outputs the validity bits for the range of <len> (default 1)
1283 bytes at <addr>. The validity of each byte of the range is
1284 given using two hexadecimal digits. These hexadecimal digits are
1285 encoding the validity of each bit of the corresponding byte, using
1286 0 if the bit is valid and 1 if the bit is invalid. In the
1287 following example, 'string10' is an array of 10 characters in
1288 which one byte on two is undefined. If a byte is not addressable,
1289 its validity bits are replaced by __. In the below example, the byte 6
1290 is not addressable.</para>
1291 <programlisting><![CDATA[
1293 $4 = (char (*)[10]) 0x8049e28
1294 (gdb) monitor mc.get_vbits 0x8049e28 10
1295 ff00ff00 ff__ff00 ff00
1297 ]]></programlisting>
1301 <para><varname>mc.make_memory [noaccess|undefined|defined|ifaddressabledefined] <addr> [<len>]</varname>
1302 marks the range of <len> (default 1) bytes at <addr>
1303 with the given accessibility. Marking with 'noaccess' changes the
1304 (A) bits of the range to be not addressable. Marking with
1305 'undefined' or 'defined' are changing the definedness of the
1306 range. 'ifaddressabledefined' marks the range as defined but only
1307 if the range is addressable. In the following example, the first
1308 byte of the 'string10' is marked as defined.
1310 <programlisting><![CDATA[
1311 (gdb) monitor mc.make_memory defined 0x8049e28 1
1312 (gdb) monitor mc.get_vbits 0x8049e28 10
1313 0000ff00 ff00ff00 ff00
1315 ]]></programlisting>
1319 <para><varname>mc.check_memory [addressable|defined] <addr>
1320 [<len>]</varname> checks that the range of <len>
1321 (default 1) bytes at <addr> has the given accessibility. It
1322 then outputs a description of <addr>. In the below case, a
1323 detailed description is given as the option --read-var-info=yes
1324 was used to start Valgrind.
1326 <programlisting><![CDATA[
1327 (gdb) monitor mc.check_memory defined 0x8049e28 1
1328 Address 0x8049E28 len 1 defined
1329 ==14698== Location 0x8049e28 is 0 bytes inside string10[0],
1330 ==14698== declared at prog.c:10, in frame #0 of thread 1
1332 ]]></programlisting>
1336 <para><varname>mc.leak_check
1337 [full*|summary] [reachable|leakpossible*|definiteleak]</varname>
1338 starts a leak checking. The * in the arguments above indicates the
1339 default value. </para>
1341 <para> If the first argument is 'summary', only a summary of
1342 the leak search is given.
1345 <para>The second argument controls which entries are output
1346 for a 'full' leak search. The value 'definiteleak' indicates to
1347 output only the definitely leaked blocks. The value 'leakpossible'
1348 will output in addition the possibly leaked blocks. The value
1349 'reachable' will output all blocks (reachable, possibly leaked,
1352 <para>The below is an example of using the mc.leak_check monitor
1353 command on the leak-cases Memcheck regression tests.</para>
1354 <programlisting><![CDATA[
1355 (gdb) monitor mc.leak_check full leakpossible
1356 ==14729== 16 bytes in 1 blocks are possibly lost in loss record 13 of 16
1357 ==14729== at 0x4006E9E: malloc (vg_replace_malloc.c:236)
1358 ==14729== by 0x80484D5: mk (leak-cases.c:52)
1359 ==14729== by 0x804855F: f (leak-cases.c:81)
1360 ==14729== by 0x80488F5: main (leak-cases.c:107)
1362 ==14729== LEAK SUMMARY:
1363 ==14729== definitely lost: 32 bytes in 2 blocks
1364 ==14729== indirectly lost: 16 bytes in 1 blocks
1365 ==14729== possibly lost: 32 bytes in 2 blocks
1366 ==14729== still reachable: 96 bytes in 6 blocks
1367 ==14729== suppressed: 0 bytes in 0 blocks
1368 ==14729== Reachable blocks (those to which a pointer was found) are not shown.
1369 ==14729== To see them, rerun with: --leak-check=full --show-reachable=yes
1372 ==14729== LEAK SUMMARY:
1373 ==14729== definitely lost: 32 bytes in 2 blocks
1374 ==14729== indirectly lost: 16 bytes in 1 blocks
1375 ==14729== possibly lost: 32 bytes in 2 blocks
1376 ==14729== still reachable: 96 bytes in 6 blocks
1377 ==14729== suppressed: 0 bytes in 0 blocks
1378 ==14729== Reachable blocks (those to which a pointer was found) are not shown.
1379 ==14729== To see them, rerun with: --leak-check=full --show-reachable=yes
1382 ]]></programlisting>
1383 <para>Note that when using the Valgrind gdbserver, it is not
1384 needed to rerun with --leak-check=full --show-reachable=yes to see
1385 the reachable blocks. You can obtain the same information without
1386 rerunning by using the gdb command 'monitor mc.leak_check full
1387 reachable' (or, using abbreviation: 'mo mc.l f r').
1394 <sect1 id="mc-manual.clientreqs" xreflabel="Client requests">
1395 <title>Client Requests</title>
1397 <para>The following client requests are defined in
1398 <filename>memcheck.h</filename>.
1399 See <filename>memcheck.h</filename> for exact details of their
1405 <para><varname>VALGRIND_MAKE_MEM_NOACCESS</varname>,
1406 <varname>VALGRIND_MAKE_MEM_UNDEFINED</varname> and
1407 <varname>VALGRIND_MAKE_MEM_DEFINED</varname>.
1408 These mark address ranges as completely inaccessible,
1409 accessible but containing undefined data, and accessible and
1410 containing defined data, respectively.</para>
1414 <para><varname>VALGRIND_MAKE_MEM_DEFINED_IF_ADDRESSABLE</varname>.
1415 This is just like <varname>VALGRIND_MAKE_MEM_DEFINED</varname> but only
1416 affects those bytes that are already addressable.</para>
1420 <para><varname>VALGRIND_CHECK_MEM_IS_ADDRESSABLE</varname> and
1421 <varname>VALGRIND_CHECK_MEM_IS_DEFINED</varname>: check immediately
1422 whether or not the given address range has the relevant property,
1423 and if not, print an error message. Also, for the convenience of
1424 the client, returns zero if the relevant property holds; otherwise,
1425 the returned value is the address of the first byte for which the
1426 property is not true. Always returns 0 when not run on
1431 <para><varname>VALGRIND_CHECK_VALUE_IS_DEFINED</varname>: a quick and easy
1432 way to find out whether Valgrind thinks a particular value
1433 (lvalue, to be precise) is addressable and defined. Prints an error
1434 message if not. It has no return value.</para>
1438 <para><varname>VALGRIND_DO_LEAK_CHECK</varname>: does a full memory leak
1439 check (like <option>--leak-check=full</option>) right now.
1440 This is useful for incrementally checking for leaks between arbitrary
1441 places in the program's execution. It has no return value.</para>
1445 <para><varname>VALGRIND_DO_QUICK_LEAK_CHECK</varname>: like
1446 <varname>VALGRIND_DO_LEAK_CHECK</varname>, except it produces only a leak
1447 summary (like <option>--leak-check=summary</option>).
1448 It has no return value.</para>
1452 <para><varname>VALGRIND_COUNT_LEAKS</varname>: fills in the four
1453 arguments with the number of bytes of memory found by the previous
1454 leak check to be leaked (i.e. the sum of direct leaks and indirect leaks),
1455 dubious, reachable and suppressed. This is useful in test harness code,
1456 after calling <varname>VALGRIND_DO_LEAK_CHECK</varname> or
1457 <varname>VALGRIND_DO_QUICK_LEAK_CHECK</varname>.</para>
1461 <para><varname>VALGRIND_COUNT_LEAK_BLOCKS</varname>: identical to
1462 <varname>VALGRIND_COUNT_LEAKS</varname> except that it returns the
1463 number of blocks rather than the number of bytes in each
1468 <para><varname>VALGRIND_GET_VBITS</varname> and
1469 <varname>VALGRIND_SET_VBITS</varname>: allow you to get and set the
1470 V (validity) bits for an address range. You should probably only
1471 set V bits that you have got with
1472 <varname>VALGRIND_GET_VBITS</varname>. Only for those who really
1473 know what they are doing.</para>
1477 <para><varname>VALGRIND_CREATE_BLOCK</varname> and
1478 <varname>VALGRIND_DISCARD</varname>. <varname>VALGRIND_CREATE_BLOCK</varname>
1479 takes an address, a number of bytes and a character string. The
1480 specified address range is then associated with that string. When
1481 Memcheck reports an invalid access to an address in the range, it
1482 will describe it in terms of this block rather than in terms of
1483 any other block it knows about. Note that the use of this macro
1484 does not actually change the state of memory in any way -- it
1485 merely gives a name for the range.
1488 <para>At some point you may want Memcheck to stop reporting errors
1489 in terms of the block named
1490 by <varname>VALGRIND_CREATE_BLOCK</varname>. To make this
1491 possible, <varname>VALGRIND_CREATE_BLOCK</varname> returns a
1492 "block handle", which is a C <varname>int</varname> value. You
1493 can pass this block handle to <varname>VALGRIND_DISCARD</varname>.
1494 After doing so, Valgrind will no longer relate addressing errors
1495 in the specified range to the block. Passing invalid handles to
1496 <varname>VALGRIND_DISCARD</varname> is harmless.
1507 <sect1 id="mc-manual.mempools" xreflabel="Memory Pools">
1508 <title>Memory Pools: describing and working with custom allocators</title>
1510 <para>Some programs use custom memory allocators, often for performance
1511 reasons. Left to itself, Memcheck is unable to understand the
1512 behaviour of custom allocation schemes as well as it understands the
1513 standard allocators, and so may miss errors and leaks in your program. What
1514 this section describes is a way to give Memcheck enough of a description of
1515 your custom allocator that it can make at least some sense of what is
1518 <para>There are many different sorts of custom allocator, so Memcheck
1519 attempts to reason about them using a loose, abstract model. We
1520 use the following terminology when describing custom allocation
1525 <para>Custom allocation involves a set of independent "memory pools".
1529 <para>Memcheck's notion of a a memory pool consists of a single "anchor
1530 address" and a set of non-overlapping "chunks" associated with the
1531 anchor address.</para>
1534 <para>Typically a pool's anchor address is the address of a
1535 book-keeping "header" structure.</para>
1538 <para>Typically the pool's chunks are drawn from a contiguous
1539 "superblock" acquired through the system
1540 <function>malloc</function> or
1541 <function>mmap</function>.</para>
1546 <para>Keep in mind that the last two points above say "typically": the
1547 Valgrind mempool client request API is intentionally vague about the
1548 exact structure of a mempool. There is no specific mention made of
1549 headers or superblocks. Nevertheless, the following picture may help
1550 elucidate the intention of the terms in the API:</para>
1552 <programlisting><![CDATA[
1562 +------+---+--------------+---+------------------+
1563 | |rzB| allocation |rzB| |
1564 +------+---+--------------+---+------------------+
1567 "addr" "addr"+"size"
1568 ]]></programlisting>
1571 Note that the header and the superblock may be contiguous or
1572 discontiguous, and there may be multiple superblocks associated with a
1573 single header; such variations are opaque to Memcheck. The API
1574 only requires that your allocation scheme can present sensible values
1575 of "pool", "addr" and "size".</para>
1578 Typically, before making client requests related to mempools, a client
1579 program will have allocated such a header and superblock for their
1580 mempool, and marked the superblock NOACCESS using the
1581 <varname>VALGRIND_MAKE_MEM_NOACCESS</varname> client request.</para>
1584 When dealing with mempools, the goal is to maintain a particular
1585 invariant condition: that Memcheck believes the unallocated portions
1586 of the pool's superblock (including redzones) are NOACCESS. To
1587 maintain this invariant, the client program must ensure that the
1588 superblock starts out in that state; Memcheck cannot make it so, since
1589 Memcheck never explicitly learns about the superblock of a pool, only
1590 the allocated chunks within the pool.</para>
1593 Once the header and superblock for a pool are established and properly
1594 marked, there are a number of client requests programs can use to
1595 inform Memcheck about changes to the state of a mempool:</para>
1601 <varname>VALGRIND_CREATE_MEMPOOL(pool, rzB, is_zeroed)</varname>:
1602 This request registers the address <varname>pool</varname> as the anchor
1603 address for a memory pool. It also provides a size
1604 <varname>rzB</varname>, specifying how large the redzones placed around
1605 chunks allocated from the pool should be. Finally, it provides an
1606 <varname>is_zeroed</varname> argument that specifies whether the pool's
1607 chunks are zeroed (more precisely: defined) when allocated.
1610 Upon completion of this request, no chunks are associated with the
1611 pool. The request simply tells Memcheck that the pool exists, so that
1612 subsequent calls can refer to it as a pool.
1617 <para><varname>VALGRIND_DESTROY_MEMPOOL(pool)</varname>:
1618 This request tells Memcheck that a pool is being torn down. Memcheck
1619 then removes all records of chunks associated with the pool, as well
1620 as its record of the pool's existence. While destroying its records of
1621 a mempool, Memcheck resets the redzones of any live chunks in the pool
1627 <para><varname>VALGRIND_MEMPOOL_ALLOC(pool, addr, size)</varname>:
1628 This request informs Memcheck that a <varname>size</varname>-byte chunk
1629 has been allocated at <varname>addr</varname>, and associates the chunk with the
1631 <varname>pool</varname>. If the pool was created with nonzero
1632 <varname>rzB</varname> redzones, Memcheck will mark the
1633 <varname>rzB</varname> bytes before and after the chunk as NOACCESS. If
1634 the pool was created with the <varname>is_zeroed</varname> argument set,
1635 Memcheck will mark the chunk as DEFINED, otherwise Memcheck will mark
1636 the chunk as UNDEFINED.
1641 <para><varname>VALGRIND_MEMPOOL_FREE(pool, addr)</varname>:
1642 This request informs Memcheck that the chunk at <varname>addr</varname>
1643 should no longer be considered allocated. Memcheck will mark the chunk
1644 associated with <varname>addr</varname> as NOACCESS, and delete its
1645 record of the chunk's existence.
1650 <para><varname>VALGRIND_MEMPOOL_TRIM(pool, addr, size)</varname>:
1651 This request trims the chunks associated with <varname>pool</varname>.
1652 The request only operates on chunks associated with
1653 <varname>pool</varname>. Trimming is formally defined as:</para>
1656 <para> All chunks entirely inside the range
1657 <varname>addr..(addr+size-1)</varname> are preserved.</para>
1660 <para>All chunks entirely outside the range
1661 <varname>addr..(addr+size-1)</varname> are discarded, as though
1662 <varname>VALGRIND_MEMPOOL_FREE</varname> was called on them. </para>
1665 <para>All other chunks must intersect with the range
1666 <varname>addr..(addr+size-1)</varname>; areas outside the
1667 intersection are marked as NOACCESS, as though they had been
1668 independently freed with
1669 <varname>VALGRIND_MEMPOOL_FREE</varname>.</para>
1672 <para>This is a somewhat rare request, but can be useful in
1673 implementing the type of mass-free operations common in custom
1674 LIFO allocators.</para>
1678 <para><varname>VALGRIND_MOVE_MEMPOOL(poolA, poolB)</varname>: This
1679 request informs Memcheck that the pool previously anchored at
1680 address <varname>poolA</varname> has moved to anchor address
1681 <varname>poolB</varname>. This is a rare request, typically only needed
1682 if you <function>realloc</function> the header of a mempool.</para>
1683 <para>No memory-status bits are altered by this request.</para>
1688 <varname>VALGRIND_MEMPOOL_CHANGE(pool, addrA, addrB,
1689 size)</varname>: This request informs Memcheck that the chunk
1690 previously allocated at address <varname>addrA</varname> within
1691 <varname>pool</varname> has been moved and/or resized, and should be
1692 changed to cover the region <varname>addrB..(addrB+size-1)</varname>. This
1693 is a rare request, typically only needed if you
1694 <function>realloc</function> a superblock or wish to extend a chunk
1695 without changing its memory-status bits.
1697 <para>No memory-status bits are altered by this request.
1702 <para><varname>VALGRIND_MEMPOOL_EXISTS(pool)</varname>:
1703 This request informs the caller whether or not Memcheck is currently
1704 tracking a mempool at anchor address <varname>pool</varname>. It
1705 evaluates to 1 when there is a mempool associated with that address, 0
1706 otherwise. This is a rare request, only useful in circumstances when
1707 client code might have lost track of the set of active mempools.
1721 <sect1 id="mc-manual.mpiwrap" xreflabel="MPI Wrappers">
1722 <title>Debugging MPI Parallel Programs with Valgrind</title>
1724 <para>Memcheck supports debugging of distributed-memory applications
1725 which use the MPI message passing standard. This support consists of a
1726 library of wrapper functions for the
1727 <computeroutput>PMPI_*</computeroutput> interface. When incorporated
1728 into the application's address space, either by direct linking or by
1729 <computeroutput>LD_PRELOAD</computeroutput>, the wrappers intercept
1730 calls to <computeroutput>PMPI_Send</computeroutput>,
1731 <computeroutput>PMPI_Recv</computeroutput>, etc. They then
1732 use client requests to inform Memcheck of memory state changes caused
1733 by the function being wrapped. This reduces the number of false
1734 positives that Memcheck otherwise typically reports for MPI
1735 applications.</para>
1737 <para>The wrappers also take the opportunity to carefully check
1738 size and definedness of buffers passed as arguments to MPI functions, hence
1739 detecting errors such as passing undefined data to
1740 <computeroutput>PMPI_Send</computeroutput>, or receiving data into a
1741 buffer which is too small.</para>
1743 <para>Unlike most of the rest of Valgrind, the wrapper library is subject to a
1744 BSD-style license, so you can link it into any code base you like.
1745 See the top of <computeroutput>mpi/libmpiwrap.c</computeroutput>
1746 for license details.</para>
1749 <sect2 id="mc-manual.mpiwrap.build" xreflabel="Building MPI Wrappers">
1750 <title>Building and installing the wrappers</title>
1752 <para> The wrapper library will be built automatically if possible.
1753 Valgrind's configure script will look for a suitable
1754 <computeroutput>mpicc</computeroutput> to build it with. This must be
1755 the same <computeroutput>mpicc</computeroutput> you use to build the
1756 MPI application you want to debug. By default, Valgrind tries
1757 <computeroutput>mpicc</computeroutput>, but you can specify a
1758 different one by using the configure-time option
1759 <option>--with-mpicc</option>. Currently the
1760 wrappers are only buildable with
1761 <computeroutput>mpicc</computeroutput>s which are based on GNU
1762 GCC or Intel's C++ Compiler.</para>
1764 <para>Check that the configure script prints a line like this:</para>
1766 <programlisting><![CDATA[
1767 checking for usable MPI2-compliant mpicc and mpi.h... yes, mpicc
1768 ]]></programlisting>
1770 <para>If it says <computeroutput>... no</computeroutput>, your
1771 <computeroutput>mpicc</computeroutput> has failed to compile and link
1772 a test MPI2 program.</para>
1774 <para>If the configure test succeeds, continue in the usual way with
1775 <computeroutput>make</computeroutput> and <computeroutput>make
1776 install</computeroutput>. The final install tree should then contain
1777 <computeroutput>libmpiwrap-<platform>.so</computeroutput>.
1780 <para>Compile up a test MPI program (eg, MPI hello-world) and try
1783 <programlisting><![CDATA[
1784 LD_PRELOAD=$prefix/lib/valgrind/libmpiwrap-<platform>.so \
1785 mpirun [args] $prefix/bin/valgrind ./hello
1786 ]]></programlisting>
1788 <para>You should see something similar to the following</para>
1790 <programlisting><![CDATA[
1791 valgrind MPI wrappers 31901: Active for pid 31901
1792 valgrind MPI wrappers 31901: Try MPIWRAP_DEBUG=help for possible options
1793 ]]></programlisting>
1795 <para>repeated for every process in the group. If you do not see
1796 these, there is an build/installation problem of some kind.</para>
1798 <para> The MPI functions to be wrapped are assumed to be in an ELF
1799 shared object with soname matching
1800 <computeroutput>libmpi.so*</computeroutput>. This is known to be
1801 correct at least for Open MPI and Quadrics MPI, and can easily be
1802 changed if required.</para>
1806 <sect2 id="mc-manual.mpiwrap.gettingstarted"
1807 xreflabel="Getting started with MPI Wrappers">
1808 <title>Getting started</title>
1810 <para>Compile your MPI application as usual, taking care to link it
1811 using the same <computeroutput>mpicc</computeroutput> that your
1812 Valgrind build was configured with.</para>
1815 Use the following basic scheme to run your application on Valgrind with
1816 the wrappers engaged:</para>
1818 <programlisting><![CDATA[
1819 MPIWRAP_DEBUG=[wrapper-args] \
1820 LD_PRELOAD=$prefix/lib/valgrind/libmpiwrap-<platform>.so \
1821 mpirun [mpirun-args] \
1822 $prefix/bin/valgrind [valgrind-args] \
1823 [application] [app-args]
1824 ]]></programlisting>
1826 <para>As an alternative to
1827 <computeroutput>LD_PRELOAD</computeroutput>ing
1828 <computeroutput>libmpiwrap-<platform>.so</computeroutput>, you can
1829 simply link it to your application if desired. This should not disturb
1830 native behaviour of your application in any way.</para>
1834 <sect2 id="mc-manual.mpiwrap.controlling"
1835 xreflabel="Controlling the MPI Wrappers">
1836 <title>Controlling the wrapper library</title>
1838 <para>Environment variable
1839 <computeroutput>MPIWRAP_DEBUG</computeroutput> is consulted at
1840 startup. The default behaviour is to print a starting banner</para>
1842 <programlisting><![CDATA[
1843 valgrind MPI wrappers 16386: Active for pid 16386
1844 valgrind MPI wrappers 16386: Try MPIWRAP_DEBUG=help for possible options
1845 ]]></programlisting>
1847 <para> and then be relatively quiet.</para>
1849 <para>You can give a list of comma-separated options in
1850 <computeroutput>MPIWRAP_DEBUG</computeroutput>. These are</para>
1854 <para><computeroutput>verbose</computeroutput>:
1855 show entries/exits of all wrappers. Also show extra
1856 debugging info, such as the status of outstanding
1857 <computeroutput>MPI_Request</computeroutput>s resulting
1858 from uncompleted <computeroutput>MPI_Irecv</computeroutput>s.</para>
1861 <para><computeroutput>quiet</computeroutput>:
1862 opposite of <computeroutput>verbose</computeroutput>, only print
1863 anything when the wrappers want
1864 to report a detected programming error, or in case of catastrophic
1865 failure of the wrappers.</para>
1868 <para><computeroutput>warn</computeroutput>:
1869 by default, functions which lack proper wrappers
1870 are not commented on, just silently
1871 ignored. This causes a warning to be printed for each unwrapped
1872 function used, up to a maximum of three warnings per function.</para>
1875 <para><computeroutput>strict</computeroutput>:
1876 print an error message and abort the program if
1877 a function lacking a wrapper is used.</para>
1881 <para> If you want to use Valgrind's XML output facility
1882 (<option>--xml=yes</option>), you should pass
1883 <computeroutput>quiet</computeroutput> in
1884 <computeroutput>MPIWRAP_DEBUG</computeroutput> so as to get rid of any
1885 extraneous printing from the wrappers.</para>
1890 <sect2 id="mc-manual.mpiwrap.limitations.functions"
1891 xreflabel="Functions: Abilities and Limitations">
1892 <title>Functions</title>
1894 <para>All MPI2 functions except
1895 <computeroutput>MPI_Wtick</computeroutput>,
1896 <computeroutput>MPI_Wtime</computeroutput> and
1897 <computeroutput>MPI_Pcontrol</computeroutput> have wrappers. The
1898 first two are not wrapped because they return a
1899 <computeroutput>double</computeroutput>, which Valgrind's
1900 function-wrap mechanism cannot handle (but it could easily be
1901 extended to do so). <computeroutput>MPI_Pcontrol</computeroutput> cannot be
1902 wrapped as it has variable arity:
1903 <computeroutput>int MPI_Pcontrol(const int level, ...)</computeroutput></para>
1905 <para>Most functions are wrapped with a default wrapper which does
1906 nothing except complain or abort if it is called, depending on
1907 settings in <computeroutput>MPIWRAP_DEBUG</computeroutput> listed
1908 above. The following functions have "real", do-something-useful
1911 <programlisting><![CDATA[
1912 PMPI_Send PMPI_Bsend PMPI_Ssend PMPI_Rsend
1914 PMPI_Recv PMPI_Get_count
1916 PMPI_Isend PMPI_Ibsend PMPI_Issend PMPI_Irsend
1919 PMPI_Wait PMPI_Waitall
1920 PMPI_Test PMPI_Testall
1922 PMPI_Iprobe PMPI_Probe
1928 PMPI_Type_commit PMPI_Type_free
1930 PMPI_Pack PMPI_Unpack
1932 PMPI_Bcast PMPI_Gather PMPI_Scatter PMPI_Alltoall
1933 PMPI_Reduce PMPI_Allreduce PMPI_Op_create
1935 PMPI_Comm_create PMPI_Comm_dup PMPI_Comm_free PMPI_Comm_rank PMPI_Comm_size
1938 PMPI_Init PMPI_Initialized PMPI_Finalize
1939 ]]></programlisting>
1941 <para> A few functions such as
1942 <computeroutput>PMPI_Address</computeroutput> are listed as
1943 <computeroutput>HAS_NO_WRAPPER</computeroutput>. They have no wrapper
1944 at all as there is nothing worth checking, and giving a no-op wrapper
1945 would reduce performance for no reason.</para>
1947 <para> Note that the wrapper library itself can itself generate large
1948 numbers of calls to the MPI implementation, especially when walking
1949 complex types. The most common functions called are
1950 <computeroutput>PMPI_Extent</computeroutput>,
1951 <computeroutput>PMPI_Type_get_envelope</computeroutput>,
1952 <computeroutput>PMPI_Type_get_contents</computeroutput>, and
1953 <computeroutput>PMPI_Type_free</computeroutput>. </para>
1956 <sect2 id="mc-manual.mpiwrap.limitations.types"
1957 xreflabel="Types: Abilities and Limitations">
1958 <title>Types</title>
1960 <para> MPI-1.1 structured types are supported, and walked exactly.
1961 The currently supported combiners are
1962 <computeroutput>MPI_COMBINER_NAMED</computeroutput>,
1963 <computeroutput>MPI_COMBINER_CONTIGUOUS</computeroutput>,
1964 <computeroutput>MPI_COMBINER_VECTOR</computeroutput>,
1965 <computeroutput>MPI_COMBINER_HVECTOR</computeroutput>
1966 <computeroutput>MPI_COMBINER_INDEXED</computeroutput>,
1967 <computeroutput>MPI_COMBINER_HINDEXED</computeroutput> and
1968 <computeroutput>MPI_COMBINER_STRUCT</computeroutput>. This should
1969 cover all MPI-1.1 types. The mechanism (function
1970 <computeroutput>walk_type</computeroutput>) should extend easily to
1971 cover MPI2 combiners.</para>
1973 <para>MPI defines some named structured types
1974 (<computeroutput>MPI_FLOAT_INT</computeroutput>,
1975 <computeroutput>MPI_DOUBLE_INT</computeroutput>,
1976 <computeroutput>MPI_LONG_INT</computeroutput>,
1977 <computeroutput>MPI_2INT</computeroutput>,
1978 <computeroutput>MPI_SHORT_INT</computeroutput>,
1979 <computeroutput>MPI_LONG_DOUBLE_INT</computeroutput>) which are pairs
1980 of some basic type and a C <computeroutput>int</computeroutput>.
1981 Unfortunately the MPI specification makes it impossible to look inside
1982 these types and see where the fields are. Therefore these wrappers
1983 assume the types are laid out as <computeroutput>struct { float val;
1984 int loc; }</computeroutput> (for
1985 <computeroutput>MPI_FLOAT_INT</computeroutput>), etc, and act
1986 accordingly. This appears to be correct at least for Open MPI 1.0.2
1987 and for Quadrics MPI.</para>
1989 <para>If <computeroutput>strict</computeroutput> is an option specified
1990 in <computeroutput>MPIWRAP_DEBUG</computeroutput>, the application
1991 will abort if an unhandled type is encountered. Otherwise, the
1992 application will print a warning message and continue.</para>
1994 <para>Some effort is made to mark/check memory ranges corresponding to
1995 arrays of values in a single pass. This is important for performance
1996 since asking Valgrind to mark/check any range, no matter how small,
1997 carries quite a large constant cost. This optimisation is applied to
1998 arrays of primitive types (<computeroutput>double</computeroutput>,
1999 <computeroutput>float</computeroutput>,
2000 <computeroutput>int</computeroutput>,
2001 <computeroutput>long</computeroutput>, <computeroutput>long
2002 long</computeroutput>, <computeroutput>short</computeroutput>,
2003 <computeroutput>char</computeroutput>, and <computeroutput>long
2004 double</computeroutput> on platforms where <computeroutput>sizeof(long
2005 double) == 8</computeroutput>). For arrays of all other types, the
2006 wrappers handle each element individually and so there can be a very
2007 large performance cost.</para>
2012 <sect2 id="mc-manual.mpiwrap.writingwrappers"
2013 xreflabel="Writing new MPI Wrappers">
2014 <title>Writing new wrappers</title>
2017 For the most part the wrappers are straightforward. The only
2018 significant complexity arises with nonblocking receives.</para>
2020 <para>The issue is that <computeroutput>MPI_Irecv</computeroutput>
2021 states the recv buffer and returns immediately, giving a handle
2022 (<computeroutput>MPI_Request</computeroutput>) for the transaction.
2023 Later the user will have to poll for completion with
2024 <computeroutput>MPI_Wait</computeroutput> etc, and when the
2025 transaction completes successfully, the wrappers have to paint the
2026 recv buffer. But the recv buffer details are not presented to
2027 <computeroutput>MPI_Wait</computeroutput> -- only the handle is. The
2028 library therefore maintains a shadow table which associates
2029 uncompleted <computeroutput>MPI_Request</computeroutput>s with the
2030 corresponding buffer address/count/type. When an operation completes,
2031 the table is searched for the associated address/count/type info, and
2032 memory is marked accordingly.</para>
2034 <para>Access to the table is guarded by a (POSIX pthreads) lock, so as
2035 to make the library thread-safe.</para>
2037 <para>The table is allocated with
2038 <computeroutput>malloc</computeroutput> and never
2039 <computeroutput>free</computeroutput>d, so it will show up in leak
2042 <para>Writing new wrappers should be fairly easy. The source file is
2043 <computeroutput>mpi/libmpiwrap.c</computeroutput>. If possible,
2044 find an existing wrapper for a function of similar behaviour to the
2045 one you want to wrap, and use it as a starting point. The wrappers
2046 are organised in sections in the same order as the MPI 1.1 spec, to
2047 aid navigation. When adding a wrapper, remember to comment out the
2048 definition of the default wrapper in the long list of defaults at the
2049 bottom of the file (do not remove it, just comment it out).</para>
2052 <sect2 id="mc-manual.mpiwrap.whattoexpect"
2053 xreflabel="What to expect with MPI Wrappers">
2054 <title>What to expect when using the wrappers</title>
2056 <para>The wrappers should reduce Memcheck's false-error rate on MPI
2057 applications. Because the wrapping is done at the MPI interface,
2058 there will still potentially be a large number of errors reported in
2059 the MPI implementation below the interface. The best you can do is
2060 try to suppress them.</para>
2062 <para>You may also find that the input-side (buffer
2063 length/definedness) checks find errors in your MPI use, for example
2064 passing too short a buffer to
2065 <computeroutput>MPI_Recv</computeroutput>.</para>
2067 <para>Functions which are not wrapped may increase the false
2068 error rate. A possible approach is to run with
2069 <computeroutput>MPI_DEBUG</computeroutput> containing
2070 <computeroutput>warn</computeroutput>. This will show you functions
2071 which lack proper wrappers but which are nevertheless used. You can
2072 then write wrappers for them.
2075 <para>A known source of potential false errors are the
2076 <computeroutput>PMPI_Reduce</computeroutput> family of functions, when
2077 using a custom (user-defined) reduction function. In a reduction
2078 operation, each node notionally sends data to a "central point" which
2079 uses the specified reduction function to merge the data items into a
2080 single item. Hence, in general, data is passed between nodes and fed
2081 to the reduction function, but the wrapper library cannot mark the
2082 transferred data as initialised before it is handed to the reduction
2083 function, because all that happens "inside" the
2084 <computeroutput>PMPI_Reduce</computeroutput> call. As a result you
2085 may see false positives reported in your reduction function.</para>
projects / l4.git / blob