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