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 [ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]> 5 6 7 <chapter id="manual-core" xreflabel="Valgrind's core"> 8 <title>Using and understanding the Valgrind core</title> 9 10 <para>This chapter describes the Valgrind core services, command-line 11 options and behaviours. That means it is relevant regardless of what 12 particular tool you are using. The information should be sufficient for you 13 to make effective day-to-day use of Valgrind. Advanced topics related to 14 the Valgrind core are described in <xref linkend="manual-core-adv"/>. 15 </para> 16 17 <para> 18 A point of terminology: most references to "Valgrind" in this chapter 19 refer to the Valgrind core services. </para> 20 21 22 23 <sect1 id="manual-core.whatdoes" 24 xreflabel="What Valgrind does with your program"> 25 <title>What Valgrind does with your program</title> 26 27 <para>Valgrind is designed to be as non-intrusive as possible. It works 28 directly with existing executables. You don't need to recompile, relink, 29 or otherwise modify the program to be checked.</para> 30 31 <para>You invoke Valgrind like this:</para> 32 <programlisting><![CDATA[ 33 valgrind [valgrind-options] your-prog [your-prog-options]]]></programlisting> 34 35 <para>The most important option is <option>--tool</option> which dictates 36 which Valgrind tool to run. For example, if want to run the command 37 <computeroutput>ls -l</computeroutput> using the memory-checking tool 38 Memcheck, issue this command:</para> 39 40 <programlisting><![CDATA[ 41 valgrind --tool=memcheck ls -l]]></programlisting> 42 43 <para>However, Memcheck is the default, so if you want to use it you can 44 omit the <option>--tool</option> option.</para> 45 46 <para>Regardless of which tool is in use, Valgrind takes control of your 47 program before it starts. Debugging information is read from the 48 executable and associated libraries, so that error messages and other 49 outputs can be phrased in terms of source code locations, when 50 appropriate.</para> 51 52 <para>Your program is then run on a synthetic CPU provided by the 53 Valgrind core. As new code is executed for the first time, the core 54 hands the code to the selected tool. The tool adds its own 55 instrumentation code to this and hands the result back to the core, 56 which coordinates the continued execution of this instrumented 57 code.</para> 58 59 <para>The amount of instrumentation code added varies widely between 60 tools. At one end of the scale, Memcheck adds code to check every 61 memory access and every value computed, 62 making it run 10-50 times slower than natively. 63 At the other end of the spectrum, the minimal tool, called Nulgrind, 64 adds no instrumentation at all and causes in total "only" about a 4 times 65 slowdown.</para> 66 67 <para>Valgrind simulates every single instruction your program executes. 68 Because of this, the active tool checks, or profiles, not only the code 69 in your application but also in all supporting dynamically-linked libraries, 70 including the C library, graphical libraries, and so on.</para> 71 72 <para>If you're using an error-detection tool, Valgrind may 73 detect errors in system libraries, for example the GNU C or X11 74 libraries, which you have to use. You might not be interested in these 75 errors, since you probably have no control over that code. Therefore, 76 Valgrind allows you to selectively suppress errors, by recording them in 77 a suppressions file which is read when Valgrind starts up. The build 78 mechanism selects default suppressions which give reasonable 79 behaviour for the OS and libraries detected on your machine. 80 To make it easier to write suppressions, you can use the 81 <option>--gen-suppressions=yes</option> option. This tells Valgrind to 82 print out a suppression for each reported error, which you can then 83 copy into a suppressions file.</para> 84 85 <para>Different error-checking tools report different kinds of errors. 86 The suppression mechanism therefore allows you to say which tool or 87 tool(s) each suppression applies to.</para> 88 89 </sect1> 90 91 92 <sect1 id="manual-core.started" xreflabel="Getting started"> 93 <title>Getting started</title> 94 95 <para>First off, consider whether it might be beneficial to recompile 96 your application and supporting libraries with debugging info enabled 97 (the <option>-g</option> option). Without debugging info, the best 98 Valgrind tools will be able to do is guess which function a particular 99 piece of code belongs to, which makes both error messages and profiling 100 output nearly useless. With <option>-g</option>, you'll get 101 messages which point directly to the relevant source code lines.</para> 102 103 <para>Another option you might like to consider, if you are working with 104 C++, is <option>-fno-inline</option>. That makes it easier to see the 105 function-call chain, which can help reduce confusion when navigating 106 around large C++ apps. For example, debugging 107 OpenOffice.org with Memcheck is a bit easier when using this option. You 108 don't have to do this, but doing so helps Valgrind produce more accurate 109 and less confusing error reports. Chances are you're set up like this 110 already, if you intended to debug your program with GNU GDB, or some 111 other debugger. Alternatively, the Valgrind option 112 <option>--read-inline-info=yes</option> instructs Valgrind to read 113 the debug information describing inlining information. With this, 114 function call chain will be properly shown, even when your application 115 is compiled with inlining. </para> 116 117 <para>If you are planning to use Memcheck: On rare 118 occasions, compiler optimisations (at <option>-O2</option> 119 and above, and sometimes <option>-O1</option>) have been 120 observed to generate code which fools Memcheck into wrongly reporting 121 uninitialised value errors, or missing uninitialised value errors. We have 122 looked in detail into fixing this, and unfortunately the result is that 123 doing so would give a further significant slowdown in what is already a slow 124 tool. So the best solution is to turn off optimisation altogether. Since 125 this often makes things unmanageably slow, a reasonable compromise is to use 126 <option>-O</option>. This gets you the majority of the 127 benefits of higher optimisation levels whilst keeping relatively small the 128 chances of false positives or false negatives from Memcheck. Also, you 129 should compile your code with <option>-Wall</option> because 130 it can identify some or all of the problems that Valgrind can miss at the 131 higher optimisation levels. (Using <option>-Wall</option> 132 is also a good idea in general.) All other tools (as far as we know) are 133 unaffected by optimisation level, and for profiling tools like Cachegrind it 134 is better to compile your program at its normal optimisation level.</para> 135 136 <para>Valgrind understands the DWARF2/3/4 formats used by GCC 3.1 and 137 later. The reader for "stabs" debugging format (used by GCC versions 138 prior to 3.1) has been disabled in Valgrind 3.9.0.</para> 139 140 <para>When you're ready to roll, run Valgrind as described above. 141 Note that you should run the real 142 (machine-code) executable here. If your application is started by, for 143 example, a shell or Perl script, you'll need to modify it to invoke 144 Valgrind on the real executables. Running such scripts directly under 145 Valgrind will result in you getting error reports pertaining to 146 <filename>/bin/sh</filename>, 147 <filename>/usr/bin/perl</filename>, or whatever interpreter 148 you're using. This may not be what you want and can be confusing. You 149 can force the issue by giving the option 150 <option>--trace-children=yes</option>, but confusion is still 151 likely.</para> 152 153 </sect1> 154 155 156 <!-- Referenced from both the manual and manpage --> 157 <sect1 id="&vg-comment-id;" xreflabel="&vg-comment-label;"> 158 <title>The Commentary</title> 159 160 <para>Valgrind tools write a commentary, a stream of text, detailing 161 error reports and other significant events. All lines in the commentary 162 have following form: 163 164 <programlisting><![CDATA[ 165 ==12345== some-message-from-Valgrind]]></programlisting> 166 </para> 167 168 <para>The <computeroutput>12345</computeroutput> is the process ID. 169 This scheme makes it easy to distinguish program output from Valgrind 170 commentary, and also easy to differentiate commentaries from different 171 processes which have become merged together, for whatever reason.</para> 172 173 <para>By default, Valgrind tools write only essential messages to the 174 commentary, so as to avoid flooding you with information of secondary 175 importance. If you want more information about what is happening, 176 re-run, passing the <option>-v</option> option to Valgrind. A second 177 <option>-v</option> gives yet more detail. 178 </para> 179 180 <para>You can direct the commentary to three different places:</para> 181 182 <orderedlist> 183 184 <listitem id="manual-core.out2fd" xreflabel="Directing output to fd"> 185 <para>The default: send it to a file descriptor, which is by default 186 2 (stderr). So, if you give the core no options, it will write 187 commentary to the standard error stream. If you want to send it to 188 some other file descriptor, for example number 9, you can specify 189 <option>--log-fd=9</option>.</para> 190 191 <para>This is the simplest and most common arrangement, but can 192 cause problems when Valgrinding entire trees of processes which 193 expect specific file descriptors, particularly stdin/stdout/stderr, 194 to be available for their own use.</para> 195 </listitem> 196 197 <listitem id="manual-core.out2file" 198 xreflabel="Directing output to file"> <para>A less intrusive 199 option is to write the commentary to a file, which you specify by 200 <option>--log-file=filename</option>. There are special format 201 specifiers that can be used to use a process ID or an environment 202 variable name in the log file name. These are useful/necessary if your 203 program invokes multiple processes (especially for MPI programs). 204 See the <link linkend="manual-core.basicopts">basic options section</link> 205 for more details.</para> 206 </listitem> 207 208 <listitem id="manual-core.out2socket" 209 xreflabel="Directing output to network socket"> <para>The 210 least intrusive option is to send the commentary to a network 211 socket. The socket is specified as an IP address and port number 212 pair, like this: <option>--log-socket=192.168.0.1:12345</option> if 213 you want to send the output to host IP 192.168.0.1 port 12345 214 (note: we 215 have no idea if 12345 is a port of pre-existing significance). You 216 can also omit the port number: 217 <option>--log-socket=192.168.0.1</option>, in which case a default 218 port of 1500 is used. This default is defined by the constant 219 <computeroutput>VG_CLO_DEFAULT_LOGPORT</computeroutput> in the 220 sources.</para> 221 222 <para>Note, unfortunately, that you have to use an IP address here, 223 rather than a hostname.</para> 224 225 <para>Writing to a network socket is pointless if you don't 226 have something listening at the other end. We provide a simple 227 listener program, 228 <computeroutput>valgrind-listener</computeroutput>, which accepts 229 connections on the specified port and copies whatever it is sent to 230 stdout. Probably someone will tell us this is a horrible security 231 risk. It seems likely that people will write more sophisticated 232 listeners in the fullness of time.</para> 233 234 <para><computeroutput>valgrind-listener</computeroutput> can accept 235 simultaneous connections from up to 50 Valgrinded processes. In front 236 of each line of output it prints the current number of active 237 connections in round brackets.</para> 238 239 <para><computeroutput>valgrind-listener</computeroutput> accepts three 240 command-line options:</para> 241 <!-- start of xi:include in the manpage --> 242 <variablelist id="listener.opts.list"> 243 <varlistentry> 244 <term><option>-e --exit-at-zero</option></term> 245 <listitem> 246 <para>When the number of connected processes falls back to zero, 247 exit. Without this, it will run forever, that is, until you 248 send it Control-C.</para> 249 </listitem> 250 </varlistentry> 251 <varlistentry> 252 <term><option>--max-connect=INTEGER</option></term> 253 <listitem> 254 <para>By default, the listener can connect to up to 50 processes. 255 Occasionally, that number is too small. Use this option to 256 provide a different limit. E.g. 257 <computeroutput>--max-connect=100</computeroutput>. 258 </para> 259 </listitem> 260 </varlistentry> 261 <varlistentry> 262 <term><option>portnumber</option></term> 263 <listitem> 264 <para>Changes the port it listens on from the default (1500). 265 The specified port must be in the range 1024 to 65535. 266 The same restriction applies to port numbers specified by a 267 <option>--log-socket</option> to Valgrind itself.</para> 268 </listitem> 269 </varlistentry> 270 </variablelist> 271 <!-- end of xi:include in the manpage --> 272 273 <para>If a Valgrinded process fails to connect to a listener, for 274 whatever reason (the listener isn't running, invalid or unreachable 275 host or port, etc), Valgrind switches back to writing the commentary 276 to stderr. The same goes for any process which loses an established 277 connection to a listener. In other words, killing the listener 278 doesn't kill the processes sending data to it.</para> 279 </listitem> 280 281 </orderedlist> 282 283 <para>Here is an important point about the relationship between the 284 commentary and profiling output from tools. The commentary contains a 285 mix of messages from the Valgrind core and the selected tool. If the 286 tool reports errors, it will report them to the commentary. However, if 287 the tool does profiling, the profile data will be written to a file of 288 some kind, depending on the tool, and independent of what 289 <option>--log-*</option> options are in force. The commentary is 290 intended to be a low-bandwidth, human-readable channel. Profiling data, 291 on the other hand, is usually voluminous and not meaningful without 292 further processing, which is why we have chosen this arrangement.</para> 293 294 </sect1> 295 296 297 <sect1 id="manual-core.report" xreflabel="Reporting of errors"> 298 <title>Reporting of errors</title> 299 300 <para>When an error-checking tool 301 detects something bad happening in the program, an error 302 message is written to the commentary. Here's an example from Memcheck:</para> 303 304 <programlisting><![CDATA[ 305 ==25832== Invalid read of size 4 306 ==25832== at 0x8048724: BandMatrix::ReSize(int, int, int) (bogon.cpp:45) 307 ==25832== by 0x80487AF: main (bogon.cpp:66) 308 ==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd]]></programlisting> 309 310 <para>This message says that the program did an illegal 4-byte read of 311 address 0xBFFFF74C, which, as far as Memcheck can tell, is not a valid 312 stack address, nor corresponds to any current heap blocks or recently freed 313 heap blocks. The read is happening at line 45 of 314 <filename>bogon.cpp</filename>, called from line 66 of the same file, 315 etc. For errors associated with an identified (current or freed) heap block, 316 for example reading freed memory, Valgrind reports not only the 317 location where the error happened, but also where the associated heap block 318 was allocated/freed.</para> 319 320 <para>Valgrind remembers all error reports. When an error is detected, 321 it is compared against old reports, to see if it is a duplicate. If so, 322 the error is noted, but no further commentary is emitted. This avoids 323 you being swamped with bazillions of duplicate error reports.</para> 324 325 <para>If you want to know how many times each error occurred, run with 326 the <option>-v</option> option. When execution finishes, all the 327 reports are printed out, along with, and sorted by, their occurrence 328 counts. This makes it easy to see which errors have occurred most 329 frequently.</para> 330 331 <para>Errors are reported before the associated operation actually 332 happens. For example, if you're using Memcheck and your program attempts to 333 read from address zero, Memcheck will emit a message to this effect, and 334 your program will then likely die with a segmentation fault.</para> 335 336 <para>In general, you should try and fix errors in the order that they 337 are reported. Not doing so can be confusing. For example, a program 338 which copies uninitialised values to several memory locations, and later 339 uses them, will generate several error messages, when run on Memcheck. 340 The first such error message may well give the most direct clue to the 341 root cause of the problem.</para> 342 343 <para>The process of detecting duplicate errors is quite an 344 expensive one and can become a significant performance overhead 345 if your program generates huge quantities of errors. To avoid 346 serious problems, Valgrind will simply stop collecting 347 errors after 1,000 different errors have been seen, or 10,000,000 errors 348 in total have been seen. In this situation you might as well 349 stop your program and fix it, because Valgrind won't tell you 350 anything else useful after this. Note that the 1,000/10,000,000 limits 351 apply after suppressed errors are removed. These limits are 352 defined in <filename>m_errormgr.c</filename> and can be increased 353 if necessary.</para> 354 355 <para>To avoid this cutoff you can use the 356 <option>--error-limit=no</option> option. Then Valgrind will always show 357 errors, regardless of how many there are. Use this option carefully, 358 since it may have a bad effect on performance.</para> 359 360 </sect1> 361 362 363 <sect1 id="manual-core.suppress" xreflabel="Suppressing errors"> 364 <title>Suppressing errors</title> 365 366 <para>The error-checking tools detect numerous problems in the system 367 libraries, such as the C library, 368 which come pre-installed with your OS. You can't easily fix 369 these, but you don't want to see these errors (and yes, there are many!) 370 So Valgrind reads a list of errors to suppress at startup. A default 371 suppression file is created by the 372 <computeroutput>./configure</computeroutput> script when the system is 373 built.</para> 374 375 <para>You can modify and add to the suppressions file at your leisure, 376 or, better, write your own. Multiple suppression files are allowed. 377 This is useful if part of your project contains errors you can't or 378 don't want to fix, yet you don't want to continuously be reminded of 379 them.</para> 380 381 <formalpara><title>Note:</title> <para>By far the easiest way to add 382 suppressions is to use the <option>--gen-suppressions=yes</option> option 383 described in <xref linkend="manual-core.options"/>. This generates 384 suppressions automatically. For best results, 385 though, you may want to edit the output 386 of <option>--gen-suppressions=yes</option> by hand, in which 387 case it would be advisable to read through this section. 388 </para> 389 </formalpara> 390 391 <para>Each error to be suppressed is described very specifically, to 392 minimise the possibility that a suppression-directive inadvertently 393 suppresses a bunch of similar errors which you did want to see. The 394 suppression mechanism is designed to allow precise yet flexible 395 specification of errors to suppress.</para> 396 397 <para>If you use the <option>-v</option> option, at the end of execution, 398 Valgrind prints out one line for each used suppression, giving the number of times 399 it got used, its name and the filename and line number where the suppression is 400 defined. Depending on the suppression kind, the filename and line number are optionally 401 followed by additional information (such as the number of blocks and bytes suppressed 402 by a memcheck leak suppression). Here's the suppressions used by a 403 run of <computeroutput>valgrind -v --tool=memcheck ls -l</computeroutput>:</para> 404 405 <programlisting><![CDATA[ 406 --1610-- used_suppression: 2 dl-hack3-cond-1 /usr/lib/valgrind/default.supp:1234 407 --1610-- used_suppression: 2 glibc-2.5.x-on-SUSE-10.2-(PPC)-2a /usr/lib/valgrind/default.supp:1234 408 ]]></programlisting> 409 410 <para>Multiple suppressions files are allowed. Valgrind loads suppression 411 patterns from <filename>$PREFIX/lib/valgrind/default.supp</filename> unless 412 <option>--default-suppressions=no</option> has been specified. You can 413 ask to add suppressions from additional files by specifying 414 <option>--suppressions=/path/to/file.supp</option> one or more times. 415 </para> 416 417 <para>If you want to understand more about suppressions, look at an 418 existing suppressions file whilst reading the following documentation. 419 The file <filename>glibc-2.3.supp</filename>, in the source 420 distribution, provides some good examples.</para> 421 422 <para>Each suppression has the following components:</para> 423 424 <itemizedlist> 425 426 <listitem> 427 <para>First line: its name. This merely gives a handy name to the 428 suppression, by which it is referred to in the summary of used 429 suppressions printed out when a program finishes. It's not 430 important what the name is; any identifying string will do.</para> 431 </listitem> 432 433 <listitem> 434 <para>Second line: name of the tool(s) that the suppression is for 435 (if more than one, comma-separated), and the name of the suppression 436 itself, separated by a colon (n.b.: no spaces are allowed), eg:</para> 437 <programlisting><![CDATA[ 438 tool_name1,tool_name2:suppression_name]]></programlisting> 439 440 <para>Recall that Valgrind is a modular system, in which 441 different instrumentation tools can observe your program whilst it 442 is running. Since different tools detect different kinds of errors, 443 it is necessary to say which tool(s) the suppression is meaningful 444 to.</para> 445 446 <para>Tools will complain, at startup, if a tool does not understand 447 any suppression directed to it. Tools ignore suppressions which are 448 not directed to them. As a result, it is quite practical to put 449 suppressions for all tools into the same suppression file.</para> 450 </listitem> 451 452 <listitem> 453 <para>Next line: a small number of suppression types have extra 454 information after the second line (eg. the <varname>Param</varname> 455 suppression for Memcheck)</para> 456 </listitem> 457 458 <listitem> 459 <para>Remaining lines: This is the calling context for the error -- 460 the chain of function calls that led to it. There can be up to 24 461 of these lines.</para> 462 463 <para>Locations may be names of either shared objects or 464 functions. They begin 465 <computeroutput>obj:</computeroutput> and 466 <computeroutput>fun:</computeroutput> respectively. Function and 467 object names to match against may use the wildcard characters 468 <computeroutput>*</computeroutput> and 469 <computeroutput>?</computeroutput>.</para> 470 471 <para><command>Important note: </command> C++ function names must be 472 <command>mangled</command>. If you are writing suppressions by 473 hand, use the <option>--demangle=no</option> option to get the 474 mangled names in your error messages. An example of a mangled 475 C++ name is <computeroutput>_ZN9QListView4showEv</computeroutput>. 476 This is the form that the GNU C++ compiler uses internally, and 477 the form that must be used in suppression files. The equivalent 478 demangled name, <computeroutput>QListView::show()</computeroutput>, 479 is what you see at the C++ source code level. 480 </para> 481 482 <para>A location line may also be 483 simply "<computeroutput>...</computeroutput>" (three dots). This is 484 a frame-level wildcard, which matches zero or more frames. Frame 485 level wildcards are useful because they make it easy to ignore 486 varying numbers of uninteresting frames in between frames of 487 interest. That is often important when writing suppressions which 488 are intended to be robust against variations in the amount of 489 function inlining done by compilers.</para> 490 </listitem> 491 492 <listitem> 493 <para>Finally, the entire suppression must be between curly 494 braces. Each brace must be the first character on its own 495 line.</para> 496 </listitem> 497 498 </itemizedlist> 499 500 <para>A suppression only suppresses an error when the error matches all 501 the details in the suppression. Here's an example:</para> 502 503 <programlisting><![CDATA[ 504 { 505 __gconv_transform_ascii_internal/__mbrtowc/mbtowc 506 Memcheck:Value4 507 fun:__gconv_transform_ascii_internal 508 fun:__mbr*toc 509 fun:mbtowc 510 }]]></programlisting> 511 512 513 <para>What it means is: for Memcheck only, suppress a 514 use-of-uninitialised-value error, when the data size is 4, when it 515 occurs in the function 516 <computeroutput>__gconv_transform_ascii_internal</computeroutput>, when 517 that is called from any function of name matching 518 <computeroutput>__mbr*toc</computeroutput>, when that is called from 519 <computeroutput>mbtowc</computeroutput>. It doesn't apply under any 520 other circumstances. The string by which this suppression is identified 521 to the user is 522 <computeroutput>__gconv_transform_ascii_internal/__mbrtowc/mbtowc</computeroutput>.</para> 523 524 <para>(See <xref linkend="mc-manual.suppfiles"/> for more details 525 on the specifics of Memcheck's suppression kinds.)</para> 526 527 <para>Another example, again for the Memcheck tool:</para> 528 529 <programlisting><![CDATA[ 530 { 531 libX11.so.6.2/libX11.so.6.2/libXaw.so.7.0 532 Memcheck:Value4 533 obj:/usr/X11R6/lib/libX11.so.6.2 534 obj:/usr/X11R6/lib/libX11.so.6.2 535 obj:/usr/X11R6/lib/libXaw.so.7.0 536 }]]></programlisting> 537 538 <para>This suppresses any size 4 uninitialised-value error which occurs 539 anywhere in <filename>libX11.so.6.2</filename>, when called from 540 anywhere in the same library, when called from anywhere in 541 <filename>libXaw.so.7.0</filename>. The inexact specification of 542 locations is regrettable, but is about all you can hope for, given that 543 the X11 libraries shipped on the Linux distro on which this example 544 was made have had their symbol tables removed.</para> 545 546 <para>Although the above two examples do not make this clear, you can 547 freely mix <computeroutput>obj:</computeroutput> and 548 <computeroutput>fun:</computeroutput> lines in a suppression.</para> 549 550 <para>Finally, here's an example using three frame-level wildcards:</para> 551 552 <programlisting><![CDATA[ 553 { 554 a-contrived-example 555 Memcheck:Leak 556 fun:malloc 557 ... 558 fun:ddd 559 ... 560 fun:ccc 561 ... 562 fun:main 563 } 564 ]]></programlisting> 565 This suppresses Memcheck memory-leak errors, in the case where 566 the allocation was done by <computeroutput>main</computeroutput> 567 calling (though any number of intermediaries, including zero) 568 <computeroutput>ccc</computeroutput>, 569 calling onwards via 570 <computeroutput>ddd</computeroutput> and eventually 571 to <computeroutput>malloc.</computeroutput>. 572 </sect1> 573 574 575 <sect1 id="manual-core.options" 576 xreflabel="Core Command-line Options"> 577 <title>Core Command-line Options</title> 578 579 <para>As mentioned above, Valgrind's core accepts a common set of options. 580 The tools also accept tool-specific options, which are documented 581 separately for each tool.</para> 582 583 <para>Valgrind's default settings succeed in giving reasonable behaviour 584 in most cases. We group the available options by rough categories.</para> 585 586 <sect2 id="manual-core.toolopts" xreflabel="Tool-selection Option"> 587 <title>Tool-selection Option</title> 588 589 <para id="tool.opts.para">The single most important option.</para> 590 591 <variablelist id="tool.opts.list"> 592 593 <varlistentry id="tool_name" xreflabel="--tool"> 594 <term> 595 <option><![CDATA[--tool=<toolname> [default: memcheck] ]]></option> 596 </term> 597 <listitem> 598 <para>Run the Valgrind tool called <varname>toolname</varname>, 599 e.g. memcheck, cachegrind, callgrind, helgrind, drd, massif, 600 lackey, none, exp-sgcheck, exp-bbv, exp-dhat, etc.</para> 601 </listitem> 602 </varlistentry> 603 604 </variablelist> 605 606 </sect2> 607 608 609 610 <sect2 id="manual-core.basicopts" xreflabel="Basic Options"> 611 <title>Basic Options</title> 612 613 <!-- start of xi:include in the manpage --> 614 <para id="basic.opts.para">These options work with all tools.</para> 615 616 <variablelist id="basic.opts.list"> 617 618 <varlistentry id="opt.help" xreflabel="--help"> 619 <term><option>-h --help</option></term> 620 <listitem> 621 <para>Show help for all options, both for the core and for the 622 selected tool. If the option is repeated it is equivalent to giving 623 <option>--help-debug</option>.</para> 624 </listitem> 625 </varlistentry> 626 627 <varlistentry id="opt.help-debug" xreflabel="--help-debug"> 628 <term><option>--help-debug</option></term> 629 <listitem> 630 <para>Same as <option>--help</option>, but also lists debugging 631 options which usually are only of use to Valgrind's 632 developers.</para> 633 </listitem> 634 </varlistentry> 635 636 <varlistentry id="opt.version" xreflabel="--version"> 637 <term><option>--version</option></term> 638 <listitem> 639 <para>Show the version number of the Valgrind core. Tools can have 640 their own version numbers. There is a scheme in place to ensure 641 that tools only execute when the core version is one they are 642 known to work with. This was done to minimise the chances of 643 strange problems arising from tool-vs-core version 644 incompatibilities.</para> 645 </listitem> 646 </varlistentry> 647 648 <varlistentry id="opt.quiet" xreflabel="--quiet"> 649 <term><option>-q</option>, <option>--quiet</option></term> 650 <listitem> 651 <para>Run silently, and only print error messages. Useful if you 652 are running regression tests or have some other automated test 653 machinery.</para> 654 </listitem> 655 </varlistentry> 656 657 <varlistentry id="opt.verbose" xreflabel="--verbose"> 658 <term><option>-v</option>, <option>--verbose</option></term> 659 <listitem> 660 <para>Be more verbose. Gives extra information on various aspects 661 of your program, such as: the shared objects loaded, the 662 suppressions used, the progress of the instrumentation and 663 execution engines, and warnings about unusual behaviour. Repeating 664 the option increases the verbosity level.</para> 665 </listitem> 666 </varlistentry> 667 668 <varlistentry id="opt.trace-children" xreflabel="--trace-children"> 669 <term> 670 <option><![CDATA[--trace-children=<yes|no> [default: no] ]]></option> 671 </term> 672 <listitem> 673 <para>When enabled, Valgrind will trace into sub-processes 674 initiated via the <varname>exec</varname> system call. This is 675 necessary for multi-process programs. 676 </para> 677 <para>Note that Valgrind does trace into the child of a 678 <varname>fork</varname> (it would be difficult not to, since 679 <varname>fork</varname> makes an identical copy of a process), so this 680 option is arguably badly named. However, most children of 681 <varname>fork</varname> calls immediately call <varname>exec</varname> 682 anyway. 683 </para> 684 </listitem> 685 </varlistentry> 686 687 <varlistentry id="opt.trace-children-skip" xreflabel="--trace-children-skip"> 688 <term> 689 <option><![CDATA[--trace-children-skip=patt1,patt2,... ]]></option> 690 </term> 691 <listitem> 692 <para>This option only has an effect when 693 <option>--trace-children=yes</option> is specified. It allows 694 for some children to be skipped. The option takes a comma 695 separated list of patterns for the names of child executables 696 that Valgrind should not trace into. Patterns may include the 697 metacharacters <computeroutput>?</computeroutput> 698 and <computeroutput>*</computeroutput>, which have the usual 699 meaning.</para> 700 <para> 701 This can be useful for pruning uninteresting branches from a 702 tree of processes being run on Valgrind. But you should be 703 careful when using it. When Valgrind skips tracing into an 704 executable, it doesn't just skip tracing that executable, it 705 also skips tracing any of that executable's child processes. 706 In other words, the flag doesn't merely cause tracing to stop 707 at the specified executables -- it skips tracing of entire 708 process subtrees rooted at any of the specified 709 executables.</para> 710 </listitem> 711 </varlistentry> 712 713 <varlistentry id="opt.trace-children-skip-by-arg" 714 xreflabel="--trace-children-skip-by-arg"> 715 <term> 716 <option><![CDATA[--trace-children-skip-by-arg=patt1,patt2,... ]]></option> 717 </term> 718 <listitem> 719 <para>This is the same as 720 <option>--trace-children-skip</option>, with one difference: 721 the decision as to whether to trace into a child process is 722 made by examining the arguments to the child process, rather 723 than the name of its executable.</para> 724 </listitem> 725 </varlistentry> 726 727 <varlistentry id="opt.child-silent-after-fork" 728 xreflabel="--child-silent-after-fork"> 729 <term> 730 <option><![CDATA[--child-silent-after-fork=<yes|no> [default: no] ]]></option> 731 </term> 732 <listitem> 733 <para>When enabled, Valgrind will not show any debugging or 734 logging output for the child process resulting from 735 a <varname>fork</varname> call. This can make the output less 736 confusing (although more misleading) when dealing with processes 737 that create children. It is particularly useful in conjunction 738 with <varname>--trace-children=</varname>. Use of this option is also 739 strongly recommended if you are requesting XML output 740 (<varname>--xml=yes</varname>), since otherwise the XML from child and 741 parent may become mixed up, which usually makes it useless. 742 </para> 743 </listitem> 744 </varlistentry> 745 746 <varlistentry id="opt.vgdb" xreflabel="--vgdb"> 747 <term> 748 <option><![CDATA[--vgdb=<no|yes|full> [default: yes] ]]></option> 749 </term> 750 <listitem> 751 752 <para>Valgrind will provide "gdbserver" functionality when 753 <option>--vgdb=yes</option> or <option>--vgdb=full</option> is 754 specified. This allows an external GNU GDB debugger to control 755 and debug your program when it runs on Valgrind. 756 <option>--vgdb=full</option> incurs significant performance 757 overheads, but provides more precise breakpoints and 758 watchpoints. See <xref linkend="manual-core-adv.gdbserver"/> for 759 a detailed description. 760 </para> 761 762 <para> If the embedded gdbserver is enabled but no gdb is 763 currently being used, the <xref linkend="manual-core-adv.vgdb"/> 764 command line utility can send "monitor commands" to Valgrind 765 from a shell. The Valgrind core provides a set of 766 <xref linkend="manual-core-adv.valgrind-monitor-commands"/>. A tool 767 can optionally provide tool specific monitor commands, which are 768 documented in the tool specific chapter. 769 </para> 770 771 </listitem> 772 </varlistentry> 773 774 <varlistentry id="opt.vgdb-error" xreflabel="--vgdb-error"> 775 <term> 776 <option><![CDATA[--vgdb-error=<number> [default: 999999999] ]]></option> 777 </term> 778 <listitem> 779 <para> Use this option when the Valgrind gdbserver is enabled with 780 <option>--vgdb=yes</option> or <option>--vgdb=full</option>. 781 Tools that report errors will wait 782 for "<computeroutput>number</computeroutput>" errors to be 783 reported before freezing the program and waiting for you to 784 connect with GDB. It follows that a value of zero will cause 785 the gdbserver to be started before your program is executed. 786 This is typically used to insert GDB breakpoints before 787 execution, and also works with tools that do not report 788 errors, such as Massif. 789 </para> 790 </listitem> 791 </varlistentry> 792 793 <varlistentry id="opt.vgdb-stop-at" xreflabel="--vgdb-stop-at"> 794 <term> 795 <option><![CDATA[--vgdb-stop-at=<set> [default: none] ]]></option> 796 </term> 797 <listitem> 798 <para> Use this option when the Valgrind gdbserver is enabled with 799 <option>--vgdb=yes</option> or <option>--vgdb=full</option>. 800 The Valgrind gdbserver will be invoked for each error after 801 <option>--vgdb-error</option> have been reported. 802 You can additionally ask the Valgrind gdbserver to be invoked 803 for other events, specified in one of the following ways: </para> 804 <itemizedlist> 805 <listitem><para>a comma separated list of one or more of 806 <option>startup exit valgrindabexit</option>.</para> 807 808 <para>The values <option>startup</option> <option>exit</option> 809 <option>valgrindabexit</option> respectively indicate to 810 invoke gdbserver before your program is executed, after the 811 last instruction of your program, on Valgrind abnormal exit 812 (e.g. internal error, out of memory, ...).</para> 813 814 <para>Note: <option>startup</option> and 815 <option>--vgdb-error=0</option> will both cause Valgrind 816 gdbserver to be invoked before your program is executed. The 817 <option>--vgdb-error=0</option> will in addition cause your 818 program to stop on all subsequent errors.</para> 819 820 </listitem> 821 822 <listitem><para><option>all</option> to specify the complete set. 823 It is equivalent to 824 <option>--vgdb-stop-at=startup,exit,valgrindabexit</option>.</para> 825 </listitem> 826 827 <listitem><para><option>none</option> for the empty set.</para> 828 </listitem> 829 </itemizedlist> 830 </listitem> 831 </varlistentry> 832 833 <varlistentry id="opt.track-fds" xreflabel="--track-fds"> 834 <term> 835 <option><![CDATA[--track-fds=<yes|no> [default: no] ]]></option> 836 </term> 837 <listitem> 838 <para>When enabled, Valgrind will print out a list of open file 839 descriptors on exit or on request, via the gdbserver monitor 840 command <varname>v.info open_fds</varname>. Along with each 841 file descriptor is printed a stack backtrace of where the file 842 was opened and any details relating to the file descriptor such 843 as the file name or socket details.</para> 844 </listitem> 845 </varlistentry> 846 847 <varlistentry id="opt.time-stamp" xreflabel="--time-stamp"> 848 <term> 849 <option><![CDATA[--time-stamp=<yes|no> [default: no] ]]></option> 850 </term> 851 <listitem> 852 <para>When enabled, each message is preceded with an indication of 853 the elapsed wallclock time since startup, expressed as days, 854 hours, minutes, seconds and milliseconds.</para> 855 </listitem> 856 </varlistentry> 857 858 <varlistentry id="opt.log-fd" xreflabel="--log-fd"> 859 <term> 860 <option><![CDATA[--log-fd=<number> [default: 2, stderr] ]]></option> 861 </term> 862 <listitem> 863 <para>Specifies that Valgrind should send all of its messages to 864 the specified file descriptor. The default, 2, is the standard 865 error channel (stderr). Note that this may interfere with the 866 client's own use of stderr, as Valgrind's output will be 867 interleaved with any output that the client sends to 868 stderr.</para> 869 </listitem> 870 </varlistentry> 871 872 <varlistentry id="opt.log-file" xreflabel="--log-file"> 873 <term> 874 <option><![CDATA[--log-file=<filename> ]]></option> 875 </term> 876 <listitem> 877 <para>Specifies that Valgrind should send all of its messages to 878 the specified file. If the file name is empty, it causes an abort. 879 There are three special format specifiers that can be used in the file 880 name.</para> 881 882 <para><option>%p</option> is replaced with the current process ID. 883 This is very useful for program that invoke multiple processes. 884 WARNING: If you use <option>--trace-children=yes</option> and your 885 program invokes multiple processes OR your program forks without 886 calling exec afterwards, and you don't use this specifier 887 (or the <option>%q</option> specifier below), the Valgrind output from 888 all those processes will go into one file, possibly jumbled up, and 889 possibly incomplete. Note: If the program forks and calls exec afterwards, 890 Valgrind output of the child from the period between fork and exec 891 will be lost. Fortunately this gap is really tiny for most programs; 892 and modern programs use <computeroutput>posix_spawn</computeroutput> 893 anyway.</para> 894 895 <para><option>%n</option> is replaced with a file sequence number 896 unique for this process. 897 This is useful for processes that produces several files 898 from the same filename template.</para> 899 900 901 <para><option>%q{FOO}</option> is replaced with the contents of the 902 environment variable <varname>FOO</varname>. If the 903 <option>{FOO}</option> part is malformed, it causes an abort. This 904 specifier is rarely needed, but very useful in certain circumstances 905 (eg. when running MPI programs). The idea is that you specify a 906 variable which will be set differently for each process in the job, 907 for example <computeroutput>BPROC_RANK</computeroutput> or whatever is 908 applicable in your MPI setup. If the named environment variable is not 909 set, it causes an abort. Note that in some shells, the 910 <option>{</option> and <option>}</option> characters may need to be 911 escaped with a backslash.</para> 912 913 <para><option>%%</option> is replaced with <option>%</option>.</para> 914 915 <para>If an <option>%</option> is followed by any other character, it 916 causes an abort.</para> 917 918 <para>If the file name specifies a relative file name, it is put 919 in the program's initial working directory: this is the current 920 directory when the program started its execution after the fork 921 or after the exec. If it specifies an absolute file name (ie. 922 starts with '/') then it is put there. 923 </para> 924 </listitem> 925 </varlistentry> 926 927 <varlistentry id="opt.log-socket" xreflabel="--log-socket"> 928 <term> 929 <option><![CDATA[--log-socket=<ip-address:port-number> ]]></option> 930 </term> 931 <listitem> 932 <para>Specifies that Valgrind should send all of its messages to 933 the specified port at the specified IP address. The port may be 934 omitted, in which case port 1500 is used. If a connection cannot 935 be made to the specified socket, Valgrind falls back to writing 936 output to the standard error (stderr). This option is intended to 937 be used in conjunction with the 938 <computeroutput>valgrind-listener</computeroutput> program. For 939 further details, see 940 <link linkend="&vg-comment-id;">the commentary</link> 941 in the manual.</para> 942 </listitem> 943 </varlistentry> 944 945 </variablelist> 946 <!-- end of xi:include in the manpage --> 947 948 </sect2> 949 950 951 <sect2 id="manual-core.erropts" xreflabel="Error-related Options"> 952 <title>Error-related Options</title> 953 954 <!-- start of xi:include in the manpage --> 955 <para id="error-related.opts.para">These options are used by all tools 956 that can report errors, e.g. Memcheck, but not Cachegrind.</para> 957 958 <variablelist id="error-related.opts.list"> 959 960 <varlistentry id="opt.xml" xreflabel="--xml"> 961 <term> 962 <option><![CDATA[--xml=<yes|no> [default: no] ]]></option> 963 </term> 964 <listitem> 965 <para>When enabled, the important parts of the output (e.g. tool error 966 messages) will be in XML format rather than plain text. Furthermore, 967 the XML output will be sent to a different output channel than the 968 plain text output. Therefore, you also must use one of 969 <option>--xml-fd</option>, <option>--xml-file</option> or 970 <option>--xml-socket</option> to specify where the XML is to be sent. 971 </para> 972 973 <para>Less important messages will still be printed in plain text, but 974 because the XML output and plain text output are sent to different 975 output channels (the destination of the plain text output is still 976 controlled by <option>--log-fd</option>, <option>--log-file</option> 977 and <option>--log-socket</option>) this should not cause problems. 978 </para> 979 980 <para>This option is aimed at making life easier for tools that consume 981 Valgrind's output as input, such as GUI front ends. Currently this 982 option works with Memcheck, Helgrind, DRD and SGcheck. The output 983 format is specified in the file 984 <computeroutput>docs/internals/xml-output-protocol4.txt</computeroutput> 985 in the source tree for Valgrind 3.5.0 or later.</para> 986 987 <para>The recommended options for a GUI to pass, when requesting 988 XML output, are: <option>--xml=yes</option> to enable XML output, 989 <option>--xml-file</option> to send the XML output to a (presumably 990 GUI-selected) file, <option>--log-file</option> to send the plain 991 text output to a second GUI-selected file, 992 <option>--child-silent-after-fork=yes</option>, and 993 <option>-q</option> to restrict the plain text output to critical 994 error messages created by Valgrind itself. For example, failure to 995 read a specified suppressions file counts as a critical error message. 996 In this way, for a successful run the text output file will be empty. 997 But if it isn't empty, then it will contain important information 998 which the GUI user should be made aware 999 of.</para> 1000 </listitem> 1001 </varlistentry> 1002 1003 <varlistentry id="opt.xml-fd" xreflabel="--xml-fd"> 1004 <term> 1005 <option><![CDATA[--xml-fd=<number> [default: -1, disabled] ]]></option> 1006 </term> 1007 <listitem> 1008 <para>Specifies that Valgrind should send its XML output to the 1009 specified file descriptor. It must be used in conjunction with 1010 <option>--xml=yes</option>.</para> 1011 </listitem> 1012 </varlistentry> 1013 1014 <varlistentry id="opt.xml-file" xreflabel="--xml-file"> 1015 <term> 1016 <option><![CDATA[--xml-file=<filename> ]]></option> 1017 </term> 1018 <listitem> 1019 <para>Specifies that Valgrind should send its XML output 1020 to the specified file. It must be used in conjunction with 1021 <option>--xml=yes</option>. Any <option>%p</option> or 1022 <option>%q</option> sequences appearing in the filename are expanded 1023 in exactly the same way as they are for <option>--log-file</option>. 1024 See the description of <xref linkend="opt.log-file"/> for details. 1025 </para> 1026 </listitem> 1027 </varlistentry> 1028 1029 <varlistentry id="opt.xml-socket" xreflabel="--xml-socket"> 1030 <term> 1031 <option><![CDATA[--xml-socket=<ip-address:port-number> ]]></option> 1032 </term> 1033 <listitem> 1034 <para>Specifies that Valgrind should send its XML output the 1035 specified port at the specified IP address. It must be used in 1036 conjunction with <option>--xml=yes</option>. The form of the argument 1037 is the same as that used by <option>--log-socket</option>. 1038 See the description of <option>--log-socket</option> 1039 for further details.</para> 1040 </listitem> 1041 </varlistentry> 1042 1043 <varlistentry id="opt.xml-user-comment" xreflabel="--xml-user-comment"> 1044 <term> 1045 <option><![CDATA[--xml-user-comment=<string> ]]></option> 1046 </term> 1047 <listitem> 1048 <para>Embeds an extra user comment string at the start of the XML 1049 output. Only works when <option>--xml=yes</option> is specified; 1050 ignored otherwise.</para> 1051 </listitem> 1052 </varlistentry> 1053 1054 <varlistentry id="opt.demangle" xreflabel="--demangle"> 1055 <term> 1056 <option><![CDATA[--demangle=<yes|no> [default: yes] ]]></option> 1057 </term> 1058 <listitem> 1059 <para>Enable/disable automatic demangling (decoding) of C++ names. 1060 Enabled by default. When enabled, Valgrind will attempt to 1061 translate encoded C++ names back to something approaching the 1062 original. The demangler handles symbols mangled by g++ versions 1063 2.X, 3.X and 4.X.</para> 1064 1065 <para>An important fact about demangling is that function names 1066 mentioned in suppressions files should be in their mangled form. 1067 Valgrind does not demangle function names when searching for 1068 applicable suppressions, because to do otherwise would make 1069 suppression file contents dependent on the state of Valgrind's 1070 demangling machinery, and also slow down suppression matching.</para> 1071 </listitem> 1072 </varlistentry> 1073 1074 <varlistentry id="opt.num-callers" xreflabel="--num-callers"> 1075 <term> 1076 <option><![CDATA[--num-callers=<number> [default: 12] ]]></option> 1077 </term> 1078 <listitem> 1079 <para>Specifies the maximum number of entries shown in stack traces 1080 that identify program locations. Note that errors are commoned up 1081 using only the top four function locations (the place in the current 1082 function, and that of its three immediate callers). So this doesn't 1083 affect the total number of errors reported.</para> 1084 1085 <para>The maximum value for this is 500. Note that higher settings 1086 will make Valgrind run a bit more slowly and take a bit more 1087 memory, but can be useful when working with programs with 1088 deeply-nested call chains.</para> 1089 </listitem> 1090 </varlistentry> 1091 1092 <varlistentry id="opt.unw-stack-scan-thresh" 1093 xreflabel="--unw-stack-scan-thresh"> 1094 <term> 1095 <option><![CDATA[--unw-stack-scan-thresh=<number> [default: 0] ]]></option> 1096 </term> 1097 <term> 1098 <option><![CDATA[--unw-stack-scan-frames=<number> [default: 5] ]]></option> 1099 </term> 1100 <listitem> 1101 <para>Stack-scanning support is available only on ARM 1102 targets.</para> 1103 1104 <para>These flags enable and control stack unwinding by stack 1105 scanning. When the normal stack unwinding mechanisms -- usage 1106 of Dwarf CFI records, and frame-pointer following -- fail, stack 1107 scanning may be able to recover a stack trace.</para> 1108 1109 <para>Note that stack scanning is an imprecise, heuristic 1110 mechanism that may give very misleading results, or none at all. 1111 It should be used only in emergencies, when normal unwinding 1112 fails, and it is important to nevertheless have stack 1113 traces.</para> 1114 1115 <para>Stack scanning is a simple technique: the unwinder reads 1116 words from the stack, and tries to guess which of them might be 1117 return addresses, by checking to see if they point just after 1118 ARM or Thumb call instructions. If so, the word is added to the 1119 backtrace.</para> 1120 1121 <para>The main danger occurs when a function call returns, 1122 leaving its return address exposed, and a new function is 1123 called, but the new function does not overwrite the old address. 1124 The result of this is that the backtrace may contain entries for 1125 functions which have already returned, and so be very 1126 confusing.</para> 1127 1128 <para>A second limitation of this implementation is that it will 1129 scan only the page (4KB, normally) containing the starting stack 1130 pointer. If the stack frames are large, this may result in only 1131 a few (or not even any) being present in the trace. Also, if 1132 you are unlucky and have an initial stack pointer near the end 1133 of its containing page, the scan may miss all interesting 1134 frames.</para> 1135 1136 <para>By default stack scanning is disabled. The normal use 1137 case is to ask for it when a stack trace would otherwise be very 1138 short. So, to enable it, 1139 use <computeroutput>--unw-stack-scan-thresh=number</computeroutput>. 1140 This requests Valgrind to try using stack scanning to "extend" 1141 stack traces which contain fewer 1142 than <computeroutput>number</computeroutput> frames.</para> 1143 1144 <para>If stack scanning does take place, it will only generate 1145 at most the number of frames specified 1146 by <computeroutput>--unw-stack-scan-frames</computeroutput>. 1147 Typically, stack scanning generates so many garbage entries that 1148 this value is set to a low value (5) by default. In no case 1149 will a stack trace larger than the value specified 1150 by <computeroutput>--num-callers</computeroutput> be 1151 created.</para> 1152 </listitem> 1153 </varlistentry> 1154 1155 <varlistentry id="opt.error-limit" xreflabel="--error-limit"> 1156 <term> 1157 <option><![CDATA[--error-limit=<yes|no> [default: yes] ]]></option> 1158 </term> 1159 <listitem> 1160 <para>When enabled, Valgrind stops reporting errors after 10,000,000 1161 in total, or 1,000 different ones, have been seen. This is to 1162 stop the error tracking machinery from becoming a huge performance 1163 overhead in programs with many errors.</para> 1164 </listitem> 1165 </varlistentry> 1166 1167 <varlistentry id="opt.error-exitcode" xreflabel="--error-exitcode"> 1168 <term> 1169 <option><![CDATA[--error-exitcode=<number> [default: 0] ]]></option> 1170 </term> 1171 <listitem> 1172 <para>Specifies an alternative exit code to return if Valgrind 1173 reported any errors in the run. When set to the default value 1174 (zero), the return value from Valgrind will always be the return 1175 value of the process being simulated. When set to a nonzero value, 1176 that value is returned instead, if Valgrind detects any errors. 1177 This is useful for using Valgrind as part of an automated test 1178 suite, since it makes it easy to detect test cases for which 1179 Valgrind has reported errors, just by inspecting return codes.</para> 1180 </listitem> 1181 </varlistentry> 1182 1183 <varlistentry id="opt.error-markers" xreflabel="--error-markers"> 1184 <term> 1185 <option><![CDATA[--error-markers=<begin>,<end> [default: none]]]></option> 1186 </term> 1187 <listitem> 1188 <para>When errors are output as plain text (i.e. XML not used), 1189 <option>--error-markers</option> instructs to output a line 1190 containing the <option>begin</option> (<option>end</option>) 1191 string before (after) each error. </para> 1192 <para> Such marker lines facilitate searching for errors and/or 1193 extracting errors in an output file that contain valgrind errors mixed 1194 with the program output. </para> 1195 <para> Note that empty markers are accepted. So, only using a begin 1196 (or an end) marker is possible.</para> 1197 </listitem> 1198 </varlistentry> 1199 1200 <varlistentry id="opt.sigill-diagnostics" xreflabel="--sigill-diagnostics"> 1201 <term> 1202 <option><![CDATA[--sigill-diagnostics=<yes|no> [default: yes] ]]></option> 1203 </term> 1204 <listitem> 1205 <para>Enable/disable printing of illegal instruction diagnostics. 1206 Enabled by default, but defaults to disabled when 1207 <option>--quiet</option> is given. The default can always be explicitly 1208 overridden by giving this option.</para> 1209 1210 <para>When enabled, a warning message will be printed, along with some 1211 diagnostics, whenever an instruction is encountered that Valgrind 1212 cannot decode or translate, before the program is given a SIGILL signal. 1213 Often an illegal instruction indicates a bug in the program or missing 1214 support for the particular instruction in Valgrind. But some programs 1215 do deliberately try to execute an instruction that might be missing 1216 and trap the SIGILL signal to detect processor features. Using 1217 this flag makes it possible to avoid the diagnostic output 1218 that you would otherwise get in such cases.</para> 1219 </listitem> 1220 </varlistentry> 1221 1222 <varlistentry id="opt.show-below-main" xreflabel="--show-below-main"> 1223 <term> 1224 <option><![CDATA[--show-below-main=<yes|no> [default: no] ]]></option> 1225 </term> 1226 <listitem> 1227 <para>By default, stack traces for errors do not show any 1228 functions that appear beneath <function>main</function> because 1229 most of the time it's uninteresting C library stuff and/or 1230 gobbledygook. Alternatively, if <function>main</function> is not 1231 present in the stack trace, stack traces will not show any functions 1232 below <function>main</function>-like functions such as glibc's 1233 <function>__libc_start_main</function>. Furthermore, if 1234 <function>main</function>-like functions are present in the trace, 1235 they are normalised as <function>(below main)</function>, in order to 1236 make the output more deterministic.</para> 1237 1238 <para>If this option is enabled, all stack trace entries will be 1239 shown and <function>main</function>-like functions will not be 1240 normalised.</para> 1241 </listitem> 1242 </varlistentry> 1243 1244 <varlistentry id="opt.fullpath-after" xreflabel="--fullpath-after"> 1245 <term> 1246 <option><![CDATA[--fullpath-after=<string> 1247 [default: don't show source paths] ]]></option> 1248 </term> 1249 <listitem> 1250 <para>By default Valgrind only shows the filenames in stack 1251 traces, but not full paths to source files. When using Valgrind 1252 in large projects where the sources reside in multiple different 1253 directories, this can be inconvenient. 1254 <option>--fullpath-after</option> provides a flexible solution 1255 to this problem. When this option is present, the path to each 1256 source file is shown, with the following all-important caveat: 1257 if <option>string</option> is found in the path, then the path 1258 up to and including <option>string</option> is omitted, else the 1259 path is shown unmodified. Note that <option>string</option> is 1260 not required to be a prefix of the path.</para> 1261 1262 <para>For example, consider a file named 1263 <computeroutput>/home/janedoe/blah/src/foo/bar/xyzzy.c</computeroutput>. 1264 Specifying <option>--fullpath-after=/home/janedoe/blah/src/</option> 1265 will cause Valgrind to show the name 1266 as <computeroutput>foo/bar/xyzzy.c</computeroutput>.</para> 1267 1268 <para>Because the string is not required to be a prefix, 1269 <option>--fullpath-after=src/</option> will produce the same 1270 output. This is useful when the path contains arbitrary 1271 machine-generated characters. For example, the 1272 path 1273 <computeroutput>/my/build/dir/C32A1B47/blah/src/foo/xyzzy</computeroutput> 1274 can be pruned to <computeroutput>foo/xyzzy</computeroutput> 1275 using 1276 <option>--fullpath-after=/blah/src/</option>.</para> 1277 1278 <para>If you simply want to see the full path, just specify an 1279 empty string: <option>--fullpath-after=</option>. This isn't a 1280 special case, merely a logical consequence of the above rules.</para> 1281 1282 <para>Finally, you can use <option>--fullpath-after</option> 1283 multiple times. Any appearance of it causes Valgrind to switch 1284 to producing full paths and applying the above filtering rule. 1285 Each produced path is compared against all 1286 the <option>--fullpath-after</option>-specified strings, in the 1287 order specified. The first string to match causes the path to 1288 be truncated as described above. If none match, the full path 1289 is shown. This facilitates chopping off prefixes when the 1290 sources are drawn from a number of unrelated directories. 1291 </para> 1292 </listitem> 1293 </varlistentry> 1294 1295 <varlistentry id="opt.extra-debuginfo-path" xreflabel="--extra-debuginfo-path"> 1296 <term> 1297 <option><![CDATA[--extra-debuginfo-path=<path> [default: undefined and unused] ]]></option> 1298 </term> 1299 <listitem> 1300 <para>By default Valgrind searches in several well-known paths 1301 for debug objects, such 1302 as <computeroutput>/usr/lib/debug/</computeroutput>.</para> 1303 1304 <para>However, there may be scenarios where you may wish to put 1305 debug objects at an arbitrary location, such as external storage 1306 when running Valgrind on a mobile device with limited local 1307 storage. Another example might be a situation where you do not 1308 have permission to install debug object packages on the system 1309 where you are running Valgrind.</para> 1310 1311 <para>In these scenarios, you may provide an absolute path as an extra, 1312 final place for Valgrind to search for debug objects by specifying 1313 <option>--extra-debuginfo-path=/path/to/debug/objects</option>. 1314 The given path will be prepended to the absolute path name of 1315 the searched-for object. For example, if Valgrind is looking 1316 for the debuginfo 1317 for <computeroutput>/w/x/y/zz.so</computeroutput> 1318 and <option>--extra-debuginfo-path=/a/b/c</option> is specified, 1319 it will look for a debug object at 1320 <computeroutput>/a/b/c/w/x/y/zz.so</computeroutput>.</para> 1321 1322 <para>This flag should only be specified once. If it is 1323 specified multiple times, only the last instance is 1324 honoured.</para> 1325 </listitem> 1326 </varlistentry> 1327 1328 <varlistentry id="opt.debuginfo-server" xreflabel="--debuginfo-server"> 1329 <term> 1330 <option><![CDATA[--debuginfo-server=ipaddr:port [default: undefined and unused]]]></option> 1331 </term> 1332 <listitem> 1333 <para>This is a new, experimental, feature introduced in version 1334 3.9.0.</para> 1335 1336 <para>In some scenarios it may be convenient to read debuginfo 1337 from objects stored on a different machine. With this flag, 1338 Valgrind will query a debuginfo server running 1339 on <computeroutput>ipaddr</computeroutput> and listening on 1340 port <computeroutput>port</computeroutput>, if it cannot find 1341 the debuginfo object in the local filesystem.</para> 1342 1343 <para>The debuginfo server must accept TCP connections on 1344 port <computeroutput>port</computeroutput>. The debuginfo 1345 server is contained in the source 1346 file <computeroutput>auxprogs/valgrind-di-server.c</computeroutput>. 1347 It will only serve from the directory it is started 1348 in. <computeroutput>port</computeroutput> defaults to 1500 in 1349 both client and server if not specified.</para> 1350 1351 <para>If Valgrind looks for the debuginfo for 1352 <computeroutput>/w/x/y/zz.so</computeroutput> by using the 1353 debuginfo server, it will strip the pathname components and 1354 merely request <computeroutput>zz.so</computeroutput> on the 1355 server. That in turn will look only in its current working 1356 directory for a matching debuginfo object.</para> 1357 1358 <para>The debuginfo data is transmitted in small fragments (8 1359 KB) as requested by Valgrind. Each block is compressed using 1360 LZO to reduce transmission time. The implementation has been 1361 tuned for best performance over a single-stage 802.11g (WiFi) 1362 network link.</para> 1363 1364 <para>Note that checks for matching primary vs debug objects, 1365 using GNU debuglink CRC scheme, are performed even when using 1366 the debuginfo server. To disable such checking, you need to 1367 also specify 1368 <computeroutput>--allow-mismatched-debuginfo=yes</computeroutput>. 1369 </para> 1370 1371 <para>By default the Valgrind build system will 1372 build <computeroutput>valgrind-di-server</computeroutput> for 1373 the target platform, which is almost certainly not what you 1374 want. So far we have been unable to find out how to get 1375 automake/autoconf to build it for the build platform. If 1376 you want to use it, you will have to recompile it by hand using 1377 the command shown at the top 1378 of <computeroutput>auxprogs/valgrind-di-server.c</computeroutput>.</para> 1379 </listitem> 1380 </varlistentry> 1381 1382 <varlistentry id="opt.allow-mismatched-debuginfo" 1383 xreflabel="--allow-mismatched-debuginfo"> 1384 <term> 1385 <option><![CDATA[--allow-mismatched-debuginfo=no|yes [no] ]]></option> 1386 </term> 1387 <listitem> 1388 <para>When reading debuginfo from separate debuginfo objects, 1389 Valgrind will by default check that the main and debuginfo 1390 objects match, using the GNU debuglink mechanism. This 1391 guarantees that it does not read debuginfo from out of date 1392 debuginfo objects, and also ensures that Valgrind can't crash as 1393 a result of mismatches.</para> 1394 1395 <para>This check can be overridden using 1396 <computeroutput>--allow-mismatched-debuginfo=yes</computeroutput>. 1397 This may be useful when the debuginfo and main objects have not 1398 been split in the proper way. Be careful when using this, 1399 though: it disables all consistency checking, and Valgrind has 1400 been observed to crash when the main and debuginfo objects don't 1401 match.</para> 1402 </listitem> 1403 </varlistentry> 1404 1405 <varlistentry id="opt.suppressions" xreflabel="--suppressions"> 1406 <term> 1407 <option><![CDATA[--suppressions=<filename> [default: $PREFIX/lib/valgrind/default.supp] ]]></option> 1408 </term> 1409 <listitem> 1410 <para>Specifies an extra file from which to read descriptions of 1411 errors to suppress. You may use up to 100 extra suppression 1412 files.</para> 1413 </listitem> 1414 </varlistentry> 1415 1416 <varlistentry id="opt.gen-suppressions" xreflabel="--gen-suppressions"> 1417 <term> 1418 <option><![CDATA[--gen-suppressions=<yes|no|all> [default: no] ]]></option> 1419 </term> 1420 <listitem> 1421 <para>When set to <varname>yes</varname>, Valgrind will pause 1422 after every error shown and print the line: 1423 <literallayout><computeroutput> ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ----</computeroutput></literallayout> 1424 1425 Pressing <varname>Ret</varname>, or <varname>N Ret</varname> or 1426 <varname>n Ret</varname>, causes Valgrind continue execution without 1427 printing a suppression for this error.</para> 1428 1429 <para>Pressing <varname>Y Ret</varname> or 1430 <varname>y Ret</varname> causes Valgrind to write a suppression 1431 for this error. You can then cut and paste it into a suppression file 1432 if you don't want to hear about the error in the future.</para> 1433 1434 <para>When set to <varname>all</varname>, Valgrind will print a 1435 suppression for every reported error, without querying the 1436 user.</para> 1437 1438 <para>This option is particularly useful with C++ programs, as it 1439 prints out the suppressions with mangled names, as 1440 required.</para> 1441 1442 <para>Note that the suppressions printed are as specific as 1443 possible. You may want to common up similar ones, by adding 1444 wildcards to function names, and by using frame-level wildcards. 1445 The wildcarding facilities are powerful yet flexible, and with a 1446 bit of careful editing, you may be able to suppress a whole 1447 family of related errors with only a few suppressions. 1448 <!-- commented out because it causes broken links in the man page 1449 For details on how to do this, see 1450 <xref linkend="manual-core.suppress"/>. 1451 --> 1452 </para> 1453 1454 <para>Sometimes two different errors 1455 are suppressed by the same suppression, in which case Valgrind 1456 will output the suppression more than once, but you only need to 1457 have one copy in your suppression file (but having more than one 1458 won't cause problems). Also, the suppression name is given as 1459 <computeroutput><insert a suppression name 1460 here></computeroutput>; the name doesn't really matter, it's 1461 only used with the <option>-v</option> option which prints out all 1462 used suppression records.</para> 1463 </listitem> 1464 </varlistentry> 1465 1466 <varlistentry id="opt.input-fd" xreflabel="--input-fd"> 1467 <term> 1468 <option><![CDATA[--input-fd=<number> [default: 0, stdin] ]]></option> 1469 </term> 1470 <listitem> 1471 <para>When using 1472 <option>--gen-suppressions=yes</option>, Valgrind will stop so as 1473 to read keyboard input from you when each error occurs. By 1474 default it reads from the standard input (stdin), which is 1475 problematic for programs which close stdin. This option allows 1476 you to specify an alternative file descriptor from which to read 1477 input.</para> 1478 </listitem> 1479 </varlistentry> 1480 1481 <varlistentry id="opt.dsymutil" xreflabel="--dsymutil"> 1482 <term> 1483 <option><![CDATA[--dsymutil=no|yes [yes] ]]></option> 1484 </term> 1485 <listitem> 1486 <para>This option is only relevant when running Valgrind on 1487 Mac OS X.</para> 1488 1489 <para>Mac OS X uses a deferred debug information (debuginfo) 1490 linking scheme. When object files containing debuginfo are 1491 linked into a <computeroutput>.dylib</computeroutput> or an 1492 executable, the debuginfo is not copied into the final file. 1493 Instead, the debuginfo must be linked manually by 1494 running <computeroutput>dsymutil</computeroutput>, a 1495 system-provided utility, on the executable 1496 or <computeroutput>.dylib</computeroutput>. The resulting 1497 combined debuginfo is placed in a directory alongside the 1498 executable or <computeroutput>.dylib</computeroutput>, but with 1499 the extension <computeroutput>.dSYM</computeroutput>.</para> 1500 1501 <para>With <option>--dsymutil=no</option>, Valgrind 1502 will detect cases where the 1503 <computeroutput>.dSYM</computeroutput> directory is either 1504 missing, or is present but does not appear to match the 1505 associated executable or <computeroutput>.dylib</computeroutput>, 1506 most likely because it is out of date. In these cases, Valgrind 1507 will print a warning message but take no further action.</para> 1508 1509 <para>With <option>--dsymutil=yes</option>, Valgrind 1510 will, in such cases, automatically 1511 run <computeroutput>dsymutil</computeroutput> as necessary to 1512 bring the debuginfo up to date. For all practical purposes, if 1513 you always use <option>--dsymutil=yes</option>, then 1514 there is never any need to 1515 run <computeroutput>dsymutil</computeroutput> manually or as part 1516 of your applications's build system, since Valgrind will run it 1517 as necessary.</para> 1518 1519 <para>Valgrind will not attempt to 1520 run <computeroutput>dsymutil</computeroutput> on any 1521 executable or library in 1522 <computeroutput>/usr/</computeroutput>, 1523 <computeroutput>/bin/</computeroutput>, 1524 <computeroutput>/sbin/</computeroutput>, 1525 <computeroutput>/opt/</computeroutput>, 1526 <computeroutput>/sw/</computeroutput>, 1527 <computeroutput>/System/</computeroutput>, 1528 <computeroutput>/Library/</computeroutput> or 1529 <computeroutput>/Applications/</computeroutput> 1530 since <computeroutput>dsymutil</computeroutput> will always fail 1531 in such situations. It fails both because the debuginfo for 1532 such pre-installed system components is not available anywhere, 1533 and also because it would require write privileges in those 1534 directories.</para> 1535 1536 <para>Be careful when 1537 using <option>--dsymutil=yes</option>, since it will 1538 cause pre-existing <computeroutput>.dSYM</computeroutput> 1539 directories to be silently deleted and re-created. Also note that 1540 <computeroutput>dsymutil</computeroutput> is quite slow, sometimes 1541 excessively so.</para> 1542 </listitem> 1543 </varlistentry> 1544 1545 <varlistentry id="opt.max-stackframe" xreflabel="--max-stackframe"> 1546 <term> 1547 <option><![CDATA[--max-stackframe=<number> [default: 2000000] ]]></option> 1548 </term> 1549 <listitem> 1550 <para>The maximum size of a stack frame. If the stack pointer moves by 1551 more than this amount then Valgrind will assume that 1552 the program is switching to a different stack.</para> 1553 1554 <para>You may need to use this option if your program has large 1555 stack-allocated arrays. Valgrind keeps track of your program's 1556 stack pointer. If it changes by more than the threshold amount, 1557 Valgrind assumes your program is switching to a different stack, 1558 and Memcheck behaves differently than it would for a stack pointer 1559 change smaller than the threshold. Usually this heuristic works 1560 well. However, if your program allocates large structures on the 1561 stack, this heuristic will be fooled, and Memcheck will 1562 subsequently report large numbers of invalid stack accesses. This 1563 option allows you to change the threshold to a different 1564 value.</para> 1565 1566 <para>You should only consider use of this option if Valgrind's 1567 debug output directs you to do so. In that case it will tell you 1568 the new threshold you should specify.</para> 1569 1570 <para>In general, allocating large structures on the stack is a 1571 bad idea, because you can easily run out of stack space, 1572 especially on systems with limited memory or which expect to 1573 support large numbers of threads each with a small stack, and also 1574 because the error checking performed by Memcheck is more effective 1575 for heap-allocated data than for stack-allocated data. If you 1576 have to use this option, you may wish to consider rewriting your 1577 code to allocate on the heap rather than on the stack.</para> 1578 </listitem> 1579 </varlistentry> 1580 1581 <varlistentry id="opt.main-stacksize" xreflabel="--main-stacksize"> 1582 <term> 1583 <option><![CDATA[--main-stacksize=<number> 1584 [default: use current 'ulimit' value] ]]></option> 1585 </term> 1586 <listitem> 1587 <para>Specifies the size of the main thread's stack.</para> 1588 1589 <para>To simplify its memory management, Valgrind reserves all 1590 required space for the main thread's stack at startup. That 1591 means it needs to know the required stack size at 1592 startup.</para> 1593 1594 <para>By default, Valgrind uses the current "ulimit" value for 1595 the stack size, or 16 MB, whichever is lower. In many cases 1596 this gives a stack size in the range 8 to 16 MB, which almost 1597 never overflows for most applications.</para> 1598 1599 <para>If you need a larger total stack size, 1600 use <option>--main-stacksize</option> to specify it. Only set 1601 it as high as you need, since reserving far more space than you 1602 need (that is, hundreds of megabytes more than you need) 1603 constrains Valgrind's memory allocators and may reduce the total 1604 amount of memory that Valgrind can use. This is only really of 1605 significance on 32-bit machines.</para> 1606 1607 <para>On Linux, you may request a stack of size up to 2GB. 1608 Valgrind will stop with a diagnostic message if the stack cannot 1609 be allocated.</para> 1610 1611 <para><option>--main-stacksize</option> only affects the stack 1612 size for the program's initial thread. It has no bearing on the 1613 size of thread stacks, as Valgrind does not allocate 1614 those.</para> 1615 1616 <para>You may need to use both <option>--main-stacksize</option> 1617 and <option>--max-stackframe</option> together. It is important 1618 to understand that <option>--main-stacksize</option> sets the 1619 maximum total stack size, 1620 whilst <option>--max-stackframe</option> specifies the largest 1621 size of any one stack frame. You will have to work out 1622 the <option>--main-stacksize</option> value for yourself 1623 (usually, if your applications segfaults). But Valgrind will 1624 tell you the needed <option>--max-stackframe</option> size, if 1625 necessary.</para> 1626 1627 <para>As discussed further in the description 1628 of <option>--max-stackframe</option>, a requirement for a large 1629 stack is a sign of potential portability problems. You are best 1630 advised to place all large data in heap-allocated memory.</para> 1631 </listitem> 1632 </varlistentry> 1633 1634 <varlistentry id="opt.max-threads" xreflabel="--max-threads"> 1635 <term> 1636 <option><![CDATA[--max-threads=<number> [default: 500] ]]></option> 1637 </term> 1638 <listitem> 1639 <para>By default, Valgrind can handle to up to 500 threads. 1640 Occasionally, that number is too small. Use this option to 1641 provide a different limit. E.g. 1642 <computeroutput>--max-threads=3000</computeroutput>. 1643 </para> 1644 </listitem> 1645 </varlistentry> 1646 1647 </variablelist> 1648 <!-- end of xi:include in the manpage --> 1649 1650 </sect2> 1651 1652 1653 <sect2 id="manual-core.mallocopts" xreflabel="malloc-related Options"> 1654 <title>malloc-related Options</title> 1655 1656 <!-- start of xi:include in the manpage --> 1657 <para id="malloc-related.opts.para">For tools that use their own version of 1658 <computeroutput>malloc</computeroutput> (e.g. Memcheck, 1659 Massif, Helgrind, DRD), the following options apply.</para> 1660 1661 <variablelist id="malloc-related.opts.list"> 1662 1663 <varlistentry id="opt.alignment" xreflabel="--alignment"> 1664 <term> 1665 <option><![CDATA[--alignment=<number> [default: 8 or 16, depending on the platform] ]]></option> 1666 </term> 1667 <listitem> 1668 <para>By default Valgrind's <function>malloc</function>, 1669 <function>realloc</function>, etc, return a block whose starting 1670 address is 8-byte aligned or 16-byte aligned (the value depends on the 1671 platform and matches the platform default). This option allows you to 1672 specify a different alignment. The supplied value must be greater 1673 than or equal to the default, less than or equal to 4096, and must be 1674 a power of two.</para> 1675 </listitem> 1676 </varlistentry> 1677 1678 <varlistentry id="opt.redzone-size" xreflabel="--redzone-size"> 1679 <term> 1680 <option><![CDATA[--redzone-size=<number> [default: depends on the tool] ]]></option> 1681 </term> 1682 <listitem> 1683 <para> Valgrind's <function>malloc, realloc,</function> etc, add 1684 padding blocks before and after each heap block allocated by the 1685 program being run. Such padding blocks are called redzones. The 1686 default value for the redzone size depends on the tool. For 1687 example, Memcheck adds and protects a minimum of 16 bytes before 1688 and after each block allocated by the client. This allows it to 1689 detect block underruns or overruns of up to 16 bytes. 1690 </para> 1691 <para>Increasing the redzone size makes it possible to detect 1692 overruns of larger distances, but increases the amount of memory 1693 used by Valgrind. Decreasing the redzone size will reduce the 1694 memory needed by Valgrind but also reduces the chances of 1695 detecting over/underruns, so is not recommended.</para> 1696 </listitem> 1697 </varlistentry> 1698 1699 <varlistentry id="opt.xtree-memory" xreflabel="--xtree-memory"> 1700 <term> 1701 <option><![CDATA[--xtree-memory=none|allocs|full [none] ]]></option> 1702 </term> 1703 <listitem> 1704 <para> Tools replacing Valgrind's <function>malloc, 1705 realloc,</function> etc, can optionally produce an execution 1706 tree detailing which piece of code is responsible for heap 1707 memory usage. See <xref linkend="manual-core.xtree"/> 1708 for a detailed explanation about execution trees. </para> 1709 1710 <para> When set to <varname>none</varname>, no memory execution 1711 tree is produced.</para> 1712 1713 <para> When set to <varname>allocs</varname>, the memory 1714 execution tree gives the current number of allocated bytes and 1715 the current number of allocated blocks. </para> 1716 1717 <para> When set to <varname>full</varname>, the memory execution 1718 tree gives 6 different measurements : the current number of 1719 allocated bytes and blocks (same values as 1720 for <varname>allocs</varname>), the total number of allocated 1721 bytes and blocks, the total number of freed bytes and 1722 blocks.</para> 1723 1724 <para>Note that the overhead in cpu and memory to produce 1725 an xtree depends on the tool. The overhead in cpu is small for 1726 the value <varname>allocs</varname>, as the information needed 1727 to produce this report is maintained in any case by the tool. 1728 For massif and helgrind, specifying <varname>full</varname> 1729 implies to capture a stack trace for each free operation, 1730 while normally these tools only capture an allocation stack 1731 trace. For memcheck, the cpu overhead for the 1732 value <varname>full</varname> is small, as this can only be 1733 used in combination with 1734 <option>--keep-stacktraces=alloc-and-free</option> or 1735 <option>--keep-stacktraces=alloc-then-free</option>, which 1736 already records a stack trace for each free operation. The 1737 memory overhead varies between 5 and 10 words per unique 1738 stacktrace in the xtree, plus the memory needed to record the 1739 stack trace for the free operations, if needed specifically 1740 for the xtree. 1741 </para> 1742 </listitem> 1743 </varlistentry> 1744 1745 <varlistentry id="opt.xtree-memory-file" xreflabel="--xtree-memory-file"> 1746 <term> 1747 <option><![CDATA[--xtree-memory-file=<filename> [default: 1748 xtmemory.kcg.%p] ]]></option> 1749 </term> 1750 <listitem> 1751 <para>Specifies that Valgrind should produce the xtree memory 1752 report in the specified file. Any <option>%p</option> or 1753 <option>%q</option> sequences appearing in the filename are expanded 1754 in exactly the same way as they are for <option>--log-file</option>. 1755 See the description of <xref linkend="opt.log-file"/> 1756 for details. </para> 1757 <para>If the filename contains the extension <option>.ms</option>, 1758 then the produced file format will be a massif output file format. 1759 If the filename contains the extension <option>.kcg</option> 1760 or no extension is provided or recognised, 1761 then the produced file format will be a callgrind output format.</para> 1762 <para>See <xref linkend="manual-core.xtree"/> 1763 for a detailed explanation about execution trees formats. </para> 1764 </listitem> 1765 </varlistentry> 1766 1767 </variablelist> 1768 <!-- end of xi:include in the manpage --> 1769 1770 </sect2> 1771 1772 1773 <sect2 id="manual-core.rareopts" xreflabel="Uncommon Options"> 1774 <title>Uncommon Options</title> 1775 1776 <!-- start of xi:include in the manpage --> 1777 <para id="uncommon.opts.para">These options apply to all tools, as they 1778 affect certain obscure workings of the Valgrind core. Most people won't 1779 need to use them.</para> 1780 1781 <variablelist id="uncommon.opts.list"> 1782 1783 <varlistentry id="opt.smc-check" xreflabel="--smc-check"> 1784 <term> 1785 <option><![CDATA[--smc-check=<none|stack|all|all-non-file> 1786 [default: all-non-file for x86/amd64/s390x, stack for other archs] ]]></option> 1787 </term> 1788 <listitem> 1789 <para>This option controls Valgrind's detection of self-modifying 1790 code. If no checking is done, when a program executes some code, then 1791 overwrites it with new code, and executes the new code, Valgrind will 1792 continue to execute the translations it made for the old code. This 1793 will likely lead to incorrect behaviour and/or crashes.</para> 1794 <para>For "modern" architectures -- anything that's not x86, 1795 amd64 or s390x -- the default is <varname>stack</varname>. 1796 This is because a correct program must take explicit action 1797 to reestablish D-I cache coherence following code 1798 modification. Valgrind observes and honours such actions, 1799 with the result that self-modifying code is transparently 1800 handled with zero extra cost.</para> 1801 <para>For x86, amd64 and s390x, the program is not required to 1802 notify the hardware of required D-I coherence syncing. Hence 1803 the default is <varname>all-non-file</varname>, which covers 1804 the normal case of generating code into an anonymous 1805 (non-file-backed) mmap'd area.</para> 1806 <para>The meanings of the four available settings are as 1807 follows. No detection (<varname>none</varname>), 1808 detect self-modifying code 1809 on the stack (which is used by GCC to implement nested 1810 functions) (<varname>stack</varname>), detect self-modifying code 1811 everywhere (<varname>all</varname>), and detect 1812 self-modifying code everywhere except in file-backed 1813 mappings (<varname>all-non-file</varname>).</para> 1814 <para>Running with <varname>all</varname> will slow Valgrind 1815 down noticeably. Running with <varname>none</varname> will 1816 rarely speed things up, since very little code gets 1817 dynamically generated in most programs. The 1818 <function>VALGRIND_DISCARD_TRANSLATIONS</function> client 1819 request is an alternative to <option>--smc-check=all</option> 1820 and <option>--smc-check=all-non-file</option> 1821 that requires more programmer effort but allows Valgrind to run 1822 your program faster, by telling it precisely when translations 1823 need to be re-made. 1824 <!-- commented out because it causes broken links in the man page 1825 ; see <xref 1826 linkend="manual-core-adv.clientreq"/> for more details. 1827 --> 1828 </para> 1829 <para><option>--smc-check=all-non-file</option> provides a 1830 cheaper but more limited version 1831 of <option>--smc-check=all</option>. It adds checks to any 1832 translations that do not originate from file-backed memory 1833 mappings. Typical applications that generate code, for example 1834 JITs in web browsers, generate code into anonymous mmaped areas, 1835 whereas the "fixed" code of the browser always lives in 1836 file-backed mappings. <option>--smc-check=all-non-file</option> 1837 takes advantage of this observation, limiting the overhead of 1838 checking to code which is likely to be JIT generated.</para> 1839 </listitem> 1840 </varlistentry> 1841 1842 <varlistentry id="opt.read-inline-info" xreflabel="--read-inline-info"> 1843 <term> 1844 <option><![CDATA[--read-inline-info=<yes|no> [default: see below] ]]></option> 1845 </term> 1846 <listitem> 1847 <para>When enabled, Valgrind will read information about inlined 1848 function calls from DWARF3 debug info. This slows Valgrind 1849 startup and makes it use more memory (typically for each inlined 1850 piece of code, 6 words and space for the function name), but it 1851 results in more descriptive stacktraces. For the 3.10.0 1852 release, this functionality is enabled by default only for Linux, 1853 Android and Solaris targets and only for the tools Memcheck, Helgrind 1854 and DRD. Here is an example of some stacktraces with 1855 <option>--read-inline-info=no</option>: 1856 </para> 1857 <programlisting><![CDATA[ 1858 ==15380== Conditional jump or move depends on uninitialised value(s) 1859 ==15380== at 0x80484EA: main (inlinfo.c:6) 1860 ==15380== 1861 ==15380== Conditional jump or move depends on uninitialised value(s) 1862 ==15380== at 0x8048550: fun_noninline (inlinfo.c:6) 1863 ==15380== by 0x804850E: main (inlinfo.c:34) 1864 ==15380== 1865 ==15380== Conditional jump or move depends on uninitialised value(s) 1866 ==15380== at 0x8048520: main (inlinfo.c:6) 1867 ]]></programlisting> 1868 <para>And here are the same errors with 1869 <option>--read-inline-info=yes</option>:</para> 1870 <programlisting><![CDATA[ 1871 ==15377== Conditional jump or move depends on uninitialised value(s) 1872 ==15377== at 0x80484EA: fun_d (inlinfo.c:6) 1873 ==15377== by 0x80484EA: fun_c (inlinfo.c:14) 1874 ==15377== by 0x80484EA: fun_b (inlinfo.c:20) 1875 ==15377== by 0x80484EA: fun_a (inlinfo.c:26) 1876 ==15377== by 0x80484EA: main (inlinfo.c:33) 1877 ==15377== 1878 ==15377== Conditional jump or move depends on uninitialised value(s) 1879 ==15377== at 0x8048550: fun_d (inlinfo.c:6) 1880 ==15377== by 0x8048550: fun_noninline (inlinfo.c:41) 1881 ==15377== by 0x804850E: main (inlinfo.c:34) 1882 ==15377== 1883 ==15377== Conditional jump or move depends on uninitialised value(s) 1884 ==15377== at 0x8048520: fun_d (inlinfo.c:6) 1885 ==15377== by 0x8048520: main (inlinfo.c:35) 1886 ]]></programlisting> 1887 </listitem> 1888 </varlistentry> 1889 1890 <varlistentry id="opt.read-var-info" xreflabel="--read-var-info"> 1891 <term> 1892 <option><![CDATA[--read-var-info=<yes|no> [default: no] ]]></option> 1893 </term> 1894 <listitem> 1895 <para>When enabled, Valgrind will read information about 1896 variable types and locations from DWARF3 debug info. 1897 This slows Valgrind startup significantly and makes it use significantly 1898 more memory, but for the tools that can take advantage of it (Memcheck, 1899 Helgrind, DRD) it can result in more precise error messages. For example, 1900 here are some standard errors issued by Memcheck:</para> 1901 <programlisting><![CDATA[ 1902 ==15363== Uninitialised byte(s) found during client check request 1903 ==15363== at 0x80484A9: croak (varinfo1.c:28) 1904 ==15363== by 0x8048544: main (varinfo1.c:55) 1905 ==15363== Address 0x80497f7 is 7 bytes inside data symbol "global_i2" 1906 ==15363== 1907 ==15363== Uninitialised byte(s) found during client check request 1908 ==15363== at 0x80484A9: croak (varinfo1.c:28) 1909 ==15363== by 0x8048550: main (varinfo1.c:56) 1910 ==15363== Address 0xbea0d0cc is on thread 1's stack 1911 ==15363== in frame #1, created by main (varinfo1.c:45) 1912 ]]></programlisting> 1913 1914 <para>And here are the same errors with 1915 <option>--read-var-info=yes</option>:</para> 1916 1917 <programlisting><![CDATA[ 1918 ==15370== Uninitialised byte(s) found during client check request 1919 ==15370== at 0x80484A9: croak (varinfo1.c:28) 1920 ==15370== by 0x8048544: main (varinfo1.c:55) 1921 ==15370== Location 0x80497f7 is 0 bytes inside global_i2[7], 1922 ==15370== a global variable declared at varinfo1.c:41 1923 ==15370== 1924 ==15370== Uninitialised byte(s) found during client check request 1925 ==15370== at 0x80484A9: croak (varinfo1.c:28) 1926 ==15370== by 0x8048550: main (varinfo1.c:56) 1927 ==15370== Location 0xbeb4a0cc is 0 bytes inside local var "local" 1928 ==15370== declared at varinfo1.c:46, in frame #1 of thread 1 1929 ]]></programlisting> 1930 </listitem> 1931 </varlistentry> 1932 1933 <varlistentry id="opt.vgdb-poll" xreflabel="--vgdb-poll"> 1934 <term> 1935 <option><![CDATA[--vgdb-poll=<number> [default: 5000] ]]></option> 1936 </term> 1937 <listitem> 1938 <para> As part of its main loop, the Valgrind scheduler will 1939 poll to check if some activity (such as an external command or 1940 some input from a gdb) has to be handled by gdbserver. This 1941 activity poll will be done after having run the given number of 1942 basic blocks (or slightly more than the given number of basic 1943 blocks). This poll is quite cheap so the default value is set 1944 relatively low. You might further decrease this value if vgdb 1945 cannot use ptrace system call to interrupt Valgrind if all 1946 threads are (most of the time) blocked in a system call. 1947 </para> 1948 </listitem> 1949 </varlistentry> 1950 1951 <varlistentry id="opt.vgdb-shadow-registers" xreflabel="--vgdb-shadow-registers"> 1952 <term> 1953 <option><![CDATA[--vgdb-shadow-registers=no|yes [default: no] ]]></option> 1954 </term> 1955 <listitem> 1956 <para> When activated, gdbserver will expose the Valgrind shadow registers 1957 to GDB. With this, the value of the Valgrind shadow registers can be examined 1958 or changed using GDB. Exposing shadow registers only works with GDB version 1959 7.1 or later. 1960 </para> 1961 </listitem> 1962 </varlistentry> 1963 1964 <varlistentry id="opt.vgdb-prefix" xreflabel="--vgdb-prefix"> 1965 <term> 1966 <option><![CDATA[--vgdb-prefix=<prefix> [default: /tmp/vgdb-pipe] ]]></option> 1967 </term> 1968 <listitem> 1969 <para> To communicate with gdb/vgdb, the Valgrind gdbserver 1970 creates 3 files (2 named FIFOs and a mmap shared memory 1971 file). The prefix option controls the directory and prefix for 1972 the creation of these files. 1973 </para> 1974 </listitem> 1975 </varlistentry> 1976 1977 <varlistentry id="opt.run-libc-freeres" xreflabel="--run-libc-freeres"> 1978 <term> 1979 <option><![CDATA[--run-libc-freeres=<yes|no> [default: yes] ]]></option> 1980 </term> 1981 <listitem> 1982 <para>This option is only relevant when running Valgrind on Linux.</para> 1983 1984 <para>The GNU C library (<function>libc.so</function>), which is 1985 used by all programs, may allocate memory for its own uses. 1986 Usually it doesn't bother to free that memory when the program 1987 ends—there would be no point, since the Linux kernel reclaims 1988 all process resources when a process exits anyway, so it would 1989 just slow things down.</para> 1990 1991 <para>The glibc authors realised that this behaviour causes leak 1992 checkers, such as Valgrind, to falsely report leaks in glibc, when 1993 a leak check is done at exit. In order to avoid this, they 1994 provided a routine called <function>__libc_freeres</function> 1995 specifically to make glibc release all memory it has allocated. 1996 Memcheck therefore tries to run 1997 <function>__libc_freeres</function> at exit.</para> 1998 1999 <para>Unfortunately, in some very old versions of glibc, 2000 <function>__libc_freeres</function> is sufficiently buggy to cause 2001 segmentation faults. This was particularly noticeable on Red Hat 2002 7.1. So this option is provided in order to inhibit the run of 2003 <function>__libc_freeres</function>. If your program seems to run 2004 fine on Valgrind, but segfaults at exit, you may find that 2005 <option>--run-libc-freeres=no</option> fixes that, although at the 2006 cost of possibly falsely reporting space leaks in 2007 <filename>libc.so</filename>.</para> 2008 </listitem> 2009 </varlistentry> 2010 2011 <varlistentry id="opt.run-cxx-freeres" xreflabel="--run-cxx-freeres"> 2012 <term> 2013 <option><![CDATA[--run-cxx-freeres=<yes|no> [default: yes] ]]></option> 2014 </term> 2015 <listitem> 2016 <para>This option is only relevant when running Valgrind on Linux 2017 or Solaris C++ programs.</para> 2018 2019 <para>The GNU Standard C++ library (<function>libstdc++.so</function>), 2020 which is used by all C++ programs compiled with g++, may allocate memory 2021 for its own uses. Usually it doesn't bother to free that memory when 2022 the program ends—there would be no point, since the kernel reclaims 2023 all process resources when a process exits anyway, so it would 2024 just slow things down.</para> 2025 2026 <para>The gcc authors realised that this behaviour causes leak 2027 checkers, such as Valgrind, to falsely report leaks in libstdc++, when 2028 a leak check is done at exit. In order to avoid this, they 2029 provided a routine called <function>__gnu_cxx::__freeres</function> 2030 specifically to make libstdc++ release all memory it has allocated. 2031 Memcheck therefore tries to run 2032 <function>__gnu_cxx::__freeres</function> at exit.</para> 2033 2034 <para>For the sake of flexibility and unforeseen problems with 2035 <function>__gnu_cxx::__freeres</function>, option 2036 <option>--run-cxx-freeres=no</option> exists, 2037 although at the cost of possibly falsely reporting space leaks in 2038 <filename>libstdc++.so</filename>.</para> 2039 </listitem> 2040 </varlistentry> 2041 2042 <varlistentry id="opt.sim-hints" xreflabel="--sim-hints"> 2043 <term> 2044 <option><![CDATA[--sim-hints=hint1,hint2,... ]]></option> 2045 </term> 2046 <listitem> 2047 <para>Pass miscellaneous hints to Valgrind which slightly modify 2048 the simulated behaviour in nonstandard or dangerous ways, possibly 2049 to help the simulation of strange features. By default no hints 2050 are enabled. Use with caution! Currently known hints are:</para> 2051 2052 <itemizedlist> 2053 <listitem> 2054 <para><option>lax-ioctls: </option> Be very lax about ioctl 2055 handling; the only assumption is that the size is 2056 correct. Doesn't require the full buffer to be initialised 2057 when writing. Without this, using some device drivers with a 2058 large number of strange ioctl commands becomes very 2059 tiresome.</para> 2060 </listitem> 2061 2062 <listitem> 2063 <para><option>fuse-compatible: </option> Enable special 2064 handling for certain system calls that may block in a FUSE 2065 file-system. This may be necessary when running Valgrind 2066 on a multi-threaded program that uses one thread to manage 2067 a FUSE file-system and another thread to access that 2068 file-system. 2069 </para> 2070 </listitem> 2071 2072 <listitem> 2073 <para><option>enable-outer: </option> Enable some special 2074 magic needed when the program being run is itself 2075 Valgrind.</para> 2076 </listitem> 2077 2078 <listitem> 2079 <para><option>no-inner-prefix: </option> Disable printing 2080 a prefix <option>></option> in front of each stdout or 2081 stderr output line in an inner Valgrind being run by an 2082 outer Valgrind. This is useful when running Valgrind 2083 regression tests in an outer/inner setup. Note that the 2084 prefix <option>></option> will always be printed in 2085 front of the inner debug logging lines.</para> 2086 </listitem> 2087 <listitem> 2088 <para><option>no-nptl-pthread-stackcache: </option> 2089 This hint is only relevant when running Valgrind on Linux.</para> 2090 2091 <para>The GNU glibc pthread library 2092 (<function>libpthread.so</function>), which is used by 2093 pthread programs, maintains a cache of pthread stacks. 2094 When a pthread terminates, the memory used for the pthread 2095 stack and some thread local storage related data structure 2096 are not always directly released. This memory is kept in 2097 a cache (up to a certain size), and is re-used if a new 2098 thread is started.</para> 2099 2100 <para>This cache causes the helgrind tool to report some 2101 false positive race condition errors on this cached 2102 memory, as helgrind does not understand the internal glibc 2103 cache synchronisation primitives. So, when using helgrind, 2104 disabling the cache helps to avoid false positive race 2105 conditions, in particular when using thread local storage 2106 variables (e.g. variables using the 2107 <function>__thread</function> qualifier).</para> 2108 2109 <para>When using the memcheck tool, disabling the cache 2110 ensures the memory used by glibc to handle __thread 2111 variables is directly released when a thread 2112 terminates.</para> 2113 2114 <para>Note: Valgrind disables the cache using some internal 2115 knowledge of the glibc stack cache implementation and by 2116 examining the debug information of the pthread 2117 library. This technique is thus somewhat fragile and might 2118 not work for all glibc versions. This has been successfully 2119 tested with various glibc versions (e.g. 2.11, 2.16, 2.18) 2120 on various platforms.</para> 2121 </listitem> 2122 <listitem> 2123 <para><option>lax-doors: </option> (Solaris only) Be very lax 2124 about door syscall handling over unrecognised door file 2125 descriptors. Does not require that full buffer is initialised 2126 when writing. Without this, programs using libdoor(3LIB) 2127 functionality with completely proprietary semantics may report 2128 large number of false positives.</para> 2129 </listitem> 2130 <listitem> 2131 <para><option>fallback-llsc: </option>(MIPS and ARM64 only): Enables 2132 an alternative implementation of Load-Linked (LL) and 2133 Store-Conditional (SC) instructions. The standard implementation 2134 gives more correct behaviour, but can cause indefinite looping on 2135 certain processor implementations that are intolerant of extra 2136 memory references between LL and SC. So far this is known only to 2137 happen on Cavium 3 cores. 2138 2139 You should not need to use this flag, since the relevant cores are 2140 detected at startup and the alternative implementation is 2141 automatically enabled if necessary. There is no equivalent 2142 anti-flag: you cannot force-disable the alternative 2143 implementation, if it is automatically enabled. 2144 2145 The underlying problem exists because the "standard" 2146 implementation of LL and SC is done by copying through LL and SC 2147 instructions into the instrumented code. However, tools may 2148 insert extra instrumentation memory references in between the LL 2149 and SC instructions. These memory references are not present in 2150 the original uninstrumented code, and their presence in the 2151 instrumented code can cause the SC instructions to persistently 2152 fail, leading to indefinite looping in LL-SC blocks. 2153 2154 The alternative implementation gives correct behaviour of LL and 2155 SC instructions between threads in a process, up to and including 2156 the ABA scenario. It also gives correct behaviour between a 2157 Valgrinded thread and a non-Valgrinded thread running in a 2158 different process, that communicate via shared memory, but only up 2159 to and including correct CAS behaviour -- in this case the ABA 2160 scenario may not be correctly handled. 2161 </para> 2162 </listitem> 2163 </itemizedlist> 2164 </listitem> 2165 </varlistentry> 2166 2167 <varlistentry id="opt.fair-sched" xreflabel="--fair-sched"> 2168 <term> 2169 <option><![CDATA[--fair-sched=<no|yes|try> [default: no] ]]></option> 2170 </term> 2171 2172 <listitem> <para>The <option>--fair-sched</option> option controls 2173 the locking mechanism used by Valgrind to serialise thread 2174 execution. The locking mechanism controls the way the threads 2175 are scheduled, and different settings give different trade-offs 2176 between fairness and performance. For more details about the 2177 Valgrind thread serialisation scheme and its impact on 2178 performance and thread scheduling, see 2179 <xref linkend="&vg-pthreads-perf-sched-id;"/>.</para> 2180 2181 <itemizedlist> 2182 <listitem> <para>The value <option>--fair-sched=yes</option> 2183 activates a fair scheduler. In short, if multiple threads are 2184 ready to run, the threads will be scheduled in a round robin 2185 fashion. This mechanism is not available on all platforms or 2186 Linux versions. If not available, 2187 using <option>--fair-sched=yes</option> will cause Valgrind to 2188 terminate with an error.</para> 2189 <para>You may find this setting improves overall 2190 responsiveness if you are running an interactive 2191 multithreaded program, for example a web browser, on 2192 Valgrind.</para> 2193 </listitem> 2194 2195 <listitem> <para>The value <option>--fair-sched=try</option> 2196 activates fair scheduling if available on the 2197 platform. Otherwise, it will automatically fall back 2198 to <option>--fair-sched=no</option>.</para> 2199 </listitem> 2200 2201 <listitem> <para>The value <option>--fair-sched=no</option> activates 2202 a scheduler which does not guarantee fairness 2203 between threads ready to run, but which in general gives the 2204 highest performance.</para> 2205 </listitem> 2206 </itemizedlist> 2207 </listitem> 2208 2209 </varlistentry> 2210 2211 <varlistentry id="opt.kernel-variant" xreflabel="--kernel-variant"> 2212 <term> 2213 <option>--kernel-variant=variant1,variant2,...</option> 2214 </term> 2215 <listitem> 2216 <para>Handle system calls and ioctls arising from minor variants 2217 of the default kernel for this platform. This is useful for 2218 running on hacked kernels or with kernel modules which support 2219 nonstandard ioctls, for example. Use with caution. If you don't 2220 understand what this option does then you almost certainly don't 2221 need it. Currently known variants are:</para> 2222 <itemizedlist> 2223 <listitem> 2224 <para><option>bproc</option>: support the 2225 <function>sys_broc</function> system call on x86. This is for 2226 running on BProc, which is a minor variant of standard Linux which 2227 is sometimes used for building clusters. 2228 </para> 2229 </listitem> 2230 <listitem> 2231 <para><option>android-no-hw-tls</option>: some 2232 versions of the Android emulator for ARM do not provide a 2233 hardware TLS (thread-local state) register, and Valgrind 2234 crashes at startup. Use this variant to select software 2235 support for TLS. 2236 </para> 2237 </listitem> 2238 <listitem> 2239 <para><option>android-gpu-sgx5xx</option>: use this to 2240 support handling of proprietary ioctls for the PowerVR SGX 2241 5XX series of GPUs on Android devices. Failure to select 2242 this does not cause stability problems, but may cause 2243 Memcheck to report false errors after the program performs 2244 GPU-specific ioctls. 2245 </para> 2246 </listitem> 2247 <listitem> 2248 <para><option>android-gpu-adreno3xx</option>: similarly, use 2249 this to support handling of proprietary ioctls for the 2250 Qualcomm Adreno 3XX series of GPUs on Android devices. 2251 </para> 2252 </listitem> 2253 </itemizedlist> 2254 </listitem> 2255 </varlistentry> 2256 2257 <varlistentry id="opt.merge-recursive-frames" xreflabel="--merge-recursive-frames"> 2258 <term> 2259 <option><![CDATA[--merge-recursive-frames=<number> [default: 0] ]]></option> 2260 </term> 2261 <listitem> 2262 <para>Some recursive algorithms, for example balanced binary 2263 tree implementations, create many different stack traces, each 2264 containing cycles of calls. A cycle is defined as two identical 2265 program counter values separated by zero or more other program 2266 counter values. Valgrind may then use a lot of memory to store 2267 all these stack traces. This is a poor use of memory 2268 considering that such stack traces contain repeated 2269 uninteresting recursive calls instead of more interesting 2270 information such as the function that has initiated the 2271 recursive call. 2272 </para> 2273 <para>The option <option>--merge-recursive-frames=<number></option> 2274 instructs Valgrind to detect and merge recursive call cycles 2275 having a size of up to <option><number></option> 2276 frames. When such a cycle is detected, Valgrind records the 2277 cycle in the stack trace as a unique program counter. 2278 </para> 2279 <para> 2280 The value 0 (the default) causes no recursive call merging. 2281 A value of 1 will cause stack traces of simple recursive algorithms 2282 (for example, a factorial implementation) to be collapsed. 2283 A value of 2 will usually be needed to collapse stack traces produced 2284 by recursive algorithms such as binary trees, quick sort, etc. 2285 Higher values might be needed for more complex recursive algorithms. 2286 </para> 2287 <para>Note: recursive calls are detected by analysis of program 2288 counter values. They are not detected by looking at function 2289 names.</para> 2290 </listitem> 2291 </varlistentry> 2292 2293 <varlistentry id="opt.num-transtab-sectors" xreflabel="--num-transtab-sectors"> 2294 <term> 2295 <option><![CDATA[--num-transtab-sectors=<number> [default: 6 2296 for Android platforms, 16 for all others] ]]></option> 2297 </term> 2298 <listitem> 2299 <para>Valgrind translates and instruments your program's machine 2300 code in small fragments (basic blocks). The translations are stored in a 2301 translation cache that is divided into a number of sections 2302 (sectors). If the cache is full, the sector containing the 2303 oldest translations is emptied and reused. If these old 2304 translations are needed again, Valgrind must re-translate and 2305 re-instrument the corresponding machine code, which is 2306 expensive. If the "executed instructions" working set of a 2307 program is big, increasing the number of sectors may improve 2308 performance by reducing the number of re-translations needed. 2309 Sectors are allocated on demand. Once allocated, a sector can 2310 never be freed, and occupies considerable space, depending on the tool 2311 and the value of <option>--avg-transtab-entry-size</option> 2312 (about 40 MB per sector for Memcheck). Use the 2313 option <option>--stats=yes</option> to obtain precise 2314 information about the memory used by a sector and the allocation 2315 and recycling of sectors.</para> 2316 </listitem> 2317 </varlistentry> 2318 2319 <varlistentry id="opt.avg-transtab-entry-size" xreflabel="--avg-transtab-entry-size"> 2320 <term> 2321 <option><![CDATA[--avg-transtab-entry-size=<number> [default: 0, 2322 meaning use tool provided default] ]]></option> 2323 </term> 2324 <listitem> 2325 <para>Average size of translated basic block. This average size 2326 is used to dimension the size of a sector. 2327 Each tool provides a default value to be used. 2328 If this default value is too small, the translation sectors 2329 will become full too quickly. If this default value is too big, 2330 a significant part of the translation sector memory will be unused. 2331 Note that the average size of a basic block translation depends 2332 on the tool, and might depend on tool options. For example, 2333 the memcheck option <option>--track-origins=yes</option> 2334 increases the size of the basic block translations. 2335 Use <option>--avg-transtab-entry-size</option> to tune the size of the 2336 sectors, either to gain memory or to avoid too many retranslations. 2337 </para> 2338 </listitem> 2339 </varlistentry> 2340 2341 <varlistentry id="opt.aspace-minaddr" xreflabel="----aspace-minaddr"> 2342 <term> 2343 <option><![CDATA[--aspace-minaddr=<address> [default: depends 2344 on the platform] ]]></option> 2345 </term> 2346 <listitem> 2347 <para>To avoid potential conflicts with some system libraries, 2348 Valgrind does not use the address space 2349 below <option>--aspace-minaddr</option> value, keeping it 2350 reserved in case a library specifically requests memory in this 2351 region. So, some "pessimistic" value is guessed by Valgrind 2352 depending on the platform. On linux, by default, Valgrind avoids 2353 using the first 64MB even if typically there is no conflict in 2354 this complete zone. You can use the 2355 option <option>--aspace-minaddr</option> to have your memory 2356 hungry application benefitting from more of this lower memory. 2357 On the other hand, if you encounter a conflict, increasing 2358 aspace-minaddr value might solve it. Conflicts will typically 2359 manifest themselves with mmap failures in the low range of the 2360 address space. The 2361 provided <computeroutput>address</computeroutput> must be page 2362 aligned and must be equal or bigger to 0x1000 (4KB). To find the 2363 default value on your platform, do something such as 2364 <computeroutput>valgrind -d -d date 2>&1 | grep -i minaddr</computeroutput>. 2365 Values lower than 0x10000 (64KB) are known to create problems 2366 on some distributions. 2367 </para> 2368 </listitem> 2369 </varlistentry> 2370 2371 <varlistentry id="opt.valgrind-stacksize" xreflabel="----valgrind-stacksize"> 2372 <term> 2373 <option><![CDATA[--valgrind-stacksize=<number> [default: 1MB] ]]></option> 2374 </term> 2375 <listitem> 2376 <para>For each thread, Valgrind needs its own 'private' stack. 2377 The default size for these stacks is largely dimensioned, and so 2378 should be sufficient in most cases. In case the size is too small, 2379 Valgrind will segfault. Before segfaulting, a warning might be produced 2380 by Valgrind when approaching the limit. 2381 </para> 2382 <para> 2383 Use the option <option>--valgrind-stacksize</option> if such an (unlikely) 2384 warning is produced, or Valgrind dies due to a segmentation violation. 2385 Such segmentation violations have been seen when demangling huge C++ 2386 symbols. 2387 </para> 2388 <para>If your application uses many threads and needs a lot of memory, you can 2389 gain some memory by reducing the size of these Valgrind stacks using 2390 the option <option>--valgrind-stacksize</option>. 2391 </para> 2392 </listitem> 2393 </varlistentry> 2394 2395 <varlistentry id="opt.show-emwarns" xreflabel="--show-emwarns"> 2396 <term> 2397 <option><![CDATA[--show-emwarns=<yes|no> [default: no] ]]></option> 2398 </term> 2399 <listitem> 2400 <para>When enabled, Valgrind will emit warnings about its CPU 2401 emulation in certain cases. These are usually not 2402 interesting.</para> 2403 </listitem> 2404 </varlistentry> 2405 2406 <varlistentry id="opt.require-text-symbol" 2407 xreflabel="--require-text-symbol"> 2408 <term> 2409 <option><![CDATA[--require-text-symbol=:sonamepatt:fnnamepatt]]></option> 2410 </term> 2411 <listitem> 2412 <para>When a shared object whose soname 2413 matches <varname>sonamepatt</varname> is loaded into the 2414 process, examine all the text symbols it exports. If none of 2415 those match <varname>fnnamepatt</varname>, print an error 2416 message and abandon the run. This makes it possible to ensure 2417 that the run does not continue unless a given shared object 2418 contains a particular function name. 2419 </para> 2420 <para> 2421 Both <varname>sonamepatt</varname> and 2422 <varname>fnnamepatt</varname> can be written using the usual 2423 <varname>?</varname> and <varname>*</varname> wildcards. For 2424 example: <varname>":*libc.so*:foo?bar"</varname>. You may use 2425 characters other than a colon to separate the two patterns. It 2426 is only important that the first character and the separator 2427 character are the same. For example, the above example could 2428 also be written <varname>"Q*libc.so*Qfoo?bar"</varname>. 2429 Multiple <varname> --require-text-symbol</varname> flags are 2430 allowed, in which case shared objects that are loaded into 2431 the process will be checked against all of them. 2432 </para> 2433 <para> 2434 The purpose of this is to support reliable usage of marked-up 2435 libraries. For example, suppose we have a version of GCC's 2436 <varname>libgomp.so</varname> which has been marked up with 2437 annotations to support Helgrind. It is only too easy and 2438 confusing to load the wrong, un-annotated 2439 <varname>libgomp.so</varname> into the application. So the idea 2440 is: add a text symbol in the marked-up library, for 2441 example <varname>annotated_for_helgrind_3_6</varname>, and then 2442 give the flag 2443 <varname>--require-text-symbol=:*libgomp*so*:annotated_for_helgrind_3_6</varname> 2444 so that when <varname>libgomp.so</varname> is loaded, Valgrind 2445 scans its symbol table, and if the symbol isn't present the run 2446 is aborted, rather than continuing silently with the 2447 un-marked-up library. Note that you should put the entire flag 2448 in quotes to stop shells expanding up the <varname>*</varname> 2449 and <varname>?</varname> wildcards. 2450 </para> 2451 </listitem> 2452 </varlistentry> 2453 2454 <varlistentry id="opt.soname-synonyms" 2455 xreflabel="--soname-synonyms"> 2456 <term> 2457 <option><![CDATA[--soname-synonyms=syn1=pattern1,syn2=pattern2,...]]></option> 2458 </term> 2459 <listitem> 2460 <para>When a shared library is loaded, Valgrind checks for 2461 functions in the library that must be replaced or wrapped. For 2462 example, Memcheck replaces some string and memory functions 2463 (strchr, strlen, strcpy, memchr, memcpy, memmove, etc.) with its 2464 own versions. Such replacements are normally done only in shared 2465 libraries whose soname matches a predefined soname pattern (e.g. 2466 <varname>libc.so*</varname> on linux). By default, no 2467 replacement is done for a statically linked binary or for 2468 alternative libraries, except for the allocation functions 2469 (malloc, free, calloc, memalign, realloc, operator new, operator 2470 delete, etc.) Such allocation functions are intercepted by 2471 default in any shared library or in the executable if they are 2472 exported as global symbols. This means that if a replacement 2473 allocation library such as tcmalloc is found, its functions are 2474 also intercepted by default. 2475 2476 In some cases, the replacements allow 2477 <option>--soname-synonyms</option> to specify one additional 2478 synonym pattern, giving flexibility in the replacement. Or to 2479 prevent interception of all public allocation symbols.</para> 2480 2481 <para>Currently, this flexibility is only allowed for the 2482 malloc related functions, using the 2483 synonym <varname>somalloc</varname>. This synonym is usable for 2484 all tools doing standard replacement of malloc related functions 2485 (e.g. memcheck, massif, drd, helgrind, exp-dhat, exp-sgcheck). 2486 </para> 2487 2488 <itemizedlist> 2489 <listitem> 2490 2491 <para>Alternate malloc library: to replace the malloc 2492 related functions in a specific alternate library with 2493 soname <varname>mymalloclib.so</varname> (and not in any 2494 others), give the 2495 option <option>--soname-synonyms=somalloc=mymalloclib.so</option>. 2496 A pattern can be used to match multiple libraries sonames. 2497 For 2498 example, <option>--soname-synonyms=somalloc=*tcmalloc*</option> 2499 will match the soname of all variants of the tcmalloc 2500 library (native, debug, profiled, ... tcmalloc 2501 variants). </para> 2502 <para>Note: the soname of a elf shared library can be 2503 retrieved using the readelf utility. </para> 2504 2505 </listitem> 2506 2507 <listitem> 2508 <para>Replacements in a statically linked library are done 2509 by using the <varname>NONE</varname> pattern. For example, 2510 if you link with <varname>libtcmalloc.a</varname>, and only 2511 want to intercept the malloc related functions in the 2512 executable (and standard libraries) themselves, but not any 2513 other shared libraries, you can give the 2514 option <option>--soname-synonyms=somalloc=NONE</option>. 2515 Note that a NONE pattern will match the main executable and 2516 any shared library having no soname. </para> 2517 </listitem> 2518 2519 <listitem> 2520 <para>To run a "default" Firefox build for Linux, in which 2521 JEMalloc is linked in to the main executable, 2522 use <option>--soname-synonyms=somalloc=NONE</option>. 2523 </para> 2524 </listitem> 2525 2526 <listitem> 2527 <para>To only intercept allocation symbols in the default 2528 system libraries, but not in any other shared library or the 2529 executable defining public malloc or operator new related 2530 functions use a non-existing library name 2531 like <option>--soname-synonyms=somalloc=nouserintercepts</option> 2532 (where <varname>nouserintercepts</varname> can be any 2533 non-existing library name). 2534 </para> 2535 </listitem> 2536 2537 <listitem> 2538 <para>Shared library of the dynamic (runtime) linker is excluded from 2539 searching for global public symbols, such as those for the malloc 2540 related functions (identified by <varname>somalloc</varname> synonym). 2541 </para> 2542 </listitem> 2543 2544 </itemizedlist> 2545 </listitem> 2546 </varlistentry> 2547 2548 2549 </variablelist> 2550 <!-- end of xi:include in the manpage --> 2551 2552 </sect2> 2553 2554 2555 <sect2 id="manual-core.debugopts" xreflabel="Debugging Options"> 2556 <title>Debugging Options</title> 2557 2558 <!-- start of xi:include in the manpage --> 2559 <para id="debug.opts.para">There are also some options for debugging 2560 Valgrind itself. You shouldn't need to use them in the normal run of 2561 things. If you wish to see the list, use the 2562 <option>--help-debug</option> option.</para> 2563 2564 <para>If you wish to debug your program rather than debugging 2565 Valgrind itself, then you should use the options 2566 <option>--vgdb=yes</option> or <option>--vgdb=full</option>. 2567 </para> 2568 2569 <!-- end of xi:include in the manpage --> 2570 2571 </sect2> 2572 2573 2574 <sect2 id="manual-core.defopts" xreflabel="Setting Default Options"> 2575 <title>Setting Default Options</title> 2576 2577 <para>Note that Valgrind also reads options from three places:</para> 2578 2579 <orderedlist> 2580 <listitem> 2581 <para>The file <computeroutput>~/.valgrindrc</computeroutput></para> 2582 </listitem> 2583 2584 <listitem> 2585 <para>The environment variable 2586 <computeroutput>$VALGRIND_OPTS</computeroutput></para> 2587 </listitem> 2588 2589 <listitem> 2590 <para>The file <computeroutput>./.valgrindrc</computeroutput></para> 2591 </listitem> 2592 </orderedlist> 2593 2594 <para>These are processed in the given order, before the 2595 command-line options. Options processed later override those 2596 processed earlier; for example, options in 2597 <computeroutput>./.valgrindrc</computeroutput> will take 2598 precedence over those in 2599 <computeroutput>~/.valgrindrc</computeroutput>. 2600 </para> 2601 2602 <para>Please note that the <computeroutput>./.valgrindrc</computeroutput> 2603 file is ignored if it is not a regular file, or is marked as world writeable, 2604 or is not owned by the current user. This is because the 2605 <computeroutput>./.valgrindrc</computeroutput> can contain options that are 2606 potentially harmful or can be used by a local attacker to execute code under 2607 your user account. 2608 </para> 2609 2610 <para>Any tool-specific options put in 2611 <computeroutput>$VALGRIND_OPTS</computeroutput> or the 2612 <computeroutput>.valgrindrc</computeroutput> files should be 2613 prefixed with the tool name and a colon. For example, if you 2614 want Memcheck to always do leak checking, you can put the 2615 following entry in <literal>~/.valgrindrc</literal>:</para> 2616 2617 <programlisting><![CDATA[ 2618 --memcheck:leak-check=yes]]></programlisting> 2619 2620 <para>This will be ignored if any tool other than Memcheck is 2621 run. Without the <computeroutput>memcheck:</computeroutput> 2622 part, this will cause problems if you select other tools that 2623 don't understand 2624 <option>--leak-check=yes</option>.</para> 2625 2626 </sect2> 2627 2628 </sect1> 2629 2630 2631 2632 <sect1 id="manual-core.pthreads" xreflabel="Support for Threads"> 2633 <title>Support for Threads</title> 2634 2635 <para>Threaded programs are fully supported.</para> 2636 2637 <para>The main thing to point out with respect to threaded programs is 2638 that your program will use the native threading library, but Valgrind 2639 serialises execution so that only one (kernel) thread is running at a 2640 time. This approach avoids the horrible implementation problems of 2641 implementing a truly multithreaded version of Valgrind, but it does 2642 mean that threaded apps never use more than one CPU simultaneously, 2643 even if you have a multiprocessor or multicore machine.</para> 2644 2645 <para>Valgrind doesn't schedule the threads itself. It merely ensures 2646 that only one thread runs at once, using a simple locking scheme. The 2647 actual thread scheduling remains under control of the OS kernel. What 2648 this does mean, though, is that your program will see very different 2649 scheduling when run on Valgrind than it does when running normally. 2650 This is both because Valgrind is serialising the threads, and because 2651 the code runs so much slower than normal.</para> 2652 2653 <para>This difference in scheduling may cause your program to behave 2654 differently, if you have some kind of concurrency, critical race, 2655 locking, or similar, bugs. In that case you might consider using the 2656 tools Helgrind and/or DRD to track them down.</para> 2657 2658 <para>On Linux, Valgrind also supports direct use of the 2659 <computeroutput>clone</computeroutput> system call, 2660 <computeroutput>futex</computeroutput> and so on. 2661 <computeroutput>clone</computeroutput> is supported where either 2662 everything is shared (a thread) or nothing is shared (fork-like); partial 2663 sharing will fail. 2664 </para> 2665 2666 <!-- Referenced from both the manual and manpage --> 2667 <sect2 id="&vg-pthreads-perf-sched-id;" xreflabel="&vg-pthreads-perf-sched-label;"> 2668 <title>Scheduling and Multi-Thread Performance</title> 2669 2670 <para>A thread executes code only when it holds the abovementioned 2671 lock. After executing some number of instructions, the running thread 2672 will release the lock. All threads ready to run will then compete to 2673 acquire the lock.</para> 2674 2675 <para>The <option>--fair-sched</option> option controls the locking mechanism 2676 used to serialise thread execution.</para> 2677 2678 <para>The default pipe based locking mechanism 2679 (<option>--fair-sched=no</option>) is available on all 2680 platforms. Pipe based locking does not guarantee fairness between 2681 threads: it is quite likely that a thread that has just released the 2682 lock reacquires it immediately, even though other threads are ready to 2683 run. When using pipe based locking, different runs of the same 2684 multithreaded application might give very different thread 2685 scheduling.</para> 2686 2687 <para>An alternative locking mechanism, based on futexes, is available 2688 on some platforms. If available, it is activated 2689 by <option>--fair-sched=yes</option> or 2690 <option>--fair-sched=try</option>. Futex based locking ensures 2691 fairness (round-robin scheduling) between threads: if multiple threads 2692 are ready to run, the lock will be given to the thread which first 2693 requested the lock. Note that a thread which is blocked in a system 2694 call (e.g. in a blocking read system call) has not (yet) requested the 2695 lock: such a thread requests the lock only after the system call is 2696 finished.</para> 2697 2698 <para> The fairness of the futex based locking produces better 2699 reproducibility of thread scheduling for different executions of a 2700 multithreaded application. This better reproducibility is particularly 2701 helpful when using Helgrind or DRD.</para> 2702 2703 <para>Valgrind's use of thread serialisation implies that only one 2704 thread at a time may run. On a multiprocessor/multicore system, the 2705 running thread is assigned to one of the CPUs by the OS kernel 2706 scheduler. When a thread acquires the lock, sometimes the thread will 2707 be assigned to the same CPU as the thread that just released the 2708 lock. Sometimes, the thread will be assigned to another CPU. When 2709 using pipe based locking, the thread that just acquired the lock 2710 will usually be scheduled on the same CPU as the thread that just 2711 released the lock. With the futex based mechanism, the thread that 2712 just acquired the lock will more often be scheduled on another 2713 CPU.</para> 2714 2715 <para>Valgrind's thread serialisation and CPU assignment by the OS 2716 kernel scheduler can interact badly with the CPU frequency scaling 2717 available on many modern CPUs. To decrease power consumption, the 2718 frequency of a CPU or core is automatically decreased if the CPU/core 2719 has not been used recently. If the OS kernel often assigns the thread 2720 which just acquired the lock to another CPU/core, it is quite likely 2721 that this CPU/core is currently at a low frequency. The frequency of 2722 this CPU will be increased after some time. However, during this 2723 time, the (only) running thread will have run at the low frequency. 2724 Once this thread has run for some time, it will release the lock. 2725 Another thread will acquire this lock, and might be scheduled again on 2726 another CPU whose clock frequency was decreased in the 2727 meantime.</para> 2728 2729 <para>The futex based locking causes threads to change CPUs/cores more 2730 often. So, if CPU frequency scaling is activated, the futex based 2731 locking might decrease significantly the performance of a 2732 multithreaded app running under Valgrind. Performance losses of up to 2733 50% degradation have been observed, as compared to running on a 2734 machine for which CPU frequency scaling has been disabled. The pipe 2735 based locking locking scheme also interacts badly with CPU frequency 2736 scaling, with performance losses in the range 10..20% having been 2737 observed.</para> 2738 2739 <para>To avoid such performance degradation, you should indicate to 2740 the kernel that all CPUs/cores should always run at maximum clock 2741 speed. Depending on your Linux distribution, CPU frequency scaling 2742 may be controlled using a graphical interface or using command line 2743 such as 2744 <computeroutput>cpufreq-selector</computeroutput> or 2745 <computeroutput>cpufreq-set</computeroutput>. 2746 </para> 2747 2748 <para>An alternative way to avoid these problems is to tell the 2749 OS scheduler to tie a Valgrind process to a specific (fixed) CPU using the 2750 <computeroutput>taskset</computeroutput> command. This should ensure 2751 that the selected CPU does not fall below its maximum frequency 2752 setting so long as any thread of the program has work to do. 2753 </para> 2754 2755 </sect2> 2756 2757 2758 </sect1> 2759 2760 <sect1 id="manual-core.signals" xreflabel="Handling of Signals"> 2761 <title>Handling of Signals</title> 2762 2763 <para>Valgrind has a fairly complete signal implementation. It should be 2764 able to cope with any POSIX-compliant use of signals.</para> 2765 2766 <para>If you're using signals in clever ways (for example, catching 2767 SIGSEGV, modifying page state and restarting the instruction), you're 2768 probably relying on precise exceptions. In this case, you will need 2769 to use <option>--vex-iropt-register-updates=allregs-at-mem-access</option> 2770 or <option>--vex-iropt-register-updates=allregs-at-each-insn</option>. 2771 </para> 2772 2773 <para>If your program dies as a result of a fatal core-dumping signal, 2774 Valgrind will generate its own core file 2775 (<computeroutput>vgcore.NNNNN</computeroutput>) containing your program's 2776 state. You may use this core file for post-mortem debugging with GDB or 2777 similar. (Note: it will not generate a core if your core dump size limit is 2778 0.) At the time of writing the core dumps do not include all the floating 2779 point register information.</para> 2780 2781 <para>In the unlikely event that Valgrind itself crashes, the operating system 2782 will create a core dump in the usual way.</para> 2783 2784 </sect1> 2785 2786 2787 <sect1 id="manual-core.xtree" xreflabel="Execution Trees"> 2788 <title>Execution Trees</title> 2789 2790 <para>An execution tree (xtree) is made of a set of stack traces, each 2791 stack trace is associated with some resource consumptions or event 2792 counts. Depending on the xtree, different event counts/resource 2793 consumptions can be recorded in the xtree. Multiple tools can 2794 produce memory use xtree. Memcheck can output the leak search results 2795 in an xtree.</para> 2796 2797 <para> A typical usage for an xtree is to show a graphical or textual 2798 representation of the heap usage of a program. The below figure is 2799 a heap usage xtree graphical representation produced by 2800 kcachegrind. In the kcachegrind output, you can see that main 2801 current heap usage (allocated indirectly) is 528 bytes : 388 bytes 2802 allocated indirectly via a call to function f1 and 140 bytes 2803 indirectly allocated via a call to function f2. f2 has allocated 2804 memory by calling g2, while f1 has allocated memory by calling g11 2805 and g12. g11, g12 and g1 have directly called a memory allocation 2806 function (malloc), and so have a non zero 'Self' value. Note that when 2807 kcachegrind shows an xtree, the 'Called' column and call nr indications in 2808 the Call Graph are not significant (always set to 0 or 1, independently 2809 of the real nr of calls. The kcachegrind versions >= 0.8.0 do not show 2810 anymore such irrelevant xtree call number information.</para> 2811 2812 <graphic fileref="images/kcachegrind_xtree.png" scalefit="1"/> 2813 2814 <para>An xtree heap memory report is produced at the end of the 2815 execution when required using the 2816 option <option>--xtree-memory</option>. It can also be produced on 2817 demand using the <option>xtmemory</option> monitor command (see 2818 <xref linkend="manual-core-adv.valgrind-monitor-commands"/>). Currently, 2819 an xtree heap memory report can be produced by 2820 the <option>memcheck</option>, <option>helgrind</option> 2821 and <option>massif</option> tools.</para> 2822 2823 <para>The xtrees produced by the option 2824 <xref linkend="opt.xtree-memory"/> or the <option>xtmemory</option> 2825 monitor command are showing the following events/resource 2826 consumption describing heap usage:</para> 2827 <itemizedlist> 2828 <listitem> 2829 <para><option>curB</option> current number of Bytes allocated. The 2830 number of allocated bytes is added to the <option>curB</option> 2831 value of a stack trace for each allocation. It is decreased when 2832 a block allocated by this stack trace is released (by another 2833 "freeing" stack trace)</para> 2834 </listitem> 2835 2836 <listitem> 2837 <para><option>curBk</option> current number of Blocks allocated, 2838 maintained similary to curB : +1 for each allocation, -1 when 2839 the block is freed.</para> 2840 </listitem> 2841 2842 <listitem> 2843 <para><option>totB</option> total allocated Bytes. This is 2844 increased for each allocation with the number of allocated bytes.</para> 2845 </listitem> 2846 2847 <listitem> 2848 <para><option>totBk</option> total allocated Blocks, maintained similary 2849 to totB : +1 for each allocation.</para> 2850 </listitem> 2851 2852 <listitem> 2853 <para><option>totFdB</option> total Freed Bytes, increased each time 2854 a block is released by this ("freeing") stack trace : + nr freed bytes 2855 for each free operation.</para> 2856 </listitem> 2857 2858 <listitem> 2859 <para><option>totFdBk</option> total Freed Blocks, maintained similarly 2860 to totFdB : +1 for each free operation.</para> 2861 </listitem> 2862 </itemizedlist> 2863 <para>Note that the last 4 counts are produced only when the 2864 <option>--xtree-memory=full</option> was given at startup.</para> 2865 2866 <para>Xtrees can be saved in 2 file formats, the "Callgrind Format" and 2867 the "Massif Format".</para> 2868 <itemizedlist> 2869 2870 <listitem> 2871 <para>Callgrind Format</para> 2872 <para>An xtree file in the Callgrind Format contains a single callgraph, 2873 associating each stack trace with the values recorded 2874 in the xtree. </para> 2875 <para>Different Callgrind Format file visualisers are available:</para> 2876 <para>Valgrind distribution includes the <option>callgrind_annotate</option> 2877 command line utility that reads in the xtree data, and prints a sorted 2878 lists of functions, optionally with source annotation. Note that due to 2879 xtree specificities, you must give the option 2880 <option>--inclusive=yes</option> to callgrind_annotate.</para> 2881 <para>For graphical visualization of the data, you can use 2882 <ulink url="&cl-gui-url;">KCachegrind</ulink>, which is a KDE/Qt based 2883 GUI that makes it easy to navigate the large amount of data that 2884 an xtree can contain.</para> 2885 </listitem> 2886 2887 <listitem> 2888 <para>Massif Format</para> 2889 <para>An xtree file in the Massif Format contains one detailed tree 2890 callgraph data for each type of event recorded in the xtree. So, 2891 for <option>--xtree-memory=alloc</option>, the output file will 2892 contain 2 detailed trees (for the counts <option>curB</option> 2893 and <option>curBk</option>), 2894 while <option>--xtree-memory=full</option> will give a file 2895 with 6 detailed trees.</para> 2896 <para>Different Massif Format file visualisers are available. Valgrind 2897 distribution includes the <option>ms_print</option> 2898 command line utility that produces an easy to read reprentation of 2899 a massif output file. See <xref linkend="ms-manual.running-massif"/> and 2900 <xref linkend="ms-manual.using"/> for more details 2901 about visualising Massif Format output files.</para> 2902 </listitem> 2903 2904 </itemizedlist> 2905 2906 <para>Note that for equivalent information, the Callgrind Format is more compact 2907 than the Massif Format. However, the Callgrind Format always contains the 2908 full data: there is no filtering done during file production, filtering is 2909 done by visualisers such as kcachegrind. kcachegrind is particularly easy to 2910 use to analyse big xtree data containing multiple events counts or resources 2911 consumption. The Massif Format (optionally) only contains a part of the data. 2912 For example, the Massif tool might filter some of the data, according to the 2913 <option>--threshold</option> option. 2914 </para> 2915 2916 <para>To clarify the xtree concept, the below gives several extracts of 2917 the output produced by the following commands: 2918 <screen><![CDATA[ 2919 valgrind --xtree-memory=full --xtree-memory-file=xtmemory.kcg mfg 2920 callgrind_annotate --auto=yes --inclusive=yes --sort=curB:100,curBk:100,totB:100,totBk:100,totFdB:100,totFdBk:100 xtmemory.kcg 2921 ]]></screen> 2922 </para> 2923 2924 <para>The below extract shows that the program mfg has allocated in 2925 total 770 bytes in 60 different blocks. Of these 60 blocks, 19 were 2926 freed, releasing a total of 242 bytes. The heap currently contains 2927 528 bytes in 41 blocks.</para> 2928 <screen><![CDATA[ 2929 -------------------------------------------------------------------------------- 2930 curB curBk totB totBk totFdB totFdBk 2931 -------------------------------------------------------------------------------- 2932 528 41 770 60 242 19 PROGRAM TOTALS 2933 ]]></screen> 2934 2935 <para>The below gives more details about which functions have 2936 allocated or released memory. As an example, we see that main has 2937 (directly or indirectly) allocated 770 bytes of memory and freed 2938 (directly or indirectly) 242 bytes of memory. The function f1 has 2939 (directly or indirectly) allocated 570 bytes of memory, and has not 2940 (directly or indirectly) freed memory. Of the 570 bytes allocated 2941 by function f1, 388 bytes (34 blocks) have not been 2942 released.</para> 2943 <screen><![CDATA[ 2944 -------------------------------------------------------------------------------- 2945 curB curBk totB totBk totFdB totFdBk file:function 2946 -------------------------------------------------------------------------------- 2947 528 41 770 60 242 19 mfg.c:main 2948 388 34 570 50 0 0 mfg.c:f1 2949 220 20 330 30 0 0 mfg.c:g11 2950 168 14 240 20 0 0 mfg.c:g12 2951 140 7 200 10 0 0 mfg.c:g2 2952 140 7 200 10 0 0 mfg.c:f2 2953 0 0 0 0 131 10 mfg.c:freeY 2954 0 0 0 0 111 9 mfg.c:freeX 2955 ]]></screen> 2956 2957 <para>The below gives a more detailed information about the callgraph 2958 and which source lines/calls have (directly or indirectly) allocated or 2959 released memory. The below shows that the 770 bytes allocated by 2960 main have been indirectly allocated by calls to f1 and f2. 2961 Similarly, we see that the 570 bytes allocated by f1 have been 2962 indirectly allocated by calls to g11 and g12. Of the 330 bytes allocated 2963 by the 30 calls to g11, 168 bytes have not been freed. 2964 The function freeY (called once by main) has released in total 2965 10 blocks and 131 bytes. </para> 2966 <screen><![CDATA[ 2967 -------------------------------------------------------------------------------- 2968 -- Auto-annotated source: /home/philippe/valgrind/littleprogs/ + mfg.c 2969 -------------------------------------------------------------------------------- 2970 curB curBk totB totBk totFdB totFdBk 2971 .... 2972 . . . . . . static void freeY(void) 2973 . . . . . . { 2974 . . . . . . int i; 2975 . . . . . . for (i = 0; i < next_ptr; i++) 2976 . . . . . . if(i % 5 == 0 && ptrs[i] != NULL) 2977 0 0 0 0 131 10 free(ptrs[i]); 2978 . . . . . . } 2979 . . . . . . static void f1(void) 2980 . . . . . . { 2981 . . . . . . int i; 2982 . . . . . . for (i = 0; i < 30; i++) 2983 220 20 330 30 0 0 g11(); 2984 . . . . . . for (i = 0; i < 20; i++) 2985 168 14 240 20 0 0 g12(); 2986 . . . . . . } 2987 . . . . . . int main() 2988 . . . . . . { 2989 388 34 570 50 0 0 f1(); 2990 140 7 200 10 0 0 f2(); 2991 0 0 0 0 111 9 freeX(); 2992 0 0 0 0 131 10 freeY(); 2993 . . . . . . return 0; 2994 . . . . . . } 2995 ]]></screen> 2996 2997 <para>Heap memory xtrees are helping to understand how your (big) 2998 program is using the heap. A full heap memory xtree helps to pin 2999 point some code that allocates a lot of small objects : allocating 3000 such small objects might be replaced by more efficient technique, 3001 such as allocating a big block using malloc, and then diviving this 3002 block into smaller blocks in order to decrease the cpu and/or memory 3003 overhead of allocating a lot of small blocks. Such full xtree information 3004 complements e.g. what callgrind can show: callgrind can show the number 3005 of calls to a function (such as malloc) but does not indicate the volume 3006 of memory allocated (or freed).</para> 3007 3008 <para>A full heap memory xtree also can identify the code that allocates 3009 and frees a lot of blocks : the total foot print of the program might 3010 not reflect the fact that the same memory was over and over allocated 3011 then released.</para> 3012 3013 <para>Finally, Xtree visualisers such as kcachegrind are helping to 3014 identify big memory consumers, in order to possibly optimise the 3015 amount of memory needed by your program.</para> 3016 3017 </sect1> 3018 3019 <sect1 id="manual-core.install" xreflabel="Building and Installing"> 3020 <title>Building and Installing Valgrind</title> 3021 3022 <para>We use the standard Unix 3023 <computeroutput>./configure</computeroutput>, 3024 <computeroutput>make</computeroutput>, <computeroutput>make 3025 install</computeroutput> mechanism. Once you have completed 3026 <computeroutput>make install</computeroutput> you may then want 3027 to run the regression tests 3028 with <computeroutput>make regtest</computeroutput>. 3029 </para> 3030 3031 <para>In addition to the usual 3032 <option>--prefix=/path/to/install/tree</option>, there are three 3033 options which affect how Valgrind is built: 3034 <itemizedlist> 3035 3036 <listitem> 3037 <para><option>--enable-inner</option></para> 3038 <para>This builds Valgrind with some special magic hacks which make 3039 it possible to run it on a standard build of Valgrind (what the 3040 developers call "self-hosting"). Ordinarily you should not use 3041 this option as various kinds of safety checks are disabled. 3042 </para> 3043 </listitem> 3044 3045 <listitem> 3046 <para><option>--enable-only64bit</option></para> 3047 <para><option>--enable-only32bit</option></para> 3048 <para>On 64-bit platforms (amd64-linux, ppc64-linux, 3049 amd64-darwin), Valgrind is by default built in such a way that 3050 both 32-bit and 64-bit executables can be run. Sometimes this 3051 cleverness is a problem for a variety of reasons. These two 3052 options allow for single-target builds in this situation. If you 3053 issue both, the configure script will complain. Note they are 3054 ignored on 32-bit-only platforms (x86-linux, ppc32-linux, 3055 arm-linux, x86-darwin). 3056 </para> 3057 </listitem> 3058 3059 </itemizedlist> 3060 </para> 3061 3062 <para>The <computeroutput>configure</computeroutput> script tests 3063 the version of the X server currently indicated by the current 3064 <computeroutput>$DISPLAY</computeroutput>. This is a known bug. 3065 The intention was to detect the version of the current X 3066 client libraries, so that correct suppressions could be selected 3067 for them, but instead the test checks the server version. This 3068 is just plain wrong.</para> 3069 3070 <para>If you are building a binary package of Valgrind for 3071 distribution, please read <literal>README_PACKAGERS</literal> 3072 <xref linkend="dist.readme-packagers"/>. It contains some 3073 important information.</para> 3074 3075 <para>Apart from that, there's not much excitement here. Let us 3076 know if you have build problems.</para> 3077 3078 </sect1> 3079 3080 3081 3082 <sect1 id="manual-core.problems" xreflabel="If You Have Problems"> 3083 <title>If You Have Problems</title> 3084 3085 <para>Contact us at <ulink url="&vg-url;">&vg-url;</ulink>.</para> 3086 3087 <para>See <xref linkend="manual-core.limits"/> for the known 3088 limitations of Valgrind, and for a list of programs which are 3089 known not to work on it.</para> 3090 3091 <para>All parts of the system make heavy use of assertions and 3092 internal self-checks. They are permanently enabled, and we have no 3093 plans to disable them. If one of them breaks, please mail us!</para> 3094 3095 <para>If you get an assertion failure 3096 in <filename>m_mallocfree.c</filename>, this may have happened because 3097 your program wrote off the end of a heap block, or before its 3098 beginning, thus corrupting heap metadata. Valgrind hopefully will have 3099 emitted a message to that effect before dying in this way.</para> 3100 3101 <para>Read the <xref linkend="FAQ"/> for more advice about common problems, 3102 crashes, etc.</para> 3103 3104 </sect1> 3105 3106 3107 3108 <sect1 id="manual-core.limits" xreflabel="Limitations"> 3109 <title>Limitations</title> 3110 3111 <para>The following list of limitations seems long. However, most 3112 programs actually work fine.</para> 3113 3114 <para>Valgrind will run programs on the supported platforms 3115 subject to the following constraints:</para> 3116 3117 <itemizedlist> 3118 <listitem> 3119 <para>On Linux, Valgrind determines at startup the size of the 'brk 3120 segment' using the RLIMIT_DATA rlim_cur, with a minimum of 1 MB and 3121 a maximum of 8 MB. Valgrind outputs a message each time a program 3122 tries to extend the brk segment beyond the size determined at 3123 startup. Most programs will work properly with this limit, 3124 typically by switching to the use of mmap to get more memory. 3125 If your program really needs a big brk segment, you must change 3126 the 8 MB hardcoded limit and recompile Valgrind. 3127 </para> 3128 </listitem> 3129 3130 <listitem> 3131 <para>On x86 and amd64, there is no support for 3DNow! 3132 instructions. If the translator encounters these, Valgrind will 3133 generate a SIGILL when the instruction is executed. Apart from 3134 that, on x86 and amd64, essentially all instructions are supported, 3135 up to and including AVX and AES in 64-bit mode and SSSE3 in 32-bit 3136 mode. 32-bit mode does in fact support the bare minimum SSE4 3137 instructions needed to run programs on MacOSX 10.6 on 32-bit 3138 targets. 3139 </para> 3140 </listitem> 3141 3142 <listitem> 3143 <para>On ppc32 and ppc64, almost all integer, floating point and 3144 Altivec instructions are supported. Specifically: integer and FP 3145 insns that are mandatory for PowerPC, the "General-purpose 3146 optional" group (fsqrt, fsqrts, stfiwx), the "Graphics optional" 3147 group (fre, fres, frsqrte, frsqrtes), and the Altivec (also known 3148 as VMX) SIMD instruction set, are supported. Also, instructions 3149 from the Power ISA 2.05 specification, as present in POWER6 CPUs, 3150 are supported.</para> 3151 </listitem> 3152 3153 <listitem> 3154 <para>On ARM, essentially the entire ARMv7-A instruction set 3155 is supported, in both ARM and Thumb mode. ThumbEE and Jazelle are 3156 not supported. NEON, VFPv3 and ARMv6 media support is fairly 3157 complete. 3158 </para> 3159 </listitem> 3160 3161 <listitem> 3162 <para>If your program does its own memory management, rather than 3163 using malloc/new/free/delete, it should still work, but Memcheck's 3164 error checking won't be so effective. If you describe your 3165 program's memory management scheme using "client requests" (see 3166 <xref linkend="manual-core-adv.clientreq"/>), Memcheck can do 3167 better. Nevertheless, using malloc/new and free/delete is still 3168 the best approach.</para> 3169 </listitem> 3170 3171 <listitem> 3172 <para>Valgrind's signal simulation is not as robust as it could be. 3173 Basic POSIX-compliant sigaction and sigprocmask functionality is 3174 supplied, but it's conceivable that things could go badly awry if you 3175 do weird things with signals. Workaround: don't. Programs that do 3176 non-POSIX signal tricks are in any case inherently unportable, so 3177 should be avoided if possible.</para> 3178 </listitem> 3179 3180 <listitem> 3181 <para>Machine instructions, and system calls, have been implemented 3182 on demand. So it's possible, although unlikely, that a program will 3183 fall over with a message to that effect. If this happens, please 3184 report all the details printed out, so we can try and implement the 3185 missing feature.</para> 3186 </listitem> 3187 3188 <listitem> 3189 <para>Memory consumption of your program is majorly increased 3190 whilst running under Valgrind's Memcheck tool. This is due to the 3191 large amount of administrative information maintained behind the 3192 scenes. Another cause is that Valgrind dynamically translates the 3193 original executable. Translated, instrumented code is 12-18 times 3194 larger than the original so you can easily end up with 150+ MB of 3195 translations when running (eg) a web browser.</para> 3196 </listitem> 3197 3198 <listitem> 3199 <para>Valgrind can handle dynamically-generated code just fine. If 3200 you regenerate code over the top of old code (ie. at the same 3201 memory addresses), if the code is on the stack Valgrind will 3202 realise the code has changed, and work correctly. This is 3203 necessary to handle the trampolines GCC uses to implemented nested 3204 functions. If you regenerate code somewhere other than the stack, 3205 and you are running on an 32- or 64-bit x86 CPU, you will need to 3206 use the <option>--smc-check=all</option> option, and Valgrind will 3207 run more slowly than normal. Or you can add client requests that 3208 tell Valgrind when your program has overwritten code. 3209 </para> 3210 <para> On other platforms (ARM, PowerPC) Valgrind observes and 3211 honours the cache invalidation hints that programs are obliged to 3212 emit to notify new code, and so self-modifying-code support should 3213 work automatically, without the need 3214 for <option>--smc-check=all</option>.</para> 3215 </listitem> 3216 3217 <listitem> 3218 <para>Valgrind has the following limitations 3219 in its implementation of x86/AMD64 floating point relative to 3220 IEEE754.</para> 3221 3222 <para>Precision: There is no support for 80 bit arithmetic. 3223 Internally, Valgrind represents all such "long double" numbers in 64 3224 bits, and so there may be some differences in results. Whether or 3225 not this is critical remains to be seen. Note, the x86/amd64 3226 fldt/fstpt instructions (read/write 80-bit numbers) are correctly 3227 simulated, using conversions to/from 64 bits, so that in-memory 3228 images of 80-bit numbers look correct if anyone wants to see.</para> 3229 3230 <para>The impression observed from many FP regression tests is that 3231 the accuracy differences aren't significant. Generally speaking, if 3232 a program relies on 80-bit precision, there may be difficulties 3233 porting it to non x86/amd64 platforms which only support 64-bit FP 3234 precision. Even on x86/amd64, the program may get different results 3235 depending on whether it is compiled to use SSE2 instructions (64-bits 3236 only), or x87 instructions (80-bit). The net effect is to make FP 3237 programs behave as if they had been run on a machine with 64-bit IEEE 3238 floats, for example PowerPC. On amd64 FP arithmetic is done by 3239 default on SSE2, so amd64 looks more like PowerPC than x86 from an FP 3240 perspective, and there are far fewer noticeable accuracy differences 3241 than with x86.</para> 3242 3243 <para>Rounding: Valgrind does observe the 4 IEEE-mandated rounding 3244 modes (to nearest, to +infinity, to -infinity, to zero) for the 3245 following conversions: float to integer, integer to float where 3246 there is a possibility of loss of precision, and float-to-float 3247 rounding. For all other FP operations, only the IEEE default mode 3248 (round to nearest) is supported.</para> 3249 3250 <para>Numeric exceptions in FP code: IEEE754 defines five types of 3251 numeric exception that can happen: invalid operation (sqrt of 3252 negative number, etc), division by zero, overflow, underflow, 3253 inexact (loss of precision).</para> 3254 3255 <para>For each exception, two courses of action are defined by IEEE754: 3256 either (1) a user-defined exception handler may be called, or (2) a 3257 default action is defined, which "fixes things up" and allows the 3258 computation to proceed without throwing an exception.</para> 3259 3260 <para>Currently Valgrind only supports the default fixup actions. 3261 Again, feedback on the importance of exception support would be 3262 appreciated.</para> 3263 3264 <para>When Valgrind detects that the program is trying to exceed any 3265 of these limitations (setting exception handlers, rounding mode, or 3266 precision control), it can print a message giving a traceback of 3267 where this has happened, and continue execution. This behaviour used 3268 to be the default, but the messages are annoying and so showing them 3269 is now disabled by default. Use <option>--show-emwarns=yes</option> to see 3270 them.</para> 3271 3272 <para>The above limitations define precisely the IEEE754 'default' 3273 behaviour: default fixup on all exceptions, round-to-nearest 3274 operations, and 64-bit precision.</para> 3275 </listitem> 3276 3277 <listitem> 3278 <para>Valgrind has the following limitations in 3279 its implementation of x86/AMD64 SSE2 FP arithmetic, relative to 3280 IEEE754.</para> 3281 3282 <para>Essentially the same: no exceptions, and limited observance of 3283 rounding mode. Also, SSE2 has control bits which make it treat 3284 denormalised numbers as zero (DAZ) and a related action, flush 3285 denormals to zero (FTZ). Both of these cause SSE2 arithmetic to be 3286 less accurate than IEEE requires. Valgrind detects, ignores, and can 3287 warn about, attempts to enable either mode.</para> 3288 </listitem> 3289 3290 <listitem> 3291 <para>Valgrind has the following limitations in 3292 its implementation of ARM VFPv3 arithmetic, relative to 3293 IEEE754.</para> 3294 3295 <para>Essentially the same: no exceptions, and limited observance 3296 of rounding mode. Also, switching the VFP unit into vector mode 3297 will cause Valgrind to abort the program -- it has no way to 3298 emulate vector uses of VFP at a reasonable performance level. This 3299 is no big deal given that non-scalar uses of VFP instructions are 3300 in any case deprecated.</para> 3301 </listitem> 3302 3303 <listitem> 3304 <para>Valgrind has the following limitations 3305 in its implementation of PPC32 and PPC64 floating point 3306 arithmetic, relative to IEEE754.</para> 3307 3308 <para>Scalar (non-Altivec): Valgrind provides a bit-exact emulation of 3309 all floating point instructions, except for "fre" and "fres", which are 3310 done more precisely than required by the PowerPC architecture specification. 3311 All floating point operations observe the current rounding mode. 3312 </para> 3313 3314 <para>However, fpscr[FPRF] is not set after each operation. That could 3315 be done but would give measurable performance overheads, and so far 3316 no need for it has been found.</para> 3317 3318 <para>As on x86/AMD64, IEEE754 exceptions are not supported: all floating 3319 point exceptions are handled using the default IEEE fixup actions. 3320 Valgrind detects, ignores, and can warn about, attempts to unmask 3321 the 5 IEEE FP exception kinds by writing to the floating-point status 3322 and control register (fpscr). 3323 </para> 3324 3325 <para>Vector (Altivec, VMX): essentially as with x86/AMD64 SSE/SSE2: 3326 no exceptions, and limited observance of rounding mode. 3327 For Altivec, FP arithmetic 3328 is done in IEEE/Java mode, which is more accurate than the Linux default 3329 setting. "More accurate" means that denormals are handled properly, 3330 rather than simply being flushed to zero.</para> 3331 </listitem> 3332 </itemizedlist> 3333 3334 <para>Programs which are known not to work are:</para> 3335 <itemizedlist> 3336 <listitem> 3337 <para>emacs starts up but immediately concludes it is out of 3338 memory and aborts. It may be that Memcheck does not provide 3339 a good enough emulation of the 3340 <computeroutput>mallinfo</computeroutput> function. 3341 Emacs works fine if you build it to use 3342 the standard malloc/free routines.</para> 3343 </listitem> 3344 </itemizedlist> 3345 3346 </sect1> 3347 3348 3349 <sect1 id="manual-core.example" xreflabel="An Example Run"> 3350 <title>An Example Run</title> 3351 3352 <para>This is the log for a run of a small program using Memcheck. 3353 The program is in fact correct, and the reported error is as the 3354 result of a potentially serious code generation bug in GNU g++ 3355 (snapshot 20010527).</para> 3356 3357 <programlisting><![CDATA[ 3358 sewardj@phoenix:~/newmat10$ ~/Valgrind-6/valgrind -v ./bogon 3359 ==25832== Valgrind 0.10, a memory error detector for x86 RedHat 7.1. 3360 ==25832== Copyright (C) 2000-2001, and GNU GPL'd, by Julian Seward. 3361 ==25832== Startup, with flags: 3362 ==25832== --suppressions=/home/sewardj/Valgrind/redhat71.supp 3363 ==25832== reading syms from /lib/ld-linux.so.2 3364 ==25832== reading syms from /lib/libc.so.6 3365 ==25832== reading syms from /mnt/pima/jrs/Inst/lib/libgcc_s.so.0 3366 ==25832== reading syms from /lib/libm.so.6 3367 ==25832== reading syms from /mnt/pima/jrs/Inst/lib/libstdc++.so.3 3368 ==25832== reading syms from /home/sewardj/Valgrind/valgrind.so 3369 ==25832== reading syms from /proc/self/exe 3370 ==25832== 3371 ==25832== Invalid read of size 4 3372 ==25832== at 0x8048724: BandMatrix::ReSize(int,int,int) (bogon.cpp:45) 3373 ==25832== by 0x80487AF: main (bogon.cpp:66) 3374 ==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd 3375 ==25832== 3376 ==25832== ERROR SUMMARY: 1 errors from 1 contexts (suppressed: 0 from 0) 3377 ==25832== malloc/free: in use at exit: 0 bytes in 0 blocks. 3378 ==25832== malloc/free: 0 allocs, 0 frees, 0 bytes allocated. 3379 ==25832== For a detailed leak analysis, rerun with: --leak-check=yes 3380 ]]></programlisting> 3381 3382 <para>The GCC folks fixed this about a week before GCC 3.0 3383 shipped.</para> 3384 3385 </sect1> 3386 3387 3388 <sect1 id="manual-core.warnings" xreflabel="Warning Messages"> 3389 <title>Warning Messages You Might See</title> 3390 3391 <para>Some of these only appear if you run in verbose mode 3392 (enabled by <option>-v</option>):</para> 3393 3394 <itemizedlist> 3395 3396 <listitem> 3397 <para><computeroutput>More than 100 errors detected. Subsequent 3398 errors will still be recorded, but in less detail than 3399 before.</computeroutput></para> 3400 3401 <para>After 100 different errors have been shown, Valgrind becomes 3402 more conservative about collecting them. It then requires only the 3403 program counters in the top two stack frames to match when deciding 3404 whether or not two errors are really the same one. Prior to this 3405 point, the PCs in the top four frames are required to match. This 3406 hack has the effect of slowing down the appearance of new errors 3407 after the first 100. The 100 constant can be changed by recompiling 3408 Valgrind.</para> 3409 </listitem> 3410 3411 <listitem> 3412 <para><computeroutput>More than 1000 errors detected. I'm not 3413 reporting any more. Final error counts may be inaccurate. Go fix 3414 your program!</computeroutput></para> 3415 3416 <para>After 1000 different errors have been detected, Valgrind 3417 ignores any more. It seems unlikely that collecting even more 3418 different ones would be of practical help to anybody, and it avoids 3419 the danger that Valgrind spends more and more of its time comparing 3420 new errors against an ever-growing collection. As above, the 1000 3421 number is a compile-time constant.</para> 3422 </listitem> 3423 3424 <listitem> 3425 <para><computeroutput>Warning: client switching stacks?</computeroutput></para> 3426 3427 <para>Valgrind spotted such a large change in the stack pointer 3428 that it guesses the client is switching to a different stack. At 3429 this point it makes a kludgey guess where the base of the new 3430 stack is, and sets memory permissions accordingly. At the moment 3431 "large change" is defined as a change of more that 2000000 in the 3432 value of the stack pointer register. If Valgrind guesses wrong, 3433 you may get many bogus error messages following this and/or have 3434 crashes in the stack trace recording code. You might avoid these 3435 problems by informing Valgrind about the stack bounds using 3436 VALGRIND_STACK_REGISTER client request. </para> 3437 3438 </listitem> 3439 3440 <listitem> 3441 <para><computeroutput>Warning: client attempted to close Valgrind's 3442 logfile fd <number></computeroutput></para> 3443 3444 <para>Valgrind doesn't allow the client to close the logfile, 3445 because you'd never see any diagnostic information after that point. 3446 If you see this message, you may want to use the 3447 <option>--log-fd=<number></option> option to specify a 3448 different logfile file-descriptor number.</para> 3449 </listitem> 3450 3451 <listitem> 3452 <para><computeroutput>Warning: noted but unhandled ioctl 3453 <number></computeroutput></para> 3454 3455 <para>Valgrind observed a call to one of the vast family of 3456 <computeroutput>ioctl</computeroutput> system calls, but did not 3457 modify its memory status info (because nobody has yet written a 3458 suitable wrapper). The call will still have gone through, but you may get 3459 spurious errors after this as a result of the non-update of the 3460 memory info.</para> 3461 </listitem> 3462 3463 <listitem> 3464 <para><computeroutput>Warning: set address range perms: large range 3465 <number></computeroutput></para> 3466 3467 <para>Diagnostic message, mostly for benefit of the Valgrind 3468 developers, to do with memory permissions.</para> 3469 </listitem> 3470 3471 </itemizedlist> 3472 3473 </sect1> 3474 3475 3476 3477 3478 3479 3480 </chapter> 3481
