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"> 4 5 6<chapter id="mc-manual" xreflabel="Memcheck: a memory error detector"> 7<title>Memcheck: a memory error detector</title> 8 9<para>To use this tool, you may specify <option>--tool=memcheck</option> 10on the Valgrind command line. You don't have to, though, since Memcheck 11is the default tool.</para> 12 13 14<sect1 id="mc-manual.overview" xreflabel="Overview"> 15<title>Overview</title> 16 17<para>Memcheck is a memory error detector. It can detect the following 18problems that are common in C and C++ programs.</para> 19 20<itemizedlist> 21 <listitem> 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> 25 </listitem> 26 27 <listitem> 28 <para>Using undefined values, i.e. values that have not been initialised, 29 or that have been derived from other undefined values.</para> 30 </listitem> 31 32 <listitem> 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> 36 versus 37 <function>free</function>/<computeroutput>delete</computeroutput>/<computeroutput>delete[]</computeroutput></para> 38 </listitem> 39 40 <listitem> 41 <para>Overlapping <computeroutput>src</computeroutput> and 42 <computeroutput>dst</computeroutput> pointers in 43 <computeroutput>memcpy</computeroutput> and related 44 functions.</para> 45 </listitem> 46 47 <listitem> 48 <para>Passing a fishy (presumably negative) value to the 49 <computeroutput>size</computeroutput> parameter of a memory 50 allocation function.</para> 51 </listitem> 52 53 <listitem> 54 <para>Memory leaks.</para> 55 </listitem> 56</itemizedlist> 57 58<para>Problems like these can be difficult to find by other means, 59often remaining undetected for long periods, then causing occasional, 60 difficult-to-diagnose crashes.</para> 61 62<para>Memcheck also provides <xref linkend="manual-core.xtree"/> memory 63 profiling using the command line 64 option <computeroutput>--xtree-memory</computeroutput> and the monitor command 65 <computeroutput>xtmemory</computeroutput>.</para> 66</sect1> 67 68 69 70<sect1 id="mc-manual.errormsgs" 71 xreflabel="Explanation of error messages from Memcheck"> 72<title>Explanation of error messages from Memcheck</title> 73 74<para>Memcheck issues a range of error messages. This section presents a 75quick summary of what error messages mean. The precise behaviour of the 76error-checking machinery is described in <xref 77linkend="mc-manual.machine"/>.</para> 78 79 80<sect2 id="mc-manual.badrw" 81 xreflabel="Illegal read / Illegal write errors"> 82<title>Illegal read / Illegal write errors</title> 83 84<para>For example:</para> 85<programlisting><![CDATA[ 86Invalid read of size 4 87 at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9) 88 by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9) 89 by 0x40B07FF4: read_png_image(QImageIO *) (kernel/qpngio.cpp:326) 90 by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621) 91 Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd 92]]></programlisting> 93 94<para>This happens when your program reads or writes memory at a place 95which Memcheck reckons it shouldn't. In this example, the program did a 964-byte read at address 0xBFFFF0E0, somewhere within the system-supplied 97library libpng.so.2.1.0.9, which was called from somewhere else in the 98same library, called from line 326 of <filename>qpngio.cpp</filename>, 99and so on.</para> 100 101<para>Memcheck tries to establish what the illegal address might relate 102to, since that's often useful. So, if it points into a block of memory 103which has already been freed, you'll be informed of this, and also where 104the block was freed. Likewise, if it should turn out to be just off 105the end of a heap block, a common result of off-by-one-errors in 106array subscripting, you'll be informed of this fact, and also where the 107block was allocated. If you use the <option><xref 108linkend="opt.read-var-info"/></option> option Memcheck will run more slowly 109but may give a more detailed description of any illegal address.</para> 110 111<para>In this example, Memcheck can't identify the address. Actually 112the address is on the stack, but, for some reason, this is not a valid 113stack address -- it is below the stack pointer and that isn't allowed. 114In this particular case it's probably caused by GCC generating invalid 115code, a known bug in some ancient versions of GCC.</para> 116 117<para>Note that Memcheck only tells you that your program is about to 118access memory at an illegal address. It can't stop the access from 119happening. So, if your program makes an access which normally would 120result in a segmentation fault, you program will still suffer the same 121fate -- but you will get a message from Memcheck immediately prior to 122this. In this particular example, reading junk on the stack is 123non-fatal, and the program stays alive.</para> 124 125</sect2> 126 127 128 129<sect2 id="mc-manual.uninitvals" 130 xreflabel="Use of uninitialised values"> 131<title>Use of uninitialised values</title> 132 133<para>For example:</para> 134<programlisting><![CDATA[ 135Conditional jump or move depends on uninitialised value(s) 136 at 0x402DFA94: _IO_vfprintf (_itoa.h:49) 137 by 0x402E8476: _IO_printf (printf.c:36) 138 by 0x8048472: main (tests/manuel1.c:8) 139]]></programlisting> 140 141<para>An uninitialised-value use error is reported when your program 142uses a value which hasn't been initialised -- in other words, is 143undefined. Here, the undefined value is used somewhere inside the 144<function>printf</function> machinery of the C library. This error was 145reported when running the following small program:</para> 146<programlisting><![CDATA[ 147int main() 148{ 149 int x; 150 printf ("x = %d\n", x); 151}]]></programlisting> 152 153<para>It is important to understand that your program can copy around 154junk (uninitialised) data as much as it likes. Memcheck observes this 155and keeps track of the data, but does not complain. A complaint is 156issued only when your program attempts to make use of uninitialised 157data in a way that might affect your program's externally-visible behaviour. 158In this example, <varname>x</varname> is uninitialised. Memcheck observes 159the value being passed to <function>_IO_printf</function> and thence to 160<function>_IO_vfprintf</function>, but makes no comment. However, 161<function>_IO_vfprintf</function> has to examine the value of 162<varname>x</varname> so it can turn it into the corresponding ASCII string, 163and it is at this point that Memcheck complains.</para> 164 165<para>Sources of uninitialised data tend to be:</para> 166<itemizedlist> 167 <listitem> 168 <para>Local variables in procedures which have not been initialised, 169 as in the example above.</para> 170 </listitem> 171 <listitem> 172 <para>The contents of heap blocks (allocated with 173 <function>malloc</function>, <function>new</function>, or a similar 174 function) before you (or a constructor) write something there. 175 </para> 176 </listitem> 177</itemizedlist> 178 179<para>To see information on the sources of uninitialised data in your 180program, use the <option>--track-origins=yes</option> option. This 181makes Memcheck run more slowly, but can make it much easier to track down 182the root causes of uninitialised value errors.</para> 183 184</sect2> 185 186 187 188<sect2 id="mc-manual.bad-syscall-args" 189 xreflabel="Use of uninitialised or unaddressable values in system 190 calls"> 191<title>Use of uninitialised or unaddressable values in system 192 calls</title> 193 194<para>Memcheck checks all parameters to system calls: 195<itemizedlist> 196 <listitem> 197 <para>It checks all the direct parameters themselves, whether they are 198 initialised.</para> 199 </listitem> 200 <listitem> 201 <para>Also, if a system call needs to read from a buffer provided by 202 your program, Memcheck checks that the entire buffer is addressable 203 and its contents are initialised.</para> 204 </listitem> 205 <listitem> 206 <para>Also, if the system call needs to write to a user-supplied 207 buffer, Memcheck checks that the buffer is addressable.</para> 208 </listitem> 209</itemizedlist> 210</para> 211 212<para>After the system call, Memcheck updates its tracked information to 213precisely reflect any changes in memory state caused by the system 214call.</para> 215 216<para>Here's an example of two system calls with invalid parameters:</para> 217<programlisting><![CDATA[ 218 #include <stdlib.h> 219 #include <unistd.h> 220 int main( void ) 221 { 222 char* arr = malloc(10); 223 int* arr2 = malloc(sizeof(int)); 224 write( 1 /* stdout */, arr, 10 ); 225 exit(arr2[0]); 226 } 227]]></programlisting> 228 229<para>You get these complaints ...</para> 230<programlisting><![CDATA[ 231 Syscall param write(buf) points to uninitialised byte(s) 232 at 0x25A48723: __write_nocancel (in /lib/tls/libc-2.3.3.so) 233 by 0x259AFAD3: __libc_start_main (in /lib/tls/libc-2.3.3.so) 234 by 0x8048348: (within /auto/homes/njn25/grind/head4/a.out) 235 Address 0x25AB8028 is 0 bytes inside a block of size 10 alloc'd 236 at 0x259852B0: malloc (vg_replace_malloc.c:130) 237 by 0x80483F1: main (a.c:5) 238 239 Syscall param exit(error_code) contains uninitialised byte(s) 240 at 0x25A21B44: __GI__exit (in /lib/tls/libc-2.3.3.so) 241 by 0x8048426: main (a.c:8) 242]]></programlisting> 243 244<para>... because the program has (a) written uninitialised junk 245from the heap block to the standard output, and (b) passed an 246uninitialised value to <function>exit</function>. Note that the first 247error refers to the memory pointed to by 248<computeroutput>buf</computeroutput> (not 249<computeroutput>buf</computeroutput> itself), but the second error 250refers directly to <computeroutput>exit</computeroutput>'s argument 251<computeroutput>arr2[0]</computeroutput>.</para> 252 253</sect2> 254 255 256<sect2 id="mc-manual.badfrees" xreflabel="Illegal frees"> 257<title>Illegal frees</title> 258 259<para>For example:</para> 260<programlisting><![CDATA[ 261Invalid free() 262 at 0x4004FFDF: free (vg_clientmalloc.c:577) 263 by 0x80484C7: main (tests/doublefree.c:10) 264 Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd 265 at 0x4004FFDF: free (vg_clientmalloc.c:577) 266 by 0x80484C7: main (tests/doublefree.c:10) 267]]></programlisting> 268 269<para>Memcheck keeps track of the blocks allocated by your program 270with <function>malloc</function>/<computeroutput>new</computeroutput>, 271so it can know exactly whether or not the argument to 272<function>free</function>/<computeroutput>delete</computeroutput> is 273legitimate or not. Here, this test program has freed the same block 274twice. As with the illegal read/write errors, Memcheck attempts to 275make sense of the address freed. If, as here, the address is one 276which has previously been freed, you wil be told that -- making 277duplicate frees of the same block easy to spot. You will also get this 278message if you try to free a pointer that doesn't point to the start of a 279heap block.</para> 280 281</sect2> 282 283 284<sect2 id="mc-manual.rudefn" 285 xreflabel="When a heap block is freed with an inappropriate deallocation 286function"> 287<title>When a heap block is freed with an inappropriate deallocation 288function</title> 289 290<para>In the following example, a block allocated with 291<function>new[]</function> has wrongly been deallocated with 292<function>free</function>:</para> 293<programlisting><![CDATA[ 294Mismatched free() / delete / delete [] 295 at 0x40043249: free (vg_clientfuncs.c:171) 296 by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149) 297 by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60) 298 by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44) 299 Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd 300 at 0x4004318C: operator new[](unsigned int) (vg_clientfuncs.c:152) 301 by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314) 302 by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416) 303 by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272) 304]]></programlisting> 305 306<para>In <literal>C++</literal> it's important to deallocate memory in a 307way compatible with how it was allocated. The deal is:</para> 308<itemizedlist> 309 <listitem> 310 <para>If allocated with 311 <function>malloc</function>, 312 <function>calloc</function>, 313 <function>realloc</function>, 314 <function>valloc</function> or 315 <function>memalign</function>, you must 316 deallocate with <function>free</function>.</para> 317 </listitem> 318 <listitem> 319 <para>If allocated with <function>new</function>, you must deallocate 320 with <function>delete</function>.</para> 321 </listitem> 322 <listitem> 323 <para>If allocated with <function>new[]</function>, you must 324 deallocate with <function>delete[]</function>.</para> 325 </listitem> 326</itemizedlist> 327 328<para>The worst thing is that on Linux apparently it doesn't matter if 329you do mix these up, but the same program may then crash on a 330different platform, Solaris for example. So it's best to fix it 331properly. According to the KDE folks "it's amazing how many C++ 332programmers don't know this".</para> 333 334<para>The reason behind the requirement is as follows. In some C++ 335implementations, <function>delete[]</function> must be used for 336objects allocated by <function>new[]</function> because the compiler 337stores the size of the array and the pointer-to-member to the 338destructor of the array's content just before the pointer actually 339returned. <function>delete</function> doesn't account for this and will get 340confused, possibly corrupting the heap.</para> 341 342</sect2> 343 344 345 346<sect2 id="mc-manual.overlap" 347 xreflabel="Overlapping source and destination blocks"> 348<title>Overlapping source and destination blocks</title> 349 350<para>The following C library functions copy some data from one 351memory block to another (or something similar): 352<function>memcpy</function>, 353<function>strcpy</function>, 354<function>strncpy</function>, 355<function>strcat</function>, 356<function>strncat</function>. 357The blocks pointed to by their <computeroutput>src</computeroutput> and 358<computeroutput>dst</computeroutput> pointers aren't allowed to overlap. 359The POSIX standards have wording along the lines "If copying takes place 360between objects that overlap, the behavior is undefined." Therefore, 361Memcheck checks for this. 362</para> 363 364<para>For example:</para> 365<programlisting><![CDATA[ 366==27492== Source and destination overlap in memcpy(0xbffff294, 0xbffff280, 21) 367==27492== at 0x40026CDC: memcpy (mc_replace_strmem.c:71) 368==27492== by 0x804865A: main (overlap.c:40) 369]]></programlisting> 370 371<para>You don't want the two blocks to overlap because one of them could 372get partially overwritten by the copying.</para> 373 374<para>You might think that Memcheck is being overly pedantic reporting 375this in the case where <computeroutput>dst</computeroutput> is less than 376<computeroutput>src</computeroutput>. For example, the obvious way to 377implement <function>memcpy</function> is by copying from the first 378byte to the last. However, the optimisation guides of some 379architectures recommend copying from the last byte down to the first. 380Also, some implementations of <function>memcpy</function> zero 381<computeroutput>dst</computeroutput> before copying, because zeroing the 382destination's cache line(s) can improve performance.</para> 383 384<para>The moral of the story is: if you want to write truly portable 385code, don't make any assumptions about the language 386implementation.</para> 387 388</sect2> 389 390 391<sect2 id="mc-manual.fishyvalue" 392 xreflabel="Fishy argument values"> 393<title>Fishy argument values</title> 394 395<para>All memory allocation functions take an argument specifying the 396size of the memory block that should be allocated. Clearly, the requested 397size should be a non-negative value and is typically not excessively large. 398For instance, it is extremely unlikly that the size of an allocation 399request exceeds 2**63 bytes on a 64-bit machine. It is much more likely that 400such a value is the result of an erroneous size calculation and is in effect 401a negative value (that just happens to appear excessively large because 402the bit pattern is interpreted as an unsigned integer). 403Such a value is called a "fishy value". 404 405The <varname>size</varname> argument of the following allocation functions 406is checked for being fishy: 407<function>malloc</function>, 408<function>calloc</function>, 409<function>realloc</function>, 410<function>memalign</function>, 411<function>new</function>, 412<function>new []</function>. 413<function>__builtin_new</function>, 414<function>__builtin_vec_new</function>, 415For <function>calloc</function> both arguments are being checked. 416</para> 417 418<para>For example:</para> 419<programlisting><![CDATA[ 420==32233== Argument 'size' of function malloc has a fishy (possibly negative) value: -3 421==32233== at 0x4C2CFA7: malloc (vg_replace_malloc.c:298) 422==32233== by 0x400555: foo (fishy.c:15) 423==32233== by 0x400583: main (fishy.c:23) 424]]></programlisting> 425 426<para>In earlier Valgrind versions those values were being referred to 427as "silly arguments" and no back-trace was included. 428</para> 429 430</sect2> 431 432 433<sect2 id="mc-manual.leaks" xreflabel="Memory leak detection"> 434<title>Memory leak detection</title> 435 436<para>Memcheck keeps track of all heap blocks issued in response to 437calls to 438<function>malloc</function>/<function>new</function> et al. 439So when the program exits, it knows which blocks have not been freed. 440</para> 441 442<para>If <option>--leak-check</option> is set appropriately, for each 443remaining block, Memcheck determines if the block is reachable from pointers 444within the root-set. The root-set consists of (a) general purpose registers 445of all threads, and (b) initialised, aligned, pointer-sized data words in 446accessible client memory, including stacks.</para> 447 448<para>There are two ways a block can be reached. The first is with a 449"start-pointer", i.e. a pointer to the start of the block. The second is with 450an "interior-pointer", i.e. a pointer to the middle of the block. There are 451several ways we know of that an interior-pointer can occur:</para> 452 453<itemizedlist> 454 <listitem> 455 <para>The pointer might have originally been a start-pointer and have been 456 moved along deliberately (or not deliberately) by the program. In 457 particular, this can happen if your program uses tagged pointers, i.e. 458 if it uses the bottom one, two or three bits of a pointer, which are 459 normally always zero due to alignment, in order to store extra 460 information.</para> 461 </listitem> 462 463 <listitem> 464 <para>It might be a random junk value in memory, entirely unrelated, just 465 a coincidence.</para> 466 </listitem> 467 468 <listitem> 469 <para>It might be a pointer to the inner char array of a C++ 470 <computeroutput>std::string</computeroutput>. For example, some 471 compilers add 3 words at the beginning of the std::string to 472 store the length, the capacity and a reference count before the 473 memory containing the array of characters. They return a pointer 474 just after these 3 words, pointing at the char array.</para> 475 </listitem> 476 477 <listitem> 478 <para>Some code might allocate a block of memory, and use the first 8 479 bytes to store (block size - 8) as a 64bit number. 480 <computeroutput>sqlite3MemMalloc</computeroutput> does this.</para> 481 </listitem> 482 483 <listitem> 484 <para>It might be a pointer to an array of C++ objects (which possess 485 destructors) allocated with <computeroutput>new[]</computeroutput>. In 486 this case, some compilers store a "magic cookie" containing the array 487 length at the start of the allocated block, and return a pointer to just 488 past that magic cookie, i.e. an interior-pointer. 489 See <ulink url="http://theory.uwinnipeg.ca/gnu/gcc/gxxint_14.html">this 490 page</ulink> for more information.</para> 491 </listitem> 492 493 <listitem> 494 <para>It might be a pointer to an inner part of a C++ object using 495 multiple inheritance. </para> 496 </listitem> 497</itemizedlist> 498 499<para>You can optionally activate heuristics to use during the leak 500search to detect the interior pointers corresponding to 501the <computeroutput>stdstring</computeroutput>, 502<computeroutput>length64</computeroutput>, 503<computeroutput>newarray</computeroutput> 504and <computeroutput>multipleinheritance</computeroutput> cases. If the 505heuristic detects that an interior pointer corresponds to such a case, 506the block will be considered as reachable by the interior 507pointer. In other words, the interior pointer will be treated 508as if it were a start pointer.</para> 509 510 511<para>With that in mind, consider the nine possible cases described by the 512following figure.</para> 513 514<programlisting><![CDATA[ 515 Pointer chain AAA Leak Case BBB Leak Case 516 ------------- ------------- ------------- 517(1) RRR ------------> BBB DR 518(2) RRR ---> AAA ---> BBB DR IR 519(3) RRR BBB DL 520(4) RRR AAA ---> BBB DL IL 521(5) RRR ------?-----> BBB (y)DR, (n)DL 522(6) RRR ---> AAA -?-> BBB DR (y)IR, (n)DL 523(7) RRR -?-> AAA ---> BBB (y)DR, (n)DL (y)IR, (n)IL 524(8) RRR -?-> AAA -?-> BBB (y)DR, (n)DL (y,y)IR, (n,y)IL, (_,n)DL 525(9) RRR AAA -?-> BBB DL (y)IL, (n)DL 526 527Pointer chain legend: 528- RRR: a root set node or DR block 529- AAA, BBB: heap blocks 530- --->: a start-pointer 531- -?->: an interior-pointer 532 533Leak Case legend: 534- DR: Directly reachable 535- IR: Indirectly reachable 536- DL: Directly lost 537- IL: Indirectly lost 538- (y)XY: it's XY if the interior-pointer is a real pointer 539- (n)XY: it's XY if the interior-pointer is not a real pointer 540- (_)XY: it's XY in either case 541]]></programlisting> 542 543<para>Every possible case can be reduced to one of the above nine. Memcheck 544merges some of these cases in its output, resulting in the following four 545leak kinds.</para> 546 547 548<itemizedlist> 549 550 <listitem> 551 <para>"Still reachable". This covers cases 1 and 2 (for the BBB blocks) 552 above. A start-pointer or chain of start-pointers to the block is 553 found. Since the block is still pointed at, the programmer could, at 554 least in principle, have freed it before program exit. "Still reachable" 555 blocks are very common and arguably not a problem. So, by default, 556 Memcheck won't report such blocks individually.</para> 557 </listitem> 558 559 <listitem> 560 <para>"Definitely lost". This covers case 3 (for the BBB blocks) above. 561 This means that no pointer to the block can be found. The block is 562 classified as "lost", because the programmer could not possibly have 563 freed it at program exit, since no pointer to it exists. This is likely 564 a symptom of having lost the pointer at some earlier point in the 565 program. Such cases should be fixed by the programmer.</para> 566 </listitem> 567 568 <listitem> 569 <para>"Indirectly lost". This covers cases 4 and 9 (for the BBB blocks) 570 above. This means that the block is lost, not because there are no 571 pointers to it, but rather because all the blocks that point to it are 572 themselves lost. For example, if you have a binary tree and the root 573 node is lost, all its children nodes will be indirectly lost. Because 574 the problem will disappear if the definitely lost block that caused the 575 indirect leak is fixed, Memcheck won't report such blocks individually 576 by default.</para> 577 </listitem> 578 579 <listitem> 580 <para>"Possibly lost". This covers cases 5--8 (for the BBB blocks) 581 above. This means that a chain of one or more pointers to the block has 582 been found, but at least one of the pointers is an interior-pointer. 583 This could just be a random value in memory that happens to point into a 584 block, and so you shouldn't consider this ok unless you know you have 585 interior-pointers.</para> 586 </listitem> 587 588</itemizedlist> 589 590<para>(Note: This mapping of the nine possible cases onto four leak kinds is 591not necessarily the best way that leaks could be reported; in particular, 592interior-pointers are treated inconsistently. It is possible the 593categorisation may be improved in the future.)</para> 594 595<para>Furthermore, if suppressions exists for a block, it will be reported 596as "suppressed" no matter what which of the above four kinds it belongs 597to.</para> 598 599 600<para>The following is an example leak summary.</para> 601 602<programlisting><![CDATA[ 603LEAK SUMMARY: 604 definitely lost: 48 bytes in 3 blocks. 605 indirectly lost: 32 bytes in 2 blocks. 606 possibly lost: 96 bytes in 6 blocks. 607 still reachable: 64 bytes in 4 blocks. 608 suppressed: 0 bytes in 0 blocks. 609]]></programlisting> 610 611<para>If heuristics have been used to consider some blocks as 612reachable, the leak summary details the heuristically reachable subset 613of 'still reachable:' per heuristic. In the below example, of the 95 614bytes still reachable, 87 bytes (56+7+8+16) have been considered 615heuristically reachable. 616</para> 617 618<programlisting><![CDATA[ 619LEAK SUMMARY: 620 definitely lost: 4 bytes in 1 blocks 621 indirectly lost: 0 bytes in 0 blocks 622 possibly lost: 0 bytes in 0 blocks 623 still reachable: 95 bytes in 6 blocks 624 of which reachable via heuristic: 625 stdstring : 56 bytes in 2 blocks 626 length64 : 16 bytes in 1 blocks 627 newarray : 7 bytes in 1 blocks 628 multipleinheritance: 8 bytes in 1 blocks 629 suppressed: 0 bytes in 0 blocks 630]]></programlisting> 631 632<para>If <option>--leak-check=full</option> is specified, 633Memcheck will give details for each definitely lost or possibly lost block, 634including where it was allocated. (Actually, it merges results for all 635blocks that have the same leak kind and sufficiently similar stack traces 636into a single "loss record". The 637<option>--leak-resolution</option> lets you control the 638meaning of "sufficiently similar".) It cannot tell you when or how or why 639the pointer to a leaked block was lost; you have to work that out for 640yourself. In general, you should attempt to ensure your programs do not 641have any definitely lost or possibly lost blocks at exit.</para> 642 643<para>For example:</para> 644<programlisting><![CDATA[ 6458 bytes in 1 blocks are definitely lost in loss record 1 of 14 646 at 0x........: malloc (vg_replace_malloc.c:...) 647 by 0x........: mk (leak-tree.c:11) 648 by 0x........: main (leak-tree.c:39) 649 65088 (8 direct, 80 indirect) bytes in 1 blocks are definitely lost in loss record 13 of 14 651 at 0x........: malloc (vg_replace_malloc.c:...) 652 by 0x........: mk (leak-tree.c:11) 653 by 0x........: main (leak-tree.c:25) 654]]></programlisting> 655 656<para>The first message describes a simple case of a single 8 byte block 657that has been definitely lost. The second case mentions another 8 byte 658block that has been definitely lost; the difference is that a further 80 659bytes in other blocks are indirectly lost because of this lost block. 660The loss records are not presented in any notable order, so the loss record 661numbers aren't particularly meaningful. The loss record numbers can be used 662in the Valgrind gdbserver to list the addresses of the leaked blocks and/or give 663more details about how a block is still reachable.</para> 664 665<para>The option <option>--show-leak-kinds=<set></option> 666controls the set of leak kinds to show 667when <option>--leak-check=full</option> is specified. </para> 668 669<para>The <option><set></option> of leak kinds is specified 670in one of the following ways: 671 672<itemizedlist> 673 <listitem><para>a comma separated list of one or more of 674 <option>definite indirect possible reachable</option>.</para> 675 </listitem> 676 677 <listitem><para><option>all</option> to specify the complete set (all leak kinds).</para> 678 </listitem> 679 680 <listitem><para><option>none</option> for the empty set.</para> 681 </listitem> 682</itemizedlist> 683 684</para> 685 686<para> The default value for the leak kinds to show is 687 <option>--show-leak-kinds=definite,possible</option>. 688</para> 689 690<para>To also show the reachable and indirectly lost blocks in 691addition to the definitely and possibly lost blocks, you can 692use <option>--show-leak-kinds=all</option>. To only show the 693reachable and indirectly lost blocks, use 694<option>--show-leak-kinds=indirect,reachable</option>. The reachable 695and indirectly lost blocks will then be presented as shown in 696the following two examples.</para> 697 698<programlisting><![CDATA[ 69964 bytes in 4 blocks are still reachable in loss record 2 of 4 700 at 0x........: malloc (vg_replace_malloc.c:177) 701 by 0x........: mk (leak-cases.c:52) 702 by 0x........: main (leak-cases.c:74) 703 70432 bytes in 2 blocks are indirectly lost in loss record 1 of 4 705 at 0x........: malloc (vg_replace_malloc.c:177) 706 by 0x........: mk (leak-cases.c:52) 707 by 0x........: main (leak-cases.c:80) 708]]></programlisting> 709 710<para>Because there are different kinds of leaks with different 711severities, an interesting question is: which leaks should be 712counted as true "errors" and which should not? 713</para> 714 715<para> The answer to this question affects the numbers printed in 716the <computeroutput>ERROR SUMMARY</computeroutput> line, and also the 717effect of the <option>--error-exitcode</option> option. First, a leak 718is only counted as a true "error" 719if <option>--leak-check=full</option> is specified. Then, the 720option <option>--errors-for-leak-kinds=<set></option> controls 721the set of leak kinds to consider as errors. The default value 722is <option>--errors-for-leak-kinds=definite,possible</option> 723</para> 724 725</sect2> 726 727</sect1> 728 729 730 731<sect1 id="mc-manual.options" 732 xreflabel="Memcheck Command-Line Options"> 733<title>Memcheck Command-Line Options</title> 734 735<!-- start of xi:include in the manpage --> 736<variablelist id="mc.opts.list"> 737 738 <varlistentry id="opt.leak-check" xreflabel="--leak-check"> 739 <term> 740 <option><![CDATA[--leak-check=<no|summary|yes|full> [default: summary] ]]></option> 741 </term> 742 <listitem> 743 <para>When enabled, search for memory leaks when the client 744 program finishes. If set to <varname>summary</varname>, it says how 745 many leaks occurred. If set to <varname>full</varname> or 746 <varname>yes</varname>, each individual leak will be shown 747 in detail and/or counted as an error, as specified by the options 748 <option>--show-leak-kinds</option> and 749 <option>--errors-for-leak-kinds</option>. </para> 750 </listitem> 751 </varlistentry> 752 753 <varlistentry id="opt.leak-resolution" xreflabel="--leak-resolution"> 754 <term> 755 <option><![CDATA[--leak-resolution=<low|med|high> [default: high] ]]></option> 756 </term> 757 <listitem> 758 <para>When doing leak checking, determines how willing 759 Memcheck is to consider different backtraces to 760 be the same for the purposes of merging multiple leaks into a single 761 leak report. When set to <varname>low</varname>, only the first 762 two entries need match. When <varname>med</varname>, four entries 763 have to match. When <varname>high</varname>, all entries need to 764 match.</para> 765 766 <para>For hardcore leak debugging, you probably want to use 767 <option>--leak-resolution=high</option> together with 768 <option>--num-callers=40</option> or some such large number. 769 </para> 770 771 <para>Note that the <option>--leak-resolution</option> setting 772 does not affect Memcheck's ability to find 773 leaks. It only changes how the results are presented.</para> 774 </listitem> 775 </varlistentry> 776 777 <varlistentry id="opt.show-leak-kinds" xreflabel="--show-leak-kinds"> 778 <term> 779 <option><![CDATA[--show-leak-kinds=<set> [default: definite,possible] ]]></option> 780 </term> 781 <listitem> 782 <para>Specifies the leak kinds to show in a <varname>full</varname> 783 leak search, in one of the following ways: </para> 784 785 <itemizedlist> 786 <listitem><para>a comma separated list of one or more of 787 <option>definite indirect possible reachable</option>.</para> 788 </listitem> 789 790 <listitem><para><option>all</option> to specify the complete set (all leak kinds). 791 It is equivalent to 792 <option>--show-leak-kinds=definite,indirect,possible,reachable</option>.</para> 793 </listitem> 794 795 <listitem><para><option>none</option> for the empty set.</para> 796 </listitem> 797 </itemizedlist> 798 </listitem> 799 </varlistentry> 800 801 802 <varlistentry id="opt.errors-for-leak-kinds" xreflabel="--errors-for-leak-kinds"> 803 <term> 804 <option><![CDATA[--errors-for-leak-kinds=<set> [default: definite,possible] ]]></option> 805 </term> 806 <listitem> 807 <para>Specifies the leak kinds to count as errors in a 808 <varname>full</varname> leak search. The 809 <option><![CDATA[<set>]]></option> is specified similarly to 810 <option>--show-leak-kinds</option> 811 </para> 812 </listitem> 813 </varlistentry> 814 815 816 <varlistentry id="opt.leak-check-heuristics" xreflabel="--leak-check-heuristics"> 817 <term> 818 <option><![CDATA[--leak-check-heuristics=<set> [default: all] ]]></option> 819 </term> 820 <listitem> 821 <para>Specifies the set of leak check heuristics to be used 822 during leak searches. The heuristics control which interior pointers 823 to a block cause it to be considered as reachable. 824 The heuristic set is specified in one of the following ways:</para> 825 826 <itemizedlist> 827 <listitem><para>a comma separated list of one or more of 828 <option>stdstring length64 newarray multipleinheritance</option>.</para> 829 </listitem> 830 831 <listitem><para><option>all</option> to activate the complete set of 832 heuristics. 833 It is equivalent to 834 <option>--leak-check-heuristics=stdstring,length64,newarray,multipleinheritance</option>.</para> 835 </listitem> 836 837 <listitem><para><option>none</option> for the empty set.</para> 838 </listitem> 839 </itemizedlist> 840 </listitem> 841 842 <para>Note that these heuristics are dependent on the layout of the objects 843 produced by the C++ compiler. They have been tested with some gcc versions 844 (e.g. 4.4 and 4.7). They might not work properly with other C++ compilers. 845 </para> 846 </varlistentry> 847 848 849 <varlistentry id="opt.show-reachable" xreflabel="--show-reachable"> 850 <term> 851 <option><![CDATA[--show-reachable=<yes|no> ]]></option> 852 </term> 853 <term> 854 <option><![CDATA[--show-possibly-lost=<yes|no> ]]></option> 855 </term> 856 <listitem> 857 <para>These options provide an alternative way to specify the leak kinds to show: 858 </para> 859 <itemizedlist> 860 <listitem> 861 <para> 862 <option>--show-reachable=no --show-possibly-lost=yes</option> is equivalent to 863 <option>--show-leak-kinds=definite,possible</option>. 864 </para> 865 </listitem> 866 <listitem> 867 <para> 868 <option>--show-reachable=no --show-possibly-lost=no</option> is equivalent to 869 <option>--show-leak-kinds=definite</option>. 870 </para> 871 </listitem> 872 <listitem> 873 <para> 874 <option>--show-reachable=yes</option> is equivalent to 875 <option>--show-leak-kinds=all</option>. 876 </para> 877 </listitem> 878 </itemizedlist> 879 </listitem> 880 <para> Note that <option>--show-possibly-lost=no</option> has no effect 881 if <option>--show-reachable=yes</option> is specified.</para> 882 </varlistentry> 883 884 <varlistentry id="opt.xtree-leak" xreflabel="--xtree-leak"> 885 <term> 886 <option><![CDATA[--xtree-leak=<no|yes> [no] ]]></option> 887 </term> 888 <listitem> 889 <para>If set to yes, the results for the leak search done at exit will be 890 output in a 'Callgrind Format' execution tree file. Note that this 891 automatically sets the option <option>--leak-check=full</option>. 892 The produced file 893 will contain the following events:</para> 894 <itemizedlist> 895 <listitem><para><option>RB</option> : Reachable Bytes</para></listitem> 896 <listitem><para><option>PB</option> : Possibly lost Bytes</para></listitem> 897 <listitem><para><option>IB</option> : Indirectly lost Bytes</para></listitem> 898 <listitem><para><option>DB</option> : Definitely lost Bytes (direct plus indirect)</para></listitem> 899 <listitem><para><option>DIB</option> : Definitely Indirectly lost Bytes (subset of DB)</para></listitem> 900 <listitem><para><option>RBk</option> : reachable Blocks</para></listitem> 901 <listitem><para><option>PBk</option> : Possibly lost Blocks</para></listitem> 902 <listitem><para><option>IBk</option> : Indirectly lost Blocks</para></listitem> 903 <listitem><para><option>DBk</option> : Definitely lost Blocks</para></listitem> 904 </itemizedlist> 905 906 <para>The increase or decrease for all events above will also be output in 907 the file to provide the delta (increase or decreaseà between 2 908 successive leak searches. For example, <option>iRB</option> is the 909 increase of the <option>RB</option> event, <option>dPBk</option> is the 910 decrease of <option>PBk</option> event. The values for the increase and 911 decrease events will be zero for the first leak search done.</para> 912 913 <para>See <xref linkend="manual-core.xtree"/> for a detailed explanation 914 about execution trees.</para> 915 </listitem> 916 </varlistentry> 917 918 <varlistentry id="opt.xtree-leak-file" xreflabel="--xtree-leak-file"> 919 <term> 920 <option><![CDATA[--xtree-leak-file=<filename> [default: 921 xtleak.kcg.%p] ]]></option> 922 </term> 923 <listitem> 924 <para>Specifies that Valgrind should produce the xtree leak 925 report in the specified file. Any <option>%p</option>, 926 <option>%q</option> or <option>%n</option> sequences appearing in 927 the filename are expanded 928 in exactly the same way as they are for <option>--log-file</option>. 929 See the description of <xref linkend="opt.log-file"/> 930 for details. </para> 931 <para>See <xref linkend="manual-core.xtree"/> 932 for a detailed explanation about execution trees formats. </para> 933 </listitem> 934 </varlistentry> 935 936 <varlistentry id="opt.undef-value-errors" xreflabel="--undef-value-errors"> 937 <term> 938 <option><![CDATA[--undef-value-errors=<yes|no> [default: yes] ]]></option> 939 </term> 940 <listitem> 941 <para>Controls whether Memcheck reports 942 uses of undefined value errors. Set this to 943 <varname>no</varname> if you don't want to see undefined value 944 errors. It also has the side effect of speeding up 945 Memcheck somewhat. 946 </para> 947 </listitem> 948 </varlistentry> 949 950 <varlistentry id="opt.track-origins" xreflabel="--track-origins"> 951 <term> 952 <option><![CDATA[--track-origins=<yes|no> [default: no] ]]></option> 953 </term> 954 <listitem> 955 <para>Controls whether Memcheck tracks 956 the origin of uninitialised values. By default, it does not, 957 which means that although it can tell you that an 958 uninitialised value is being used in a dangerous way, it 959 cannot tell you where the uninitialised value came from. This 960 often makes it difficult to track down the root problem. 961 </para> 962 <para>When set 963 to <varname>yes</varname>, Memcheck keeps 964 track of the origins of all uninitialised values. Then, when 965 an uninitialised value error is 966 reported, Memcheck will try to show the 967 origin of the value. An origin can be one of the following 968 four places: a heap block, a stack allocation, a client 969 request, or miscellaneous other sources (eg, a call 970 to <varname>brk</varname>). 971 </para> 972 <para>For uninitialised values originating from a heap 973 block, Memcheck shows where the block was 974 allocated. For uninitialised values originating from a stack 975 allocation, Memcheck can tell you which 976 function allocated the value, but no more than that -- typically 977 it shows you the source location of the opening brace of the 978 function. So you should carefully check that all of the 979 function's local variables are initialised properly. 980 </para> 981 <para>Performance overhead: origin tracking is expensive. It 982 halves Memcheck's speed and increases 983 memory use by a minimum of 100MB, and possibly more. 984 Nevertheless it can drastically reduce the effort required to 985 identify the root cause of uninitialised value errors, and so 986 is often a programmer productivity win, despite running 987 more slowly. 988 </para> 989 <para>Accuracy: Memcheck tracks origins 990 quite accurately. To avoid very large space and time 991 overheads, some approximations are made. It is possible, 992 although unlikely, that Memcheck will report an incorrect origin, or 993 not be able to identify any origin. 994 </para> 995 <para>Note that the combination 996 <option>--track-origins=yes</option> 997 and <option>--undef-value-errors=no</option> is 998 nonsensical. Memcheck checks for and 999 rejects this combination at startup. 1000 </para> 1001 </listitem> 1002 </varlistentry> 1003 1004 <varlistentry id="opt.partial-loads-ok" xreflabel="--partial-loads-ok"> 1005 <term> 1006 <option><![CDATA[--partial-loads-ok=<yes|no> [default: yes] ]]></option> 1007 </term> 1008 <listitem> 1009 <para>Controls how Memcheck handles 32-, 64-, 128- and 256-bit 1010 naturally aligned loads from addresses for which some bytes are 1011 addressable and others are not. When <varname>yes</varname>, such 1012 loads do not produce an address error. Instead, loaded bytes 1013 originating from illegal addresses are marked as uninitialised, and 1014 those corresponding to legal addresses are handled in the normal 1015 way.</para> 1016 1017 <para>When <varname>no</varname>, loads from partially invalid 1018 addresses are treated the same as loads from completely invalid 1019 addresses: an illegal-address error is issued, and the resulting 1020 bytes are marked as initialised.</para> 1021 1022 <para>Note that code that behaves in this way is in violation of 1023 the ISO C/C++ standards, and should be considered broken. If 1024 at all possible, such code should be fixed.</para> 1025 </listitem> 1026 </varlistentry> 1027 1028 <varlistentry id="opt.expensive-definedness-checks" xreflabel="--expensive-definedness-checks"> 1029 <term> 1030 <option><![CDATA[--expensive-definedness-checks=<yes|no> [default: no] ]]></option> 1031 </term> 1032 <listitem> 1033 <para>Controls whether Memcheck should employ more precise but also more 1034 expensive (time consuming) algorithms when checking the definedness of a 1035 value. The default setting is not to do that and it is usually 1036 sufficient. However, for highly optimised code valgrind may sometimes 1037 incorrectly complain. 1038 Invoking valgrind with <option>--expensive-definedness-checks=yes</option> 1039 helps but comes at a performance cost. Runtime degradation of 1040 25% have been observed but the extra cost depends a lot on the 1041 application at hand. 1042 </para> 1043 </listitem> 1044 </varlistentry> 1045 1046 <varlistentry id="opt.keep-stacktraces" xreflabel="--keep-stacktraces"> 1047 <term> 1048 <option><![CDATA[--keep-stacktraces=alloc|free|alloc-and-free|alloc-then-free|none [default: alloc-and-free] ]]></option> 1049 </term> 1050 <listitem> 1051 <para>Controls which stack trace(s) to keep for malloc'd and/or 1052 free'd blocks. 1053 </para> 1054 1055 <para>With <varname>alloc-then-free</varname>, a stack trace is 1056 recorded at allocation time, and is associated with the block. 1057 When the block is freed, a second stack trace is recorded, and 1058 this replaces the allocation stack trace. As a result, any "use 1059 after free" errors relating to this block can only show a stack 1060 trace for where the block was freed. 1061 </para> 1062 1063 <para>With <varname>alloc-and-free</varname>, both allocation 1064 and the deallocation stack traces for the block are stored. 1065 Hence a "use after free" error will 1066 show both, which may make the error easier to diagnose. 1067 Compared to <varname>alloc-then-free</varname>, this setting 1068 slightly increases Valgrind's memory use as the block contains two 1069 references instead of one. 1070 </para> 1071 1072 <para>With <varname>alloc</varname>, only the allocation stack 1073 trace is recorded (and reported). With <varname>free</varname>, 1074 only the deallocation stack trace is recorded (and reported). 1075 These values somewhat decrease Valgrind's memory and cpu usage. 1076 They can be useful depending on the error types you are 1077 searching for and the level of detail you need to analyse 1078 them. For example, if you are only interested in memory leak 1079 errors, it is sufficient to record the allocation stack traces. 1080 </para> 1081 1082 <para>With <varname>none</varname>, no stack traces are recorded 1083 for malloc and free operations. If your program allocates a lot 1084 of blocks and/or allocates/frees from many different stack 1085 traces, this can significantly decrease cpu and/or memory 1086 required. Of course, few details will be reported for errors 1087 related to heap blocks. 1088 </para> 1089 1090 <para>Note that once a stack trace is recorded, Valgrind keeps 1091 the stack trace in memory even if it is not referenced by any 1092 block. Some programs (for example, recursive algorithms) can 1093 generate a huge number of stack traces. If Valgrind uses too 1094 much memory in such circumstances, you can reduce the memory 1095 required with the options <varname>--keep-stacktraces</varname> 1096 and/or by using a smaller value for the 1097 option <varname>--num-callers</varname>. 1098 </para> 1099 1100 <para>If you want to use 1101 <computeroutput>--xtree-memory=full</computeroutput> memory profiling 1102 (see <xref linkend="manual-core.xtree"/> ), then you cannot 1103 specify <varname>--keep-stacktraces=free</varname> 1104 or <varname>--keep-stacktraces=none</varname>.</para> 1105 1106 </listitem> 1107 </varlistentry> 1108 1109 <varlistentry id="opt.freelist-vol" xreflabel="--freelist-vol"> 1110 <term> 1111 <option><![CDATA[--freelist-vol=<number> [default: 20000000] ]]></option> 1112 </term> 1113 <listitem> 1114 <para>When the client program releases memory using 1115 <function>free</function> (in <literal>C</literal>) or 1116 <computeroutput>delete</computeroutput> 1117 (<literal>C++</literal>), that memory is not immediately made 1118 available for re-allocation. Instead, it is marked inaccessible 1119 and placed in a queue of freed blocks. The purpose is to defer as 1120 long as possible the point at which freed-up memory comes back 1121 into circulation. This increases the chance that 1122 Memcheck will be able to detect invalid 1123 accesses to blocks for some significant period of time after they 1124 have been freed.</para> 1125 1126 <para>This option specifies the maximum total size, in bytes, of the 1127 blocks in the queue. The default value is twenty million bytes. 1128 Increasing this increases the total amount of memory used by 1129 Memcheck but may detect invalid uses of freed 1130 blocks which would otherwise go undetected.</para> 1131 </listitem> 1132 </varlistentry> 1133 1134 <varlistentry id="opt.freelist-big-blocks" xreflabel="--freelist-big-blocks"> 1135 <term> 1136 <option><![CDATA[--freelist-big-blocks=<number> [default: 1000000] ]]></option> 1137 </term> 1138 <listitem> 1139 <para>When making blocks from the queue of freed blocks available 1140 for re-allocation, Memcheck will in priority re-circulate the blocks 1141 with a size greater or equal to <option>--freelist-big-blocks</option>. 1142 This ensures that freeing big blocks (in particular freeing blocks bigger than 1143 <option>--freelist-vol</option>) does not immediately lead to a re-circulation 1144 of all (or a lot of) the small blocks in the free list. In other words, 1145 this option increases the likelihood to discover dangling pointers 1146 for the "small" blocks, even when big blocks are freed.</para> 1147 <para>Setting a value of 0 means that all the blocks are re-circulated 1148 in a FIFO order. </para> 1149 </listitem> 1150 </varlistentry> 1151 1152 <varlistentry id="opt.workaround-gcc296-bugs" xreflabel="--workaround-gcc296-bugs"> 1153 <term> 1154 <option><![CDATA[--workaround-gcc296-bugs=<yes|no> [default: no] ]]></option> 1155 </term> 1156 <listitem> 1157 <para>When enabled, assume that reads and writes some small 1158 distance below the stack pointer are due to bugs in GCC 2.96, and 1159 does not report them. The "small distance" is 256 bytes by 1160 default. Note that GCC 2.96 is the default compiler on some ancient 1161 Linux distributions (RedHat 7.X) and so you may need to use this 1162 option. Do not use it if you do not have to, as it can cause real 1163 errors to be overlooked. A better alternative is to use a more 1164 recent GCC in which this bug is fixed.</para> 1165 1166 <para>You may also need to use this option when working with 1167 GCC 3.X or 4.X on 32-bit PowerPC Linux. This is because 1168 GCC generates code which occasionally accesses below the 1169 stack pointer, particularly for floating-point to/from integer 1170 conversions. This is in violation of the 32-bit PowerPC ELF 1171 specification, which makes no provision for locations below the 1172 stack pointer to be accessible.</para> 1173 1174 <para>This option is deprecated as of version 3.12 and may be 1175 removed from future versions. You should instead use 1176 <option>--ignore-range-below-sp</option> to specify the exact 1177 range of offsets below the stack pointer that should be ignored. 1178 A suitable equivalent 1179 is <option>--ignore-range-below-sp=1024-1</option>. 1180 </para> 1181 </listitem> 1182 </varlistentry> 1183 1184 <varlistentry id="opt.ignore-range-below-sp" 1185 xreflabel="--ignore-range-below-sp"> 1186 <term> 1187 <option><![CDATA[--ignore-range-below-sp=<number>-<number> ]]></option> 1188 </term> 1189 <listitem> 1190 <para>This is a more general replacement for the deprecated 1191 <option>--workaround-gcc296-bugs</option> option. When 1192 specified, it causes Memcheck not to report errors for accesses 1193 at the specified offsets below the stack pointer. The two 1194 offsets must be positive decimal numbers and -- somewhat 1195 counterintuitively -- the first one must be larger, in order to 1196 imply a non-wraparound address range to ignore. For example, 1197 to ignore 4 byte accesses at 8192 bytes below the stack 1198 pointer, 1199 use <option>--ignore-range-below-sp=8192-8189</option>. Only 1200 one range may be specified. 1201 </para> 1202 </listitem> 1203 </varlistentry> 1204 1205 <varlistentry id="opt.show-mismatched-frees" 1206 xreflabel="--show-mismatched-frees"> 1207 <term> 1208 <option><![CDATA[--show-mismatched-frees=<yes|no> [default: yes] ]]></option> 1209 </term> 1210 <listitem> 1211 <para>When enabled, Memcheck checks that heap blocks are 1212 deallocated using a function that matches the allocating 1213 function. That is, it expects <varname>free</varname> to be 1214 used to deallocate blocks allocated 1215 by <varname>malloc</varname>, <varname>delete</varname> for 1216 blocks allocated by <varname>new</varname>, 1217 and <varname>delete[]</varname> for blocks allocated 1218 by <varname>new[]</varname>. If a mismatch is detected, an 1219 error is reported. This is in general important because in some 1220 environments, freeing with a non-matching function can cause 1221 crashes.</para> 1222 1223 <para>There is however a scenario where such mismatches cannot 1224 be avoided. That is when the user provides implementations of 1225 <varname>new</varname>/<varname>new[]</varname> that 1226 call <varname>malloc</varname> and 1227 of <varname>delete</varname>/<varname>delete[]</varname> that 1228 call <varname>free</varname>, and these functions are 1229 asymmetrically inlined. For example, imagine 1230 that <varname>delete[]</varname> is inlined 1231 but <varname>new[]</varname> is not. The result is that 1232 Memcheck "sees" all <varname>delete[]</varname> calls as direct 1233 calls to <varname>free</varname>, even when the program source 1234 contains no mismatched calls.</para> 1235 1236 <para>This causes a lot of confusing and irrelevant error 1237 reports. <varname>--show-mismatched-frees=no</varname> disables 1238 these checks. It is not generally advisable to disable them, 1239 though, because you may miss real errors as a result.</para> 1240 </listitem> 1241 </varlistentry> 1242 1243 <varlistentry id="opt.ignore-ranges" xreflabel="--ignore-ranges"> 1244 <term> 1245 <option><![CDATA[--ignore-ranges=0xPP-0xQQ[,0xRR-0xSS] ]]></option> 1246 </term> 1247 <listitem> 1248 <para>Any ranges listed in this option (and multiple ranges can be 1249 specified, separated by commas) will be ignored by Memcheck's 1250 addressability checking.</para> 1251 </listitem> 1252 </varlistentry> 1253 1254 <varlistentry id="opt.malloc-fill" xreflabel="--malloc-fill"> 1255 <term> 1256 <option><![CDATA[--malloc-fill=<hexnumber> ]]></option> 1257 </term> 1258 <listitem> 1259 <para>Fills blocks allocated 1260 by <computeroutput>malloc</computeroutput>, 1261 <computeroutput>new</computeroutput>, etc, but not 1262 by <computeroutput>calloc</computeroutput>, with the specified 1263 byte. This can be useful when trying to shake out obscure 1264 memory corruption problems. The allocated area is still 1265 regarded by Memcheck as undefined -- this option only affects its 1266 contents. Note that <option>--malloc-fill</option> does not 1267 affect a block of memory when it is used as argument 1268 to client requests VALGRIND_MEMPOOL_ALLOC or 1269 VALGRIND_MALLOCLIKE_BLOCK. 1270 </para> 1271 </listitem> 1272 </varlistentry> 1273 1274 <varlistentry id="opt.free-fill" xreflabel="--free-fill"> 1275 <term> 1276 <option><![CDATA[--free-fill=<hexnumber> ]]></option> 1277 </term> 1278 <listitem> 1279 <para>Fills blocks freed 1280 by <computeroutput>free</computeroutput>, 1281 <computeroutput>delete</computeroutput>, etc, with the 1282 specified byte value. This can be useful when trying to shake out 1283 obscure memory corruption problems. The freed area is still 1284 regarded by Memcheck as not valid for access -- this option only 1285 affects its contents. Note that <option>--free-fill</option> does not 1286 affect a block of memory when it is used as argument to 1287 client requests VALGRIND_MEMPOOL_FREE or VALGRIND_FREELIKE_BLOCK. 1288 </para> 1289 </listitem> 1290 </varlistentry> 1291 1292</variablelist> 1293<!-- end of xi:include in the manpage --> 1294 1295</sect1> 1296 1297 1298<sect1 id="mc-manual.suppfiles" xreflabel="Writing suppression files"> 1299<title>Writing suppression files</title> 1300 1301<para>The basic suppression format is described in 1302<xref linkend="manual-core.suppress"/>.</para> 1303 1304<para>The suppression-type (second) line should have the form:</para> 1305<programlisting><![CDATA[ 1306Memcheck:suppression_type]]></programlisting> 1307 1308<para>The Memcheck suppression types are as follows:</para> 1309 1310<itemizedlist> 1311 <listitem> 1312 <para><varname>Value1</varname>, 1313 <varname>Value2</varname>, 1314 <varname>Value4</varname>, 1315 <varname>Value8</varname>, 1316 <varname>Value16</varname>, 1317 meaning an uninitialised-value error when 1318 using a value of 1, 2, 4, 8 or 16 bytes.</para> 1319 </listitem> 1320 1321 <listitem> 1322 <para><varname>Cond</varname> (or its old 1323 name, <varname>Value0</varname>), meaning use 1324 of an uninitialised CPU condition code.</para> 1325 </listitem> 1326 1327 <listitem> 1328 <para><varname>Addr1</varname>, 1329 <varname>Addr2</varname>, 1330 <varname>Addr4</varname>, 1331 <varname>Addr8</varname>, 1332 <varname>Addr16</varname>, 1333 meaning an invalid address during a 1334 memory access of 1, 2, 4, 8 or 16 bytes respectively.</para> 1335 </listitem> 1336 1337 <listitem> 1338 <para><varname>Jump</varname>, meaning an 1339 jump to an unaddressable location error.</para> 1340 </listitem> 1341 1342 <listitem> 1343 <para><varname>Param</varname>, meaning an 1344 invalid system call parameter error.</para> 1345 </listitem> 1346 1347 <listitem> 1348 <para><varname>Free</varname>, meaning an 1349 invalid or mismatching free.</para> 1350 </listitem> 1351 1352 <listitem> 1353 <para><varname>Overlap</varname>, meaning a 1354 <computeroutput>src</computeroutput> / 1355 <computeroutput>dst</computeroutput> overlap in 1356 <function>memcpy</function> or a similar function.</para> 1357 </listitem> 1358 1359 <listitem> 1360 <para><varname>Leak</varname>, meaning 1361 a memory leak.</para> 1362 </listitem> 1363 1364</itemizedlist> 1365 1366<para><computeroutput>Param</computeroutput> errors have a mandatory extra 1367information line at this point, which is the name of the offending 1368system call parameter. </para> 1369 1370<para><computeroutput>Leak</computeroutput> errors have an optional 1371extra information line, with the following format:</para> 1372<programlisting><![CDATA[ 1373match-leak-kinds:<set>]]></programlisting> 1374<para>where <computeroutput><set></computeroutput> specifies which 1375leak kinds are matched by this suppression entry. 1376<computeroutput><set></computeroutput> is specified in the 1377same way as with the option <option>--show-leak-kinds</option>, that is, 1378one of the following:</para> 1379<itemizedlist> 1380 <listitem>a comma separated list of one or more of 1381 <option>definite indirect possible reachable</option>. 1382 </listitem> 1383 1384 <listitem><option>all</option> to specify the complete set (all leak kinds). 1385 </listitem> 1386 1387 <listitem><option>none</option> for the empty set. 1388 </listitem> 1389</itemizedlist> 1390<para>If this optional extra line is not present, the suppression 1391entry will match all leak kinds.</para> 1392 1393<para>Be aware that leak suppressions that are created using 1394<option>--gen-suppressions</option> will contain this optional extra 1395line, and therefore may match fewer leaks than you expect. You may 1396want to remove the line before using the generated 1397suppressions.</para> 1398 1399<para>The other Memcheck error kinds do not have extra lines.</para> 1400 1401<para> 1402If you give the <option>-v</option> option, Valgrind will print 1403the list of used suppressions at the end of execution. 1404For a leak suppression, this output gives the number of different 1405loss records that match the suppression, and the number of bytes 1406and blocks suppressed by the suppression. 1407If the run contains multiple leak checks, the number of bytes and blocks 1408are reset to zero before each new leak check. Note that the number of different 1409loss records is not reset to zero.</para> 1410<para>In the example below, in the last leak search, 7 blocks and 96 bytes have 1411been suppressed by a suppression with the name 1412<option>some_leak_suppression</option>:</para> 1413<programlisting><![CDATA[ 1414--21041-- used_suppression: 10 some_other_leak_suppression s.supp:14 suppressed: 12,400 bytes in 1 blocks 1415--21041-- used_suppression: 39 some_leak_suppression s.supp:2 suppressed: 96 bytes in 7 blocks 1416]]></programlisting> 1417 1418<para>For <varname>ValueN</varname> and <varname>AddrN</varname> 1419errors, the first line of the calling context is either the name of 1420the function in which the error occurred, or, failing that, the full 1421path of the <filename>.so</filename> file or executable containing the 1422error location. For <varname>Free</varname> errors, the first line is 1423the name of the function doing the freeing (eg, 1424<function>free</function>, <function>__builtin_vec_delete</function>, 1425etc). For <varname>Overlap</varname> errors, the first line is the name of the 1426function with the overlapping arguments (eg. 1427<function>memcpy</function>, <function>strcpy</function>, etc).</para> 1428 1429<para>The last part of any suppression specifies the rest of the 1430calling context that needs to be matched.</para> 1431 1432</sect1> 1433 1434 1435 1436<sect1 id="mc-manual.machine" 1437 xreflabel="Details of Memcheck's checking machinery"> 1438<title>Details of Memcheck's checking machinery</title> 1439 1440<para>Read this section if you want to know, in detail, exactly 1441what and how Memcheck is checking.</para> 1442 1443 1444<sect2 id="mc-manual.value" xreflabel="Valid-value (V) bit"> 1445<title>Valid-value (V) bits</title> 1446 1447<para>It is simplest to think of Memcheck implementing a synthetic CPU 1448which is identical to a real CPU, except for one crucial detail. Every 1449bit (literally) of data processed, stored and handled by the real CPU 1450has, in the synthetic CPU, an associated "valid-value" bit, which says 1451whether or not the accompanying bit has a legitimate value. In the 1452discussions which follow, this bit is referred to as the V (valid-value) 1453bit.</para> 1454 1455<para>Each byte in the system therefore has a 8 V bits which follow it 1456wherever it goes. For example, when the CPU loads a word-size item (4 1457bytes) from memory, it also loads the corresponding 32 V bits from a 1458bitmap which stores the V bits for the process' entire address space. 1459If the CPU should later write the whole or some part of that value to 1460memory at a different address, the relevant V bits will be stored back 1461in the V-bit bitmap.</para> 1462 1463<para>In short, each bit in the system has (conceptually) an associated V 1464bit, which follows it around everywhere, even inside the CPU. Yes, all the 1465CPU's registers (integer, floating point, vector and condition registers) 1466have their own V bit vectors. For this to work, Memcheck uses a great deal 1467of compression to represent the V bits compactly.</para> 1468 1469<para>Copying values around does not cause Memcheck to check for, or 1470report on, errors. However, when a value is used in a way which might 1471conceivably affect your program's externally-visible behaviour, 1472the associated V bits are immediately checked. If any of these indicate 1473that the value is undefined (even partially), an error is reported.</para> 1474 1475<para>Here's an (admittedly nonsensical) example:</para> 1476<programlisting><![CDATA[ 1477int i, j; 1478int a[10], b[10]; 1479for ( i = 0; i < 10; i++ ) { 1480 j = a[i]; 1481 b[i] = j; 1482}]]></programlisting> 1483 1484<para>Memcheck emits no complaints about this, since it merely copies 1485uninitialised values from <varname>a[]</varname> into 1486<varname>b[]</varname>, and doesn't use them in a way which could 1487affect the behaviour of the program. However, if 1488the loop is changed to:</para> 1489<programlisting><![CDATA[ 1490for ( i = 0; i < 10; i++ ) { 1491 j += a[i]; 1492} 1493if ( j == 77 ) 1494 printf("hello there\n"); 1495]]></programlisting> 1496 1497<para>then Memcheck will complain, at the 1498<computeroutput>if</computeroutput>, that the condition depends on 1499uninitialised values. Note that it <command>doesn't</command> complain 1500at the <varname>j += a[i];</varname>, since at that point the 1501undefinedness is not "observable". It's only when a decision has to be 1502made as to whether or not to do the <function>printf</function> -- an 1503observable action of your program -- that Memcheck complains.</para> 1504 1505<para>Most low level operations, such as adds, cause Memcheck to use the 1506V bits for the operands to calculate the V bits for the result. Even if 1507the result is partially or wholly undefined, it does not 1508complain.</para> 1509 1510<para>Checks on definedness only occur in three places: when a value is 1511used to generate a memory address, when control flow decision needs to 1512be made, and when a system call is detected, Memcheck checks definedness 1513of parameters as required.</para> 1514 1515<para>If a check should detect undefinedness, an error message is 1516issued. The resulting value is subsequently regarded as well-defined. 1517To do otherwise would give long chains of error messages. In other 1518words, once Memcheck reports an undefined value error, it tries to 1519avoid reporting further errors derived from that same undefined 1520value.</para> 1521 1522<para>This sounds overcomplicated. Why not just check all reads from 1523memory, and complain if an undefined value is loaded into a CPU 1524register? Well, that doesn't work well, because perfectly legitimate C 1525programs routinely copy uninitialised values around in memory, and we 1526don't want endless complaints about that. Here's the canonical example. 1527Consider a struct like this:</para> 1528<programlisting><![CDATA[ 1529struct S { int x; char c; }; 1530struct S s1, s2; 1531s1.x = 42; 1532s1.c = 'z'; 1533s2 = s1; 1534]]></programlisting> 1535 1536<para>The question to ask is: how large is <varname>struct S</varname>, 1537in bytes? An <varname>int</varname> is 4 bytes and a 1538<varname>char</varname> one byte, so perhaps a <varname>struct 1539S</varname> occupies 5 bytes? Wrong. All non-toy compilers we know 1540of will round the size of <varname>struct S</varname> up to a whole 1541number of words, in this case 8 bytes. Not doing this forces compilers 1542to generate truly appalling code for accessing arrays of 1543<varname>struct S</varname>'s on some architectures.</para> 1544 1545<para>So <varname>s1</varname> occupies 8 bytes, yet only 5 of them will 1546be initialised. For the assignment <varname>s2 = s1</varname>, GCC 1547generates code to copy all 8 bytes wholesale into <varname>s2</varname> 1548without regard for their meaning. If Memcheck simply checked values as 1549they came out of memory, it would yelp every time a structure assignment 1550like this happened. So the more complicated behaviour described above 1551is necessary. This allows GCC to copy 1552<varname>s1</varname> into <varname>s2</varname> any way it likes, and a 1553warning will only be emitted if the uninitialised values are later 1554used.</para> 1555 1556</sect2> 1557 1558 1559<sect2 id="mc-manual.vaddress" xreflabel=" Valid-address (A) bits"> 1560<title>Valid-address (A) bits</title> 1561 1562<para>Notice that the previous subsection describes how the validity of 1563values is established and maintained without having to say whether the 1564program does or does not have the right to access any particular memory 1565location. We now consider the latter question.</para> 1566 1567<para>As described above, every bit in memory or in the CPU has an 1568associated valid-value (V) bit. In addition, all bytes in memory, but 1569not in the CPU, have an associated valid-address (A) bit. This 1570indicates whether or not the program can legitimately read or write that 1571location. It does not give any indication of the validity of the data 1572at that location -- that's the job of the V bits -- only whether or not 1573the location may be accessed.</para> 1574 1575<para>Every time your program reads or writes memory, Memcheck checks 1576the A bits associated with the address. If any of them indicate an 1577invalid address, an error is emitted. Note that the reads and writes 1578themselves do not change the A bits, only consult them.</para> 1579 1580<para>So how do the A bits get set/cleared? Like this:</para> 1581 1582<itemizedlist> 1583 <listitem> 1584 <para>When the program starts, all the global data areas are 1585 marked as accessible.</para> 1586 </listitem> 1587 1588 <listitem> 1589 <para>When the program does 1590 <function>malloc</function>/<computeroutput>new</computeroutput>, 1591 the A bits for exactly the area allocated, and not a byte more, 1592 are marked as accessible. Upon freeing the area the A bits are 1593 changed to indicate inaccessibility.</para> 1594 </listitem> 1595 1596 <listitem> 1597 <para>When the stack pointer register (<literal>SP</literal>) moves 1598 up or down, A bits are set. The rule is that the area from 1599 <literal>SP</literal> up to the base of the stack is marked as 1600 accessible, and below <literal>SP</literal> is inaccessible. (If 1601 that sounds illogical, bear in mind that the stack grows down, not 1602 up, on almost all Unix systems, including GNU/Linux.) Tracking 1603 <literal>SP</literal> like this has the useful side-effect that the 1604 section of stack used by a function for local variables etc is 1605 automatically marked accessible on function entry and inaccessible 1606 on exit.</para> 1607 </listitem> 1608 1609 <listitem> 1610 <para>When doing system calls, A bits are changed appropriately. 1611 For example, <literal>mmap</literal> 1612 magically makes files appear in the process' 1613 address space, so the A bits must be updated if <literal>mmap</literal> 1614 succeeds.</para> 1615 </listitem> 1616 1617 <listitem> 1618 <para>Optionally, your program can tell Memcheck about such changes 1619 explicitly, using the client request mechanism described 1620 above.</para> 1621 </listitem> 1622 1623</itemizedlist> 1624 1625</sect2> 1626 1627 1628<sect2 id="mc-manual.together" xreflabel="Putting it all together"> 1629<title>Putting it all together</title> 1630 1631<para>Memcheck's checking machinery can be summarised as 1632follows:</para> 1633 1634<itemizedlist> 1635 <listitem> 1636 <para>Each byte in memory has 8 associated V (valid-value) bits, 1637 saying whether or not the byte has a defined value, and a single A 1638 (valid-address) bit, saying whether or not the program currently has 1639 the right to read/write that address. As mentioned above, heavy 1640 use of compression means the overhead is typically around 25%.</para> 1641 </listitem> 1642 1643 <listitem> 1644 <para>When memory is read or written, the relevant A bits are 1645 consulted. If they indicate an invalid address, Memcheck emits an 1646 Invalid read or Invalid write error.</para> 1647 </listitem> 1648 1649 <listitem> 1650 <para>When memory is read into the CPU's registers, the relevant V 1651 bits are fetched from memory and stored in the simulated CPU. They 1652 are not consulted.</para> 1653 </listitem> 1654 1655 <listitem> 1656 <para>When a register is written out to memory, the V bits for that 1657 register are written back to memory too.</para> 1658 </listitem> 1659 1660 <listitem> 1661 <para>When values in CPU registers are used to generate a memory 1662 address, or to determine the outcome of a conditional branch, the V 1663 bits for those values are checked, and an error emitted if any of 1664 them are undefined.</para> 1665 </listitem> 1666 1667 <listitem> 1668 <para>When values in CPU registers are used for any other purpose, 1669 Memcheck computes the V bits for the result, but does not check 1670 them.</para> 1671 </listitem> 1672 1673 <listitem> 1674 <para>Once the V bits for a value in the CPU have been checked, they 1675 are then set to indicate validity. This avoids long chains of 1676 errors.</para> 1677 </listitem> 1678 1679 <listitem> 1680 <para>When values are loaded from memory, Memcheck checks the A bits 1681 for that location and issues an illegal-address warning if needed. 1682 In that case, the V bits loaded are forced to indicate Valid, 1683 despite the location being invalid.</para> 1684 1685 <para>This apparently strange choice reduces the amount of confusing 1686 information presented to the user. It avoids the unpleasant 1687 phenomenon in which memory is read from a place which is both 1688 unaddressable and contains invalid values, and, as a result, you get 1689 not only an invalid-address (read/write) error, but also a 1690 potentially large set of uninitialised-value errors, one for every 1691 time the value is used.</para> 1692 1693 <para>There is a hazy boundary case to do with multi-byte loads from 1694 addresses which are partially valid and partially invalid. See 1695 details of the option <option>--partial-loads-ok</option> for details. 1696 </para> 1697 </listitem> 1698 1699</itemizedlist> 1700 1701 1702<para>Memcheck intercepts calls to <function>malloc</function>, 1703<function>calloc</function>, <function>realloc</function>, 1704<function>valloc</function>, <function>memalign</function>, 1705<function>free</function>, <computeroutput>new</computeroutput>, 1706<computeroutput>new[]</computeroutput>, 1707<computeroutput>delete</computeroutput> and 1708<computeroutput>delete[]</computeroutput>. The behaviour you get 1709is:</para> 1710 1711<itemizedlist> 1712 1713 <listitem> 1714 <para><function>malloc</function>/<function>new</function>/<computeroutput>new[]</computeroutput>: 1715 the returned memory is marked as addressable but not having valid 1716 values. This means you have to write to it before you can read 1717 it.</para> 1718 </listitem> 1719 1720 <listitem> 1721 <para><function>calloc</function>: returned memory is marked both 1722 addressable and valid, since <function>calloc</function> clears 1723 the area to zero.</para> 1724 </listitem> 1725 1726 <listitem> 1727 <para><function>realloc</function>: if the new size is larger than 1728 the old, the new section is addressable but invalid, as with 1729 <function>malloc</function>. If the new size is smaller, the 1730 dropped-off section is marked as unaddressable. You may only pass to 1731 <function>realloc</function> a pointer previously issued to you by 1732 <function>malloc</function>/<function>calloc</function>/<function>realloc</function>.</para> 1733 </listitem> 1734 1735 <listitem> 1736 <para><function>free</function>/<computeroutput>delete</computeroutput>/<computeroutput>delete[]</computeroutput>: 1737 you may only pass to these functions a pointer previously issued 1738 to you by the corresponding allocation function. Otherwise, 1739 Memcheck complains. If the pointer is indeed valid, Memcheck 1740 marks the entire area it points at as unaddressable, and places 1741 the block in the freed-blocks-queue. The aim is to defer as long 1742 as possible reallocation of this block. Until that happens, all 1743 attempts to access it will elicit an invalid-address error, as you 1744 would hope.</para> 1745 </listitem> 1746 1747</itemizedlist> 1748 1749</sect2> 1750</sect1> 1751 1752<sect1 id="mc-manual.monitor-commands" xreflabel="Memcheck Monitor Commands"> 1753<title>Memcheck Monitor Commands</title> 1754<para>The Memcheck tool provides monitor commands handled by Valgrind's 1755built-in gdbserver (see <xref linkend="manual-core-adv.gdbserver-commandhandling"/>). 1756</para> 1757 1758<itemizedlist> 1759 <listitem> 1760 <para><varname>xb <addr> [<len>]</varname> 1761 shows the definedness (V) bits and values for <len> (default 1) 1762 bytes starting at <addr>. 1763 For each 8 bytes, two lines are output. 1764 </para> 1765 <para> 1766 The first line shows the validity bits for 8 bytes. 1767 The definedness of each byte in the range is given using two hexadecimal 1768 digits. These hexadecimal digits encode the validity of each bit of the 1769 corresponding byte, 1770 using 0 if the bit is defined and 1 if the bit is undefined. 1771 If a byte is not addressable, its validity bits are replaced 1772 by <varname>__</varname> (a double underscore). 1773 </para> 1774 <para> 1775 The second line shows the values of the bytes below the corresponding 1776 validity bits. The format used to show the bytes data is similar to the 1777 GDB command 'x /<len>xb <addr>'. The value for a non 1778 addressable bytes is shown as ?? (two question marks). 1779 </para> 1780 <para> 1781 In the following example, <varname>string10</varname> is an array 1782 of 10 characters, in which the even numbered bytes are 1783 undefined. In the below example, the byte corresponding 1784 to <varname>string10[5]</varname> is not addressable. 1785 </para> 1786<programlisting><![CDATA[ 1787(gdb) p &string10 1788$4 = (char (*)[10]) 0x804a2f0 1789(gdb) mo xb 0x804a2f0 10 1790 ff 00 ff 00 ff __ ff 00 17910x804A2F0: 0x3f 0x6e 0x3f 0x65 0x3f 0x?? 0x3f 0x65 1792 ff 00 17930x804A2F8: 0x3f 0x00 1794Address 0x804A2F0 len 10 has 1 bytes unaddressable 1795(gdb) 1796]]></programlisting> 1797 1798 <para> The command xb cannot be used with registers. To get 1799 the validity bits of a register, you must start Valgrind with the 1800 option <option>--vgdb-shadow-registers=yes</option>. The validity 1801 bits of a register can then be obtained by printing the 'shadow 1' 1802 corresponding register. In the below x86 example, the register 1803 eax has all its bits undefined, while the register ebx is fully 1804 defined. 1805 </para> 1806<programlisting><![CDATA[ 1807(gdb) p /x $eaxs1 1808$9 = 0xffffffff 1809(gdb) p /x $ebxs1 1810$10 = 0x0 1811(gdb) 1812]]></programlisting> 1813 1814 </listitem> 1815 1816 <listitem> 1817 <para><varname>get_vbits <addr> [<len>]</varname> 1818 shows the definedness (V) bits for <len> (default 1) bytes 1819 starting at <addr> using the same convention as the 1820 <varname>xb</varname> command. <varname>get_vbits</varname> only 1821 shows the V bits (grouped by 4 bytes). It does not show the values. 1822 If you want to associate V bits with the corresponding byte values, the 1823 <varname>xb</varname> command will be easier to use, in particular 1824 on little endian computers when associating undefined parts of an integer 1825 with their V bits values. 1826 </para> 1827 <para> 1828 The following example shows the result of <varname>get_vibts</varname> 1829 on the <varname>string10</varname> used in the <varname>xb</varname> 1830 command explanation. 1831 </para> 1832<programlisting><![CDATA[ 1833(gdb) monitor get_vbits 0x804a2f0 10 1834ff00ff00 ff__ff00 ff00 1835Address 0x804A2F0 len 10 has 1 bytes unaddressable 1836(gdb) 1837]]></programlisting> 1838 1839 </listitem> 1840 1841 <listitem> 1842 <para><varname>make_memory 1843 [noaccess|undefined|defined|Definedifaddressable] <addr> 1844 [<len>]</varname> marks the range of <len> (default 1) 1845 bytes at <addr> as having the given status. Parameter 1846 <varname>noaccess</varname> marks the range as non-accessible, so 1847 Memcheck will report an error on any access to it. 1848 <varname>undefined</varname> or <varname>defined</varname> mark 1849 the area as accessible, but Memcheck regards the bytes in it 1850 respectively as having undefined or defined values. 1851 <varname>Definedifaddressable</varname> marks as defined, bytes in 1852 the range which are already addressible, but makes no change to 1853 the status of bytes in the range which are not addressible. Note 1854 that the first letter of <varname>Definedifaddressable</varname> 1855 is an uppercase D to avoid confusion with <varname>defined</varname>. 1856 </para> 1857 1858 <para> 1859 In the following example, the first byte of the 1860 <varname>string10</varname> is marked as defined: 1861 </para> 1862<programlisting><![CDATA[ 1863(gdb) monitor make_memory defined 0x8049e28 1 1864(gdb) monitor get_vbits 0x8049e28 10 18650000ff00 ff00ff00 ff00 1866(gdb) 1867]]></programlisting> 1868 </listitem> 1869 1870 <listitem> 1871 <para><varname>check_memory [addressable|defined] <addr> 1872 [<len>]</varname> checks that the range of <len> 1873 (default 1) bytes at <addr> has the specified accessibility. 1874 It then outputs a description of <addr>. In the following 1875 example, a detailed description is available because the 1876 option <option>--read-var-info=yes</option> was given at Valgrind 1877 startup: 1878 </para> 1879<programlisting><![CDATA[ 1880(gdb) monitor check_memory defined 0x8049e28 1 1881Address 0x8049E28 len 1 defined 1882==14698== Location 0x8049e28 is 0 bytes inside string10[0], 1883==14698== declared at prog.c:10, in frame #0 of thread 1 1884(gdb) 1885]]></programlisting> 1886 </listitem> 1887 1888 <listitem> 1889 <para><varname>leak_check [full*|summary|xtleak] 1890 [kinds <set>|reachable|possibleleak*|definiteleak] 1891 [heuristics heur1,heur2,...] 1892 [increased*|changed|any] 1893 [unlimited*|limited <max_loss_records_output>] 1894 </varname> 1895 performs a leak check. The <varname>*</varname> in the arguments 1896 indicates the default values. </para> 1897 1898 <para> If the <varname>[full*|summary|xtleak]</varname> argument is 1899 <varname>summary</varname>, only a summary of the leak search is given; 1900 otherwise a full leak report is produced. A full leak report gives 1901 detailed information for each leak: the stack trace where the leaked blocks 1902 were allocated, the number of blocks leaked and their total size. When a 1903 full report is requested, the next two arguments further specify what 1904 kind of leaks to report. A leak's details are shown if they match 1905 both the second and third argument. A full leak report might 1906 output detailed information for many leaks. The nr of leaks for 1907 which information is output can be controlled using 1908 the <varname>limited</varname> argument followed by the maximum nr 1909 of leak records to output. If this maximum is reached, the leak 1910 search outputs the records with the biggest number of bytes. 1911 </para> 1912 <para>The value <varname>xtleak</varname> also produces a full leak report, 1913 but output it as an xtree in a file xtleak.kcg.%p.%n (see <xref linkend="opt.log-file"/>). 1914 See <xref linkend="manual-core.xtree"/> 1915 for a detailed explanation about execution trees formats. 1916 See <xref linkend="opt.xtree-leak"/> for the description of the events 1917 in a xtree leak file. 1918 </para> 1919 1920 <para>The <varname>kinds</varname> argument controls what kind of blocks 1921 are shown for a <varname>full</varname> leak search. The set of leak kinds 1922 to show can be specified using a <varname><set></varname> similarly 1923 to the command line option <option>--show-leak-kinds</option>. 1924 Alternatively, the value <varname>definiteleak</varname> 1925 is equivalent to <varname>kinds definite</varname>, the 1926 value <varname>possibleleak</varname> is equivalent to 1927 <varname>kinds definite,possible</varname> : it will also show 1928 possibly leaked blocks, .i.e those for which only an interior 1929 pointer was found. The value <varname>reachable</varname> will 1930 show all block categories (i.e. is equivalent to <varname>kinds 1931 all</varname>). 1932 </para> 1933 1934 <para>The <varname>heuristics</varname> argument controls the heuristics 1935 used during the leak search. The set of heuristics to use can be specified 1936 using a <varname><set></varname> similarly 1937 to the command line option <option>--leak-check-heuristics</option>. 1938 The default value for the <varname>heuristics</varname> argument is 1939 <varname>heuristics none</varname>. 1940 </para> 1941 1942 <para>The <varname>[increased*|changed|any]</varname> argument controls what 1943 kinds of changes are shown for a <varname>full</varname> leak search. The 1944 value <varname>increased</varname> specifies that only block 1945 allocation stacks with an increased number of leaked bytes or 1946 blocks since the previous leak check should be shown. The 1947 value <varname>changed</varname> specifies that allocation stacks 1948 with any change since the previous leak check should be shown. 1949 The value <varname>any</varname> specifies that all leak entries 1950 should be shown, regardless of any increase or decrease. When 1951 If <varname>increased</varname> or <varname>changed</varname> are 1952 specified, the leak report entries will show the delta relative to 1953 the previous leak report. 1954 </para> 1955 1956 <para>The following example shows usage of the 1957 <varname>leak_check</varname> monitor command on 1958 the <varname>memcheck/tests/leak-cases.c</varname> regression 1959 test. The first command outputs one entry having an increase in 1960 the leaked bytes. The second command is the same as the first 1961 command, but uses the abbreviated forms accepted by GDB and the 1962 Valgrind gdbserver. It only outputs the summary information, as 1963 there was no increase since the previous leak search.</para> 1964<programlisting><![CDATA[ 1965(gdb) monitor leak_check full possibleleak increased 1966==19520== 16 (+16) bytes in 1 (+1) blocks are possibly lost in loss record 9 of 12 1967==19520== at 0x40070B4: malloc (vg_replace_malloc.c:263) 1968==19520== by 0x80484D5: mk (leak-cases.c:52) 1969==19520== by 0x804855F: f (leak-cases.c:81) 1970==19520== by 0x80488E0: main (leak-cases.c:107) 1971==19520== 1972==19520== LEAK SUMMARY: 1973==19520== definitely lost: 32 (+0) bytes in 2 (+0) blocks 1974==19520== indirectly lost: 16 (+0) bytes in 1 (+0) blocks 1975==19520== possibly lost: 32 (+16) bytes in 2 (+1) blocks 1976==19520== still reachable: 96 (+16) bytes in 6 (+1) blocks 1977==19520== suppressed: 0 (+0) bytes in 0 (+0) blocks 1978==19520== Reachable blocks (those to which a pointer was found) are not shown. 1979==19520== To see them, add 'reachable any' args to leak_check 1980==19520== 1981(gdb) mo l 1982==19520== LEAK SUMMARY: 1983==19520== definitely lost: 32 (+0) bytes in 2 (+0) blocks 1984==19520== indirectly lost: 16 (+0) bytes in 1 (+0) blocks 1985==19520== possibly lost: 32 (+0) bytes in 2 (+0) blocks 1986==19520== still reachable: 96 (+0) bytes in 6 (+0) blocks 1987==19520== suppressed: 0 (+0) bytes in 0 (+0) blocks 1988==19520== Reachable blocks (those to which a pointer was found) are not shown. 1989==19520== To see them, add 'reachable any' args to leak_check 1990==19520== 1991(gdb) 1992]]></programlisting> 1993 <para>Note that when using Valgrind's gdbserver, it is not 1994 necessary to rerun 1995 with <option>--leak-check=full</option> 1996 <option>--show-reachable=yes</option> to see the reachable 1997 blocks. You can obtain the same information without rerunning by 1998 using the GDB command <computeroutput>monitor leak_check full 1999 reachable any</computeroutput> (or, using 2000 abbreviation: <computeroutput>mo l f r a</computeroutput>). 2001 </para> 2002 </listitem> 2003 2004 <listitem> 2005 <para><varname>block_list <loss_record_nr>|<loss_record_nr_from>..<loss_record_nr_to> 2006 [unlimited*|limited <max_blocks>] 2007 [heuristics heur1,heur2,...] 2008 </varname> 2009 shows the list of blocks belonging to 2010 <varname><loss_record_nr></varname> (or to the loss records range 2011 <varname><loss_record_nr_from>..<loss_record_nr_to></varname>). 2012 The nr of blocks to print can be controlled using the 2013 <varname>limited</varname> argument followed by the maximum nr 2014 of blocks to output. 2015 If one or more heuristics are given, only prints the loss records 2016 and blocks found via one of the given <varname>heur1,heur2,...</varname> 2017 heuristics. 2018 </para> 2019 2020 <para> A leak search merges the allocated blocks in loss records : 2021 a loss record re-groups all blocks having the same state (for 2022 example, Definitely Lost) and the same allocation backtrace. 2023 Each loss record is identified in the leak search result 2024 by a loss record number. 2025 The <varname>block_list</varname> command shows the loss record information 2026 followed by the addresses and sizes of the blocks which have been 2027 merged in the loss record. If a block was found using an heuristic, the block size 2028 is followed by the heuristic. 2029 </para> 2030 2031 <para> If a directly lost block causes some other blocks to be indirectly 2032 lost, the block_list command will also show these indirectly lost blocks. 2033 The indirectly lost blocks will be indented according to the level of indirection 2034 between the directly lost block and the indirectly lost block(s). 2035 Each indirectly lost block is followed by the reference of its loss record. 2036 </para> 2037 2038 <para> The block_list command can be used on the results of a leak search as long 2039 as no block has been freed after this leak search: as soon as the program frees 2040 a block, a new leak search is needed before block_list can be used again. 2041 </para> 2042 2043 <para> 2044 In the below example, the program leaks a tree structure by losing the pointer to 2045 the block A (top of the tree). 2046 So, the block A is directly lost, causing an indirect 2047 loss of blocks B to G. The first block_list command shows the loss record of A 2048 (a definitely lost block with address 0x4028028, size 16). The addresses and sizes 2049 of the indirectly lost blocks due to block A are shown below the block A. 2050 The second command shows the details of one of the indirect loss records output 2051 by the first command. 2052 </para> 2053<programlisting><![CDATA[ 2054 A 2055 / \ 2056 B C 2057 / \ / \ 2058 D E F G 2059]]></programlisting> 2060 2061<programlisting><![CDATA[ 2062(gdb) bt 2063#0 main () at leak-tree.c:69 2064(gdb) monitor leak_check full any 2065==19552== 112 (16 direct, 96 indirect) bytes in 1 blocks are definitely lost in loss record 7 of 7 2066==19552== at 0x40070B4: malloc (vg_replace_malloc.c:263) 2067==19552== by 0x80484D5: mk (leak-tree.c:28) 2068==19552== by 0x80484FC: f (leak-tree.c:41) 2069==19552== by 0x8048856: main (leak-tree.c:63) 2070==19552== 2071==19552== LEAK SUMMARY: 2072==19552== definitely lost: 16 bytes in 1 blocks 2073==19552== indirectly lost: 96 bytes in 6 blocks 2074==19552== possibly lost: 0 bytes in 0 blocks 2075==19552== still reachable: 0 bytes in 0 blocks 2076==19552== suppressed: 0 bytes in 0 blocks 2077==19552== 2078(gdb) monitor block_list 7 2079==19552== 112 (16 direct, 96 indirect) bytes in 1 blocks are definitely lost in loss record 7 of 7 2080==19552== at 0x40070B4: malloc (vg_replace_malloc.c:263) 2081==19552== by 0x80484D5: mk (leak-tree.c:28) 2082==19552== by 0x80484FC: f (leak-tree.c:41) 2083==19552== by 0x8048856: main (leak-tree.c:63) 2084==19552== 0x4028028[16] 2085==19552== 0x4028068[16] indirect loss record 1 2086==19552== 0x40280E8[16] indirect loss record 3 2087==19552== 0x4028128[16] indirect loss record 4 2088==19552== 0x40280A8[16] indirect loss record 2 2089==19552== 0x4028168[16] indirect loss record 5 2090==19552== 0x40281A8[16] indirect loss record 6 2091(gdb) mo b 2 2092==19552== 16 bytes in 1 blocks are indirectly lost in loss record 2 of 7 2093==19552== at 0x40070B4: malloc (vg_replace_malloc.c:263) 2094==19552== by 0x80484D5: mk (leak-tree.c:28) 2095==19552== by 0x8048519: f (leak-tree.c:43) 2096==19552== by 0x8048856: main (leak-tree.c:63) 2097==19552== 0x40280A8[16] 2098==19552== 0x4028168[16] indirect loss record 5 2099==19552== 0x40281A8[16] indirect loss record 6 2100(gdb) 2101 2102]]></programlisting> 2103 2104 </listitem> 2105 2106 <listitem> 2107 <para><varname>who_points_at <addr> [<len>]</varname> 2108 shows all the locations where a pointer to addr is found. 2109 If len is equal to 1, the command only shows the locations pointing 2110 exactly at addr (i.e. the "start pointers" to addr). 2111 If len is > 1, "interior pointers" pointing at the len first bytes 2112 will also be shown. 2113 </para> 2114 2115 <para>The locations searched for are the same as the locations 2116 used in the leak search. So, <varname>who_points_at</varname> can a.o. 2117 be used to show why the leak search still can reach a block, or can 2118 search for dangling pointers to a freed block. 2119 Each location pointing at addr (or pointing inside addr if interior pointers 2120 are being searched for) will be described. 2121 </para> 2122 2123 <para>In the below example, the pointers to the 'tree block A' (see example 2124 in command <varname>block_list</varname>) is shown before the tree was leaked. 2125 The descriptions are detailed as the option <option>--read-var-info=yes</option> 2126 was given at Valgrind startup. The second call shows the pointers (start and interior 2127 pointers) to block G. The block G (0x40281A8) is reachable via block C (0x40280a8) 2128 and register ECX of tid 1 (tid is the Valgrind thread id). 2129 It is "interior reachable" via the register EBX. 2130 </para> 2131 2132<programlisting><![CDATA[ 2133(gdb) monitor who_points_at 0x4028028 2134==20852== Searching for pointers to 0x4028028 2135==20852== *0x8049e20 points at 0x4028028 2136==20852== Location 0x8049e20 is 0 bytes inside global var "t" 2137==20852== declared at leak-tree.c:35 2138(gdb) monitor who_points_at 0x40281A8 16 2139==20852== Searching for pointers pointing in 16 bytes from 0x40281a8 2140==20852== *0x40280ac points at 0x40281a8 2141==20852== Address 0x40280ac is 4 bytes inside a block of size 16 alloc'd 2142==20852== at 0x40070B4: malloc (vg_replace_malloc.c:263) 2143==20852== by 0x80484D5: mk (leak-tree.c:28) 2144==20852== by 0x8048519: f (leak-tree.c:43) 2145==20852== by 0x8048856: main (leak-tree.c:63) 2146==20852== tid 1 register ECX points at 0x40281a8 2147==20852== tid 1 register EBX interior points at 2 bytes inside 0x40281a8 2148(gdb) 2149]]></programlisting> 2150 2151 <para> When <varname>who_points_at</varname> finds an interior pointer, 2152 it will report the heuristic(s) with which this interior pointer 2153 will be considered as reachable. Note that this is done independently 2154 of the value of the option <option>--leak-check-heuristics</option>. 2155 In the below example, the loss record 6 indicates a possibly lost 2156 block. <varname>who_points_at</varname> reports that there is an interior 2157 pointer pointing in this block, and that the block can be considered 2158 reachable using the heuristic 2159 <computeroutput>multipleinheritance</computeroutput>. 2160 </para> 2161 2162<programlisting><![CDATA[ 2163(gdb) monitor block_list 6 2164==3748== 8 bytes in 1 blocks are possibly lost in loss record 6 of 7 2165==3748== at 0x4007D77: operator new(unsigned int) (vg_replace_malloc.c:313) 2166==3748== by 0x8048954: main (leak_cpp_interior.cpp:43) 2167==3748== 0x402A0E0[8] 2168(gdb) monitor who_points_at 0x402A0E0 8 2169==3748== Searching for pointers pointing in 8 bytes from 0x402a0e0 2170==3748== *0xbe8ee078 interior points at 4 bytes inside 0x402a0e0 2171==3748== Address 0xbe8ee078 is on thread 1's stack 2172==3748== block at 0x402a0e0 considered reachable by ptr 0x402a0e4 using multipleinheritance heuristic 2173(gdb) 2174]]></programlisting> 2175 2176 </listitem> 2177 2178</itemizedlist> 2179 2180</sect1> 2181 2182<sect1 id="mc-manual.clientreqs" xreflabel="Client requests"> 2183<title>Client Requests</title> 2184 2185<para>The following client requests are defined in 2186<filename>memcheck.h</filename>. 2187See <filename>memcheck.h</filename> for exact details of their 2188arguments.</para> 2189 2190<itemizedlist> 2191 2192 <listitem> 2193 <para><varname>VALGRIND_MAKE_MEM_NOACCESS</varname>, 2194 <varname>VALGRIND_MAKE_MEM_UNDEFINED</varname> and 2195 <varname>VALGRIND_MAKE_MEM_DEFINED</varname>. 2196 These mark address ranges as completely inaccessible, 2197 accessible but containing undefined data, and accessible and 2198 containing defined data, respectively. They return -1, when 2199 run on Valgrind and 0 otherwise.</para> 2200 </listitem> 2201 2202 <listitem> 2203 <para><varname>VALGRIND_MAKE_MEM_DEFINED_IF_ADDRESSABLE</varname>. 2204 This is just like <varname>VALGRIND_MAKE_MEM_DEFINED</varname> but only 2205 affects those bytes that are already addressable.</para> 2206 </listitem> 2207 2208 <listitem> 2209 <para><varname>VALGRIND_CHECK_MEM_IS_ADDRESSABLE</varname> and 2210 <varname>VALGRIND_CHECK_MEM_IS_DEFINED</varname>: check immediately 2211 whether or not the given address range has the relevant property, 2212 and if not, print an error message. Also, for the convenience of 2213 the client, returns zero if the relevant property holds; otherwise, 2214 the returned value is the address of the first byte for which the 2215 property is not true. Always returns 0 when not run on 2216 Valgrind.</para> 2217 </listitem> 2218 2219 <listitem> 2220 <para><varname>VALGRIND_CHECK_VALUE_IS_DEFINED</varname>: a quick and easy 2221 way to find out whether Valgrind thinks a particular value 2222 (lvalue, to be precise) is addressable and defined. Prints an error 2223 message if not. It has no return value.</para> 2224 </listitem> 2225 2226 <listitem> 2227 <para><varname>VALGRIND_DO_LEAK_CHECK</varname>: does a full memory leak 2228 check (like <option>--leak-check=full</option>) right now. 2229 This is useful for incrementally checking for leaks between arbitrary 2230 places in the program's execution. It has no return value.</para> 2231 </listitem> 2232 2233 <listitem> 2234 <para><varname>VALGRIND_DO_ADDED_LEAK_CHECK</varname>: same as 2235 <varname> VALGRIND_DO_LEAK_CHECK</varname> but only shows the 2236 entries for which there was an increase in leaked bytes or leaked 2237 number of blocks since the previous leak search. It has no return 2238 value.</para> 2239 </listitem> 2240 2241 <listitem> 2242 <para><varname>VALGRIND_DO_CHANGED_LEAK_CHECK</varname>: same as 2243 <varname>VALGRIND_DO_LEAK_CHECK</varname> but only shows the 2244 entries for which there was an increase or decrease in leaked 2245 bytes or leaked number of blocks since the previous leak search. It 2246 has no return value.</para> 2247 </listitem> 2248 2249 <listitem> 2250 <para><varname>VALGRIND_DO_QUICK_LEAK_CHECK</varname>: like 2251 <varname>VALGRIND_DO_LEAK_CHECK</varname>, except it produces only a leak 2252 summary (like <option>--leak-check=summary</option>). 2253 It has no return value.</para> 2254 </listitem> 2255 2256 <listitem> 2257 <para><varname>VALGRIND_COUNT_LEAKS</varname>: fills in the four 2258 arguments with the number of bytes of memory found by the previous 2259 leak check to be leaked (i.e. the sum of direct leaks and indirect leaks), 2260 dubious, reachable and suppressed. This is useful in test harness code, 2261 after calling <varname>VALGRIND_DO_LEAK_CHECK</varname> or 2262 <varname>VALGRIND_DO_QUICK_LEAK_CHECK</varname>.</para> 2263 </listitem> 2264 2265 <listitem> 2266 <para><varname>VALGRIND_COUNT_LEAK_BLOCKS</varname>: identical to 2267 <varname>VALGRIND_COUNT_LEAKS</varname> except that it returns the 2268 number of blocks rather than the number of bytes in each 2269 category.</para> 2270 </listitem> 2271 2272 <listitem> 2273 <para><varname>VALGRIND_GET_VBITS</varname> and 2274 <varname>VALGRIND_SET_VBITS</varname>: allow you to get and set the 2275 V (validity) bits for an address range. You should probably only 2276 set V bits that you have got with 2277 <varname>VALGRIND_GET_VBITS</varname>. Only for those who really 2278 know what they are doing.</para> 2279 </listitem> 2280 2281 <listitem> 2282 <para><varname>VALGRIND_CREATE_BLOCK</varname> and 2283 <varname>VALGRIND_DISCARD</varname>. <varname>VALGRIND_CREATE_BLOCK</varname> 2284 takes an address, a number of bytes and a character string. The 2285 specified address range is then associated with that string. When 2286 Memcheck reports an invalid access to an address in the range, it 2287 will describe it in terms of this block rather than in terms of 2288 any other block it knows about. Note that the use of this macro 2289 does not actually change the state of memory in any way -- it 2290 merely gives a name for the range. 2291 </para> 2292 2293 <para>At some point you may want Memcheck to stop reporting errors 2294 in terms of the block named 2295 by <varname>VALGRIND_CREATE_BLOCK</varname>. To make this 2296 possible, <varname>VALGRIND_CREATE_BLOCK</varname> returns a 2297 "block handle", which is a C <varname>int</varname> value. You 2298 can pass this block handle to <varname>VALGRIND_DISCARD</varname>. 2299 After doing so, Valgrind will no longer relate addressing errors 2300 in the specified range to the block. Passing invalid handles to 2301 <varname>VALGRIND_DISCARD</varname> is harmless. 2302 </para> 2303 </listitem> 2304 2305</itemizedlist> 2306 2307</sect1> 2308 2309 2310 2311 2312<sect1 id="mc-manual.mempools" xreflabel="Memory Pools"> 2313<title>Memory Pools: describing and working with custom allocators</title> 2314 2315<para>Some programs use custom memory allocators, often for performance 2316reasons. Left to itself, Memcheck is unable to understand the 2317behaviour of custom allocation schemes as well as it understands the 2318standard allocators, and so may miss errors and leaks in your program. What 2319this section describes is a way to give Memcheck enough of a description of 2320your custom allocator that it can make at least some sense of what is 2321happening.</para> 2322 2323<para>There are many different sorts of custom allocator, so Memcheck 2324attempts to reason about them using a loose, abstract model. We 2325use the following terminology when describing custom allocation 2326systems:</para> 2327 2328<itemizedlist> 2329 <listitem> 2330 <para>Custom allocation involves a set of independent "memory pools". 2331 </para> 2332 </listitem> 2333 <listitem> 2334 <para>Memcheck's notion of a a memory pool consists of a single "anchor 2335 address" and a set of non-overlapping "chunks" associated with the 2336 anchor address.</para> 2337 </listitem> 2338 <listitem> 2339 <para>Typically a pool's anchor address is the address of a 2340 book-keeping "header" structure.</para> 2341 </listitem> 2342 <listitem> 2343 <para>Typically the pool's chunks are drawn from a contiguous 2344 "superblock" acquired through the system 2345 <function>malloc</function> or 2346 <function>mmap</function>.</para> 2347 </listitem> 2348 2349</itemizedlist> 2350 2351<para>Keep in mind that the last two points above say "typically": the 2352Valgrind mempool client request API is intentionally vague about the 2353exact structure of a mempool. There is no specific mention made of 2354headers or superblocks. Nevertheless, the following picture may help 2355elucidate the intention of the terms in the API:</para> 2356 2357<programlisting><![CDATA[ 2358 "pool" 2359 (anchor address) 2360 | 2361 v 2362 +--------+---+ 2363 | header | o | 2364 +--------+-|-+ 2365 | 2366 v superblock 2367 +------+---+--------------+---+------------------+ 2368 | |rzB| allocation |rzB| | 2369 +------+---+--------------+---+------------------+ 2370 ^ ^ 2371 | | 2372 "addr" "addr"+"size" 2373]]></programlisting> 2374 2375<para> 2376Note that the header and the superblock may be contiguous or 2377discontiguous, and there may be multiple superblocks associated with a 2378single header; such variations are opaque to Memcheck. The API 2379only requires that your allocation scheme can present sensible values 2380of "pool", "addr" and "size".</para> 2381 2382<para> 2383Typically, before making client requests related to mempools, a client 2384program will have allocated such a header and superblock for their 2385mempool, and marked the superblock NOACCESS using the 2386<varname>VALGRIND_MAKE_MEM_NOACCESS</varname> client request.</para> 2387 2388<para> 2389When dealing with mempools, the goal is to maintain a particular 2390invariant condition: that Memcheck believes the unallocated portions 2391of the pool's superblock (including redzones) are NOACCESS. To 2392maintain this invariant, the client program must ensure that the 2393superblock starts out in that state; Memcheck cannot make it so, since 2394Memcheck never explicitly learns about the superblock of a pool, only 2395the allocated chunks within the pool.</para> 2396 2397<para> 2398Once the header and superblock for a pool are established and properly 2399marked, there are a number of client requests programs can use to 2400inform Memcheck about changes to the state of a mempool:</para> 2401 2402<itemizedlist> 2403 2404 <listitem> 2405 <para> 2406 <varname>VALGRIND_CREATE_MEMPOOL(pool, rzB, is_zeroed)</varname>: 2407 This request registers the address <varname>pool</varname> as the anchor 2408 address for a memory pool. It also provides a size 2409 <varname>rzB</varname>, specifying how large the redzones placed around 2410 chunks allocated from the pool should be. Finally, it provides an 2411 <varname>is_zeroed</varname> argument that specifies whether the pool's 2412 chunks are zeroed (more precisely: defined) when allocated. 2413 </para> 2414 <para> 2415 Upon completion of this request, no chunks are associated with the 2416 pool. The request simply tells Memcheck that the pool exists, so that 2417 subsequent calls can refer to it as a pool. 2418 </para> 2419 </listitem> 2420 2421 <listitem> 2422 <!-- Note: the below is mostly a copy of valgrind.h. Keep in sync! --> 2423 <para> 2424 <varname>VALGRIND_CREATE_MEMPOOL_EXT(pool, rzB, is_zeroed, flags)</varname>: 2425 Create a memory pool with some flags (that can 2426 be OR-ed together) specifying extended behaviour. When flags is 2427 zero, the behaviour is identical to 2428 <varname>VALGRIND_CREATE_MEMPOOL</varname>.</para> 2429 <itemizedlist> 2430 <listitem> 2431 <para> The flag <varname>VALGRIND_MEMPOOL_METAPOOL</varname> 2432 specifies that the pieces of memory associated with the pool 2433 using <varname>VALGRIND_MEMPOOL_ALLOC</varname> will be used 2434 by the application as superblocks to dole out MALLOC_LIKE 2435 blocks using <varname>VALGRIND_MALLOCLIKE_BLOCK</varname>. 2436 In other words, a meta pool is a "2 levels" pool : first 2437 level is the blocks described 2438 by <varname>VALGRIND_MEMPOOL_ALLOC</varname>. The second 2439 level blocks are described 2440 using <varname>VALGRIND_MALLOCLIKE_BLOCK</varname>. Note 2441 that the association between the pool and the second level 2442 blocks is implicit : second level blocks will be located 2443 inside first level blocks. It is necessary to use 2444 the <varname>VALGRIND_MEMPOOL_METAPOOL</varname> flag for 2445 such 2 levels pools, as otherwise valgrind will detect 2446 overlapping memory blocks, and will abort execution 2447 (e.g. during leak search). 2448 </para> 2449 </listitem> 2450 <listitem> 2451 <para> 2452 <varname>VALGRIND_MEMPOOL_AUTO_FREE</varname>. Such a meta 2453 pool can also be marked as an 'auto free' pool using the 2454 flag <varname>VALGRIND_MEMPOOL_AUTO_FREE</varname>, which 2455 must be OR-ed together with 2456 the <varname>VALGRIND_MEMPOOL_METAPOOL</varname>. For an 2457 'auto free' pool, <varname>VALGRIND_MEMPOOL_FREE</varname> 2458 will automatically free the second level blocks that are 2459 contained inside the first level block freed 2460 with <varname>VALGRIND_MEMPOOL_FREE</varname>. In other 2461 words, calling <varname>VALGRIND_MEMPOOL_FREE</varname> will 2462 cause implicit calls 2463 to <varname>VALGRIND_FREELIKE_BLOCK</varname> for all the 2464 second level blocks included in the first level block. 2465 Note: it is an error to use 2466 the <varname>VALGRIND_MEMPOOL_AUTO_FREE</varname> flag 2467 without the 2468 <varname>VALGRIND_MEMPOOL_METAPOOL</varname> flag. 2469 </para> 2470 </listitem> 2471 </itemizedlist> 2472 </listitem> 2473 2474 <listitem> 2475 <para><varname>VALGRIND_DESTROY_MEMPOOL(pool)</varname>: 2476 This request tells Memcheck that a pool is being torn down. Memcheck 2477 then removes all records of chunks associated with the pool, as well 2478 as its record of the pool's existence. While destroying its records of 2479 a mempool, Memcheck resets the redzones of any live chunks in the pool 2480 to NOACCESS. 2481 </para> 2482 </listitem> 2483 2484 <listitem> 2485 <para><varname>VALGRIND_MEMPOOL_ALLOC(pool, addr, size)</varname>: 2486 This request informs Memcheck that a <varname>size</varname>-byte chunk 2487 has been allocated at <varname>addr</varname>, and associates the chunk with the 2488 specified 2489 <varname>pool</varname>. If the pool was created with nonzero 2490 <varname>rzB</varname> redzones, Memcheck will mark the 2491 <varname>rzB</varname> bytes before and after the chunk as NOACCESS. If 2492 the pool was created with the <varname>is_zeroed</varname> argument set, 2493 Memcheck will mark the chunk as DEFINED, otherwise Memcheck will mark 2494 the chunk as UNDEFINED. 2495 </para> 2496 </listitem> 2497 2498 <listitem> 2499 <para><varname>VALGRIND_MEMPOOL_FREE(pool, addr)</varname>: 2500 This request informs Memcheck that the chunk at <varname>addr</varname> 2501 should no longer be considered allocated. Memcheck will mark the chunk 2502 associated with <varname>addr</varname> as NOACCESS, and delete its 2503 record of the chunk's existence. 2504 </para> 2505 </listitem> 2506 2507 <listitem> 2508 <para><varname>VALGRIND_MEMPOOL_TRIM(pool, addr, size)</varname>: 2509 This request trims the chunks associated with <varname>pool</varname>. 2510 The request only operates on chunks associated with 2511 <varname>pool</varname>. Trimming is formally defined as:</para> 2512 <itemizedlist> 2513 <listitem> 2514 <para> All chunks entirely inside the range 2515 <varname>addr..(addr+size-1)</varname> are preserved.</para> 2516 </listitem> 2517 <listitem> 2518 <para>All chunks entirely outside the range 2519 <varname>addr..(addr+size-1)</varname> are discarded, as though 2520 <varname>VALGRIND_MEMPOOL_FREE</varname> was called on them. </para> 2521 </listitem> 2522 <listitem> 2523 <para>All other chunks must intersect with the range 2524 <varname>addr..(addr+size-1)</varname>; areas outside the 2525 intersection are marked as NOACCESS, as though they had been 2526 independently freed with 2527 <varname>VALGRIND_MEMPOOL_FREE</varname>.</para> 2528 </listitem> 2529 </itemizedlist> 2530 <para>This is a somewhat rare request, but can be useful in 2531 implementing the type of mass-free operations common in custom 2532 LIFO allocators.</para> 2533 </listitem> 2534 2535 <listitem> 2536 <para><varname>VALGRIND_MOVE_MEMPOOL(poolA, poolB)</varname>: This 2537 request informs Memcheck that the pool previously anchored at 2538 address <varname>poolA</varname> has moved to anchor address 2539 <varname>poolB</varname>. This is a rare request, typically only needed 2540 if you <function>realloc</function> the header of a mempool.</para> 2541 <para>No memory-status bits are altered by this request.</para> 2542 </listitem> 2543 2544 <listitem> 2545 <para> 2546 <varname>VALGRIND_MEMPOOL_CHANGE(pool, addrA, addrB, 2547 size)</varname>: This request informs Memcheck that the chunk 2548 previously allocated at address <varname>addrA</varname> within 2549 <varname>pool</varname> has been moved and/or resized, and should be 2550 changed to cover the region <varname>addrB..(addrB+size-1)</varname>. This 2551 is a rare request, typically only needed if you 2552 <function>realloc</function> a superblock or wish to extend a chunk 2553 without changing its memory-status bits. 2554 </para> 2555 <para>No memory-status bits are altered by this request. 2556 </para> 2557 </listitem> 2558 2559 <listitem> 2560 <para><varname>VALGRIND_MEMPOOL_EXISTS(pool)</varname>: 2561 This request informs the caller whether or not Memcheck is currently 2562 tracking a mempool at anchor address <varname>pool</varname>. It 2563 evaluates to 1 when there is a mempool associated with that address, 0 2564 otherwise. This is a rare request, only useful in circumstances when 2565 client code might have lost track of the set of active mempools. 2566 </para> 2567 </listitem> 2568 2569</itemizedlist> 2570 2571</sect1> 2572 2573 2574 2575 2576 2577 2578 2579<sect1 id="mc-manual.mpiwrap" xreflabel="MPI Wrappers"> 2580<title>Debugging MPI Parallel Programs with Valgrind</title> 2581 2582<para>Memcheck supports debugging of distributed-memory applications 2583which use the MPI message passing standard. This support consists of a 2584library of wrapper functions for the 2585<computeroutput>PMPI_*</computeroutput> interface. When incorporated 2586into the application's address space, either by direct linking or by 2587<computeroutput>LD_PRELOAD</computeroutput>, the wrappers intercept 2588calls to <computeroutput>PMPI_Send</computeroutput>, 2589<computeroutput>PMPI_Recv</computeroutput>, etc. They then 2590use client requests to inform Memcheck of memory state changes caused 2591by the function being wrapped. This reduces the number of false 2592positives that Memcheck otherwise typically reports for MPI 2593applications.</para> 2594 2595<para>The wrappers also take the opportunity to carefully check 2596size and definedness of buffers passed as arguments to MPI functions, hence 2597detecting errors such as passing undefined data to 2598<computeroutput>PMPI_Send</computeroutput>, or receiving data into a 2599buffer which is too small.</para> 2600 2601<para>Unlike most of the rest of Valgrind, the wrapper library is subject to a 2602BSD-style license, so you can link it into any code base you like. 2603See the top of <computeroutput>mpi/libmpiwrap.c</computeroutput> 2604for license details.</para> 2605 2606 2607<sect2 id="mc-manual.mpiwrap.build" xreflabel="Building MPI Wrappers"> 2608<title>Building and installing the wrappers</title> 2609 2610<para> The wrapper library will be built automatically if possible. 2611Valgrind's configure script will look for a suitable 2612<computeroutput>mpicc</computeroutput> to build it with. This must be 2613the same <computeroutput>mpicc</computeroutput> you use to build the 2614MPI application you want to debug. By default, Valgrind tries 2615<computeroutput>mpicc</computeroutput>, but you can specify a 2616different one by using the configure-time option 2617<option>--with-mpicc</option>. Currently the 2618wrappers are only buildable with 2619<computeroutput>mpicc</computeroutput>s which are based on GNU 2620GCC or Intel's C++ Compiler.</para> 2621 2622<para>Check that the configure script prints a line like this:</para> 2623 2624<programlisting><![CDATA[ 2625checking for usable MPI2-compliant mpicc and mpi.h... yes, mpicc 2626]]></programlisting> 2627 2628<para>If it says <computeroutput>... no</computeroutput>, your 2629<computeroutput>mpicc</computeroutput> has failed to compile and link 2630a test MPI2 program.</para> 2631 2632<para>If the configure test succeeds, continue in the usual way with 2633<computeroutput>make</computeroutput> and <computeroutput>make 2634install</computeroutput>. The final install tree should then contain 2635<computeroutput>libmpiwrap-<platform>.so</computeroutput>. 2636</para> 2637 2638<para>Compile up a test MPI program (eg, MPI hello-world) and try 2639this:</para> 2640 2641<programlisting><![CDATA[ 2642LD_PRELOAD=$prefix/lib/valgrind/libmpiwrap-<platform>.so \ 2643 mpirun [args] $prefix/bin/valgrind ./hello 2644]]></programlisting> 2645 2646<para>You should see something similar to the following</para> 2647 2648<programlisting><![CDATA[ 2649valgrind MPI wrappers 31901: Active for pid 31901 2650valgrind MPI wrappers 31901: Try MPIWRAP_DEBUG=help for possible options 2651]]></programlisting> 2652 2653<para>repeated for every process in the group. If you do not see 2654these, there is an build/installation problem of some kind.</para> 2655 2656<para> The MPI functions to be wrapped are assumed to be in an ELF 2657shared object with soname matching 2658<computeroutput>libmpi.so*</computeroutput>. This is known to be 2659correct at least for Open MPI and Quadrics MPI, and can easily be 2660changed if required.</para> 2661</sect2> 2662 2663 2664<sect2 id="mc-manual.mpiwrap.gettingstarted" 2665 xreflabel="Getting started with MPI Wrappers"> 2666<title>Getting started</title> 2667 2668<para>Compile your MPI application as usual, taking care to link it 2669using the same <computeroutput>mpicc</computeroutput> that your 2670Valgrind build was configured with.</para> 2671 2672<para> 2673Use the following basic scheme to run your application on Valgrind with 2674the wrappers engaged:</para> 2675 2676<programlisting><![CDATA[ 2677MPIWRAP_DEBUG=[wrapper-args] \ 2678 LD_PRELOAD=$prefix/lib/valgrind/libmpiwrap-<platform>.so \ 2679 mpirun [mpirun-args] \ 2680 $prefix/bin/valgrind [valgrind-args] \ 2681 [application] [app-args] 2682]]></programlisting> 2683 2684<para>As an alternative to 2685<computeroutput>LD_PRELOAD</computeroutput>ing 2686<computeroutput>libmpiwrap-<platform>.so</computeroutput>, you can 2687simply link it to your application if desired. This should not disturb 2688native behaviour of your application in any way.</para> 2689</sect2> 2690 2691 2692<sect2 id="mc-manual.mpiwrap.controlling" 2693 xreflabel="Controlling the MPI Wrappers"> 2694<title>Controlling the wrapper library</title> 2695 2696<para>Environment variable 2697<computeroutput>MPIWRAP_DEBUG</computeroutput> is consulted at 2698startup. The default behaviour is to print a starting banner</para> 2699 2700<programlisting><![CDATA[ 2701valgrind MPI wrappers 16386: Active for pid 16386 2702valgrind MPI wrappers 16386: Try MPIWRAP_DEBUG=help for possible options 2703]]></programlisting> 2704 2705<para> and then be relatively quiet.</para> 2706 2707<para>You can give a list of comma-separated options in 2708<computeroutput>MPIWRAP_DEBUG</computeroutput>. These are</para> 2709 2710<itemizedlist> 2711 <listitem> 2712 <para><computeroutput>verbose</computeroutput>: 2713 show entries/exits of all wrappers. Also show extra 2714 debugging info, such as the status of outstanding 2715 <computeroutput>MPI_Request</computeroutput>s resulting 2716 from uncompleted <computeroutput>MPI_Irecv</computeroutput>s.</para> 2717 </listitem> 2718 <listitem> 2719 <para><computeroutput>quiet</computeroutput>: 2720 opposite of <computeroutput>verbose</computeroutput>, only print 2721 anything when the wrappers want 2722 to report a detected programming error, or in case of catastrophic 2723 failure of the wrappers.</para> 2724 </listitem> 2725 <listitem> 2726 <para><computeroutput>warn</computeroutput>: 2727 by default, functions which lack proper wrappers 2728 are not commented on, just silently 2729 ignored. This causes a warning to be printed for each unwrapped 2730 function used, up to a maximum of three warnings per function.</para> 2731 </listitem> 2732 <listitem> 2733 <para><computeroutput>strict</computeroutput>: 2734 print an error message and abort the program if 2735 a function lacking a wrapper is used.</para> 2736 </listitem> 2737</itemizedlist> 2738 2739<para> If you want to use Valgrind's XML output facility 2740(<option>--xml=yes</option>), you should pass 2741<computeroutput>quiet</computeroutput> in 2742<computeroutput>MPIWRAP_DEBUG</computeroutput> so as to get rid of any 2743extraneous printing from the wrappers.</para> 2744 2745</sect2> 2746 2747 2748<sect2 id="mc-manual.mpiwrap.limitations.functions" 2749 xreflabel="Functions: Abilities and Limitations"> 2750<title>Functions</title> 2751 2752<para>All MPI2 functions except 2753<computeroutput>MPI_Wtick</computeroutput>, 2754<computeroutput>MPI_Wtime</computeroutput> and 2755<computeroutput>MPI_Pcontrol</computeroutput> have wrappers. The 2756first two are not wrapped because they return a 2757<computeroutput>double</computeroutput>, which Valgrind's 2758function-wrap mechanism cannot handle (but it could easily be 2759extended to do so). <computeroutput>MPI_Pcontrol</computeroutput> cannot be 2760wrapped as it has variable arity: 2761<computeroutput>int MPI_Pcontrol(const int level, ...)</computeroutput></para> 2762 2763<para>Most functions are wrapped with a default wrapper which does 2764nothing except complain or abort if it is called, depending on 2765settings in <computeroutput>MPIWRAP_DEBUG</computeroutput> listed 2766above. The following functions have "real", do-something-useful 2767wrappers:</para> 2768 2769<programlisting><![CDATA[ 2770PMPI_Send PMPI_Bsend PMPI_Ssend PMPI_Rsend 2771 2772PMPI_Recv PMPI_Get_count 2773 2774PMPI_Isend PMPI_Ibsend PMPI_Issend PMPI_Irsend 2775 2776PMPI_Irecv 2777PMPI_Wait PMPI_Waitall 2778PMPI_Test PMPI_Testall 2779 2780PMPI_Iprobe PMPI_Probe 2781 2782PMPI_Cancel 2783 2784PMPI_Sendrecv 2785 2786PMPI_Type_commit PMPI_Type_free 2787 2788PMPI_Pack PMPI_Unpack 2789 2790PMPI_Bcast PMPI_Gather PMPI_Scatter PMPI_Alltoall 2791PMPI_Reduce PMPI_Allreduce PMPI_Op_create 2792 2793PMPI_Comm_create PMPI_Comm_dup PMPI_Comm_free PMPI_Comm_rank PMPI_Comm_size 2794 2795PMPI_Error_string 2796PMPI_Init PMPI_Initialized PMPI_Finalize 2797]]></programlisting> 2798 2799<para> A few functions such as 2800<computeroutput>PMPI_Address</computeroutput> are listed as 2801<computeroutput>HAS_NO_WRAPPER</computeroutput>. They have no wrapper 2802at all as there is nothing worth checking, and giving a no-op wrapper 2803would reduce performance for no reason.</para> 2804 2805<para> Note that the wrapper library itself can itself generate large 2806numbers of calls to the MPI implementation, especially when walking 2807complex types. The most common functions called are 2808<computeroutput>PMPI_Extent</computeroutput>, 2809<computeroutput>PMPI_Type_get_envelope</computeroutput>, 2810<computeroutput>PMPI_Type_get_contents</computeroutput>, and 2811<computeroutput>PMPI_Type_free</computeroutput>. </para> 2812</sect2> 2813 2814<sect2 id="mc-manual.mpiwrap.limitations.types" 2815 xreflabel="Types: Abilities and Limitations"> 2816<title>Types</title> 2817 2818<para> MPI-1.1 structured types are supported, and walked exactly. 2819The currently supported combiners are 2820<computeroutput>MPI_COMBINER_NAMED</computeroutput>, 2821<computeroutput>MPI_COMBINER_CONTIGUOUS</computeroutput>, 2822<computeroutput>MPI_COMBINER_VECTOR</computeroutput>, 2823<computeroutput>MPI_COMBINER_HVECTOR</computeroutput> 2824<computeroutput>MPI_COMBINER_INDEXED</computeroutput>, 2825<computeroutput>MPI_COMBINER_HINDEXED</computeroutput> and 2826<computeroutput>MPI_COMBINER_STRUCT</computeroutput>. This should 2827cover all MPI-1.1 types. The mechanism (function 2828<computeroutput>walk_type</computeroutput>) should extend easily to 2829cover MPI2 combiners.</para> 2830 2831<para>MPI defines some named structured types 2832(<computeroutput>MPI_FLOAT_INT</computeroutput>, 2833<computeroutput>MPI_DOUBLE_INT</computeroutput>, 2834<computeroutput>MPI_LONG_INT</computeroutput>, 2835<computeroutput>MPI_2INT</computeroutput>, 2836<computeroutput>MPI_SHORT_INT</computeroutput>, 2837<computeroutput>MPI_LONG_DOUBLE_INT</computeroutput>) which are pairs 2838of some basic type and a C <computeroutput>int</computeroutput>. 2839Unfortunately the MPI specification makes it impossible to look inside 2840these types and see where the fields are. Therefore these wrappers 2841assume the types are laid out as <computeroutput>struct { float val; 2842int loc; }</computeroutput> (for 2843<computeroutput>MPI_FLOAT_INT</computeroutput>), etc, and act 2844accordingly. This appears to be correct at least for Open MPI 1.0.2 2845and for Quadrics MPI.</para> 2846 2847<para>If <computeroutput>strict</computeroutput> is an option specified 2848in <computeroutput>MPIWRAP_DEBUG</computeroutput>, the application 2849will abort if an unhandled type is encountered. Otherwise, the 2850application will print a warning message and continue.</para> 2851 2852<para>Some effort is made to mark/check memory ranges corresponding to 2853arrays of values in a single pass. This is important for performance 2854since asking Valgrind to mark/check any range, no matter how small, 2855carries quite a large constant cost. This optimisation is applied to 2856arrays of primitive types (<computeroutput>double</computeroutput>, 2857<computeroutput>float</computeroutput>, 2858<computeroutput>int</computeroutput>, 2859<computeroutput>long</computeroutput>, <computeroutput>long 2860long</computeroutput>, <computeroutput>short</computeroutput>, 2861<computeroutput>char</computeroutput>, and <computeroutput>long 2862double</computeroutput> on platforms where <computeroutput>sizeof(long 2863double) == 8</computeroutput>). For arrays of all other types, the 2864wrappers handle each element individually and so there can be a very 2865large performance cost.</para> 2866 2867</sect2> 2868 2869 2870<sect2 id="mc-manual.mpiwrap.writingwrappers" 2871 xreflabel="Writing new MPI Wrappers"> 2872<title>Writing new wrappers</title> 2873 2874<para> 2875For the most part the wrappers are straightforward. The only 2876significant complexity arises with nonblocking receives.</para> 2877 2878<para>The issue is that <computeroutput>MPI_Irecv</computeroutput> 2879states the recv buffer and returns immediately, giving a handle 2880(<computeroutput>MPI_Request</computeroutput>) for the transaction. 2881Later the user will have to poll for completion with 2882<computeroutput>MPI_Wait</computeroutput> etc, and when the 2883transaction completes successfully, the wrappers have to paint the 2884recv buffer. But the recv buffer details are not presented to 2885<computeroutput>MPI_Wait</computeroutput> -- only the handle is. The 2886library therefore maintains a shadow table which associates 2887uncompleted <computeroutput>MPI_Request</computeroutput>s with the 2888corresponding buffer address/count/type. When an operation completes, 2889the table is searched for the associated address/count/type info, and 2890memory is marked accordingly.</para> 2891 2892<para>Access to the table is guarded by a (POSIX pthreads) lock, so as 2893to make the library thread-safe.</para> 2894 2895<para>The table is allocated with 2896<computeroutput>malloc</computeroutput> and never 2897<computeroutput>free</computeroutput>d, so it will show up in leak 2898checks.</para> 2899 2900<para>Writing new wrappers should be fairly easy. The source file is 2901<computeroutput>mpi/libmpiwrap.c</computeroutput>. If possible, 2902find an existing wrapper for a function of similar behaviour to the 2903one you want to wrap, and use it as a starting point. The wrappers 2904are organised in sections in the same order as the MPI 1.1 spec, to 2905aid navigation. When adding a wrapper, remember to comment out the 2906definition of the default wrapper in the long list of defaults at the 2907bottom of the file (do not remove it, just comment it out).</para> 2908</sect2> 2909 2910<sect2 id="mc-manual.mpiwrap.whattoexpect" 2911 xreflabel="What to expect with MPI Wrappers"> 2912<title>What to expect when using the wrappers</title> 2913 2914<para>The wrappers should reduce Memcheck's false-error rate on MPI 2915applications. Because the wrapping is done at the MPI interface, 2916there will still potentially be a large number of errors reported in 2917the MPI implementation below the interface. The best you can do is 2918try to suppress them.</para> 2919 2920<para>You may also find that the input-side (buffer 2921length/definedness) checks find errors in your MPI use, for example 2922passing too short a buffer to 2923<computeroutput>MPI_Recv</computeroutput>.</para> 2924 2925<para>Functions which are not wrapped may increase the false 2926error rate. A possible approach is to run with 2927<computeroutput>MPI_DEBUG</computeroutput> containing 2928<computeroutput>warn</computeroutput>. This will show you functions 2929which lack proper wrappers but which are nevertheless used. You can 2930then write wrappers for them. 2931</para> 2932 2933<para>A known source of potential false errors are the 2934<computeroutput>PMPI_Reduce</computeroutput> family of functions, when 2935using a custom (user-defined) reduction function. In a reduction 2936operation, each node notionally sends data to a "central point" which 2937uses the specified reduction function to merge the data items into a 2938single item. Hence, in general, data is passed between nodes and fed 2939to the reduction function, but the wrapper library cannot mark the 2940transferred data as initialised before it is handed to the reduction 2941function, because all that happens "inside" the 2942<computeroutput>PMPI_Reduce</computeroutput> call. As a result you 2943may see false positives reported in your reduction function.</para> 2944 2945</sect2> 2946 2947</sect1> 2948 2949 2950 2951 2952 2953</chapter> 2954