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" href="vg_basic.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> 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" title="2.�Using and understanding the Valgrind core"> 21<div class="titlepage"><div><div><h2 class="title"> 22<a name="manual-core"></a>2.�Using and understanding the Valgrind core</h2></div></div></div> 23<div class="toc"> 24<p><b>Table of Contents</b></p> 25<dl> 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<dt><span class="sect1"><a href="manual-core.html#manual-core.signals">2.8. Handling of Signals</a></span></dt> 43<dt><span class="sect1"><a href="manual-core.html#manual-core.install">2.9. Building and Installing Valgrind</a></span></dt> 44<dt><span class="sect1"><a href="manual-core.html#manual-core.problems">2.10. If You Have Problems</a></span></dt> 45<dt><span class="sect1"><a href="manual-core.html#manual-core.limits">2.11. Limitations</a></span></dt> 46<dt><span class="sect1"><a href="manual-core.html#manual-core.example">2.12. An Example Run</a></span></dt> 47<dt><span class="sect1"><a href="manual-core.html#manual-core.warnings">2.13. Warning Messages You Might See</a></span></dt> 48</dl> 49</div> 50<p>This chapter describes the Valgrind core services, command-line 51options and behaviours. That means it is relevant regardless of what 52particular tool you are using. The information should be sufficient for you 53to make effective day-to-day use of Valgrind. Advanced topics related to 54the 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>. 55</p> 56<p> 57A point of terminology: most references to "Valgrind" in this chapter 58refer to the Valgrind core services. </p> 59<div class="sect1" title="2.1.�What Valgrind does with your program"> 60<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 61<a name="manual-core.whatdoes"></a>2.1.�What Valgrind does with your program</h2></div></div></div> 62<p>Valgrind is designed to be as non-intrusive as possible. It works 63directly with existing executables. You don't need to recompile, relink, 64or otherwise modify the program to be checked.</p> 65<p>You invoke Valgrind like this:</p> 66<pre class="programlisting"> 67valgrind [valgrind-options] your-prog [your-prog-options]</pre> 68<p>The most important option is <code class="option">--tool</code> which dictates 69which Valgrind tool to run. For example, if want to run the command 70<code class="computeroutput">ls -l</code> using the memory-checking tool 71Memcheck, issue this command:</p> 72<pre class="programlisting"> 73valgrind --tool=memcheck ls -l</pre> 74<p>However, Memcheck is the default, so if you want to use it you can 75omit the <code class="option">--tool</code> option.</p> 76<p>Regardless of which tool is in use, Valgrind takes control of your 77program before it starts. Debugging information is read from the 78executable and associated libraries, so that error messages and other 79outputs can be phrased in terms of source code locations, when 80appropriate.</p> 81<p>Your program is then run on a synthetic CPU provided by the 82Valgrind core. As new code is executed for the first time, the core 83hands the code to the selected tool. The tool adds its own 84instrumentation code to this and hands the result back to the core, 85which coordinates the continued execution of this instrumented 86code.</p> 87<p>The amount of instrumentation code added varies widely between 88tools. At one end of the scale, Memcheck adds code to check every 89memory access and every value computed, 90making it run 10-50 times slower than natively. 91At the other end of the spectrum, the minimal tool, called Nulgrind, 92adds no instrumentation at all and causes in total "only" about a 4 times 93slowdown.</p> 94<p>Valgrind simulates every single instruction your program executes. 95Because of this, the active tool checks, or profiles, not only the code 96in your application but also in all supporting dynamically-linked libraries, 97including the C library, graphical libraries, and so on.</p> 98<p>If you're using an error-detection tool, Valgrind may 99detect errors in system libraries, for example the GNU C or X11 100libraries, which you have to use. You might not be interested in these 101errors, since you probably have no control over that code. Therefore, 102Valgrind allows you to selectively suppress errors, by recording them in 103a suppressions file which is read when Valgrind starts up. The build 104mechanism selects default suppressions which give reasonable 105behaviour for the OS and libraries detected on your machine. 106To make it easier to write suppressions, you can use the 107<code class="option">--gen-suppressions=yes</code> option. This tells Valgrind to 108print out a suppression for each reported error, which you can then 109copy into a suppressions file.</p> 110<p>Different error-checking tools report different kinds of errors. 111The suppression mechanism therefore allows you to say which tool or 112tool(s) each suppression applies to.</p> 113</div> 114<div class="sect1" title="2.2.�Getting started"> 115<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 116<a name="manual-core.started"></a>2.2.�Getting started</h2></div></div></div> 117<p>First off, consider whether it might be beneficial to recompile 118your application and supporting libraries with debugging info enabled 119(the <code class="option">-g</code> option). Without debugging info, the best 120Valgrind tools will be able to do is guess which function a particular 121piece of code belongs to, which makes both error messages and profiling 122output nearly useless. With <code class="option">-g</code>, you'll get 123messages which point directly to the relevant source code lines.</p> 124<p>Another option you might like to consider, if you are working with 125C++, is <code class="option">-fno-inline</code>. That makes it easier to see the 126function-call chain, which can help reduce confusion when navigating 127around large C++ apps. For example, debugging 128OpenOffice.org with Memcheck is a bit easier when using this option. You 129don't have to do this, but doing so helps Valgrind produce more accurate 130and less confusing error reports. Chances are you're set up like this 131already, if you intended to debug your program with GNU GDB, or some 132other debugger.</p> 133<p>If you are planning to use Memcheck: On rare 134occasions, compiler optimisations (at <code class="option">-O2</code> 135and above, and sometimes <code class="option">-O1</code>) have been 136observed to generate code which fools Memcheck into wrongly reporting 137uninitialised value errors, or missing uninitialised value errors. We have 138looked in detail into fixing this, and unfortunately the result is that 139doing so would give a further significant slowdown in what is already a slow 140tool. So the best solution is to turn off optimisation altogether. Since 141this often makes things unmanageably slow, a reasonable compromise is to use 142<code class="option">-O</code>. This gets you the majority of the 143benefits of higher optimisation levels whilst keeping relatively small the 144chances of false positives or false negatives from Memcheck. Also, you 145should compile your code with <code class="option">-Wall</code> because 146it can identify some or all of the problems that Valgrind can miss at the 147higher optimisation levels. (Using <code class="option">-Wall</code> 148is also a good idea in general.) All other tools (as far as we know) are 149unaffected by optimisation level, and for profiling tools like Cachegrind it 150is better to compile your program at its normal optimisation level.</p> 151<p>Valgrind understands both the older "stabs" debugging format, used 152by GCC versions prior to 3.1, and the newer DWARF2/3/4 formats 153used by GCC 1543.1 and later. We continue to develop our debug-info readers, 155although the majority of effort will naturally enough go into the newer 156DWARF readers.</p> 157<p>When you're ready to roll, run Valgrind as described above. 158Note that you should run the real 159(machine-code) executable here. If your application is started by, for 160example, a shell or Perl script, you'll need to modify it to invoke 161Valgrind on the real executables. Running such scripts directly under 162Valgrind will result in you getting error reports pertaining to 163<code class="filename">/bin/sh</code>, 164<code class="filename">/usr/bin/perl</code>, or whatever interpreter 165you're using. This may not be what you want and can be confusing. You 166can force the issue by giving the option 167<code class="option">--trace-children=yes</code>, but confusion is still 168likely.</p> 169</div> 170<div class="sect1" title="2.3.�The Commentary"> 171<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 172<a name="manual-core.comment"></a>2.3.�The Commentary</h2></div></div></div> 173<p>Valgrind tools write a commentary, a stream of text, detailing 174error reports and other significant events. All lines in the commentary 175have following form: 176 177</p> 178<pre class="programlisting"> 179==12345== some-message-from-Valgrind</pre> 180<p> 181</p> 182<p>The <code class="computeroutput">12345</code> is the process ID. 183This scheme makes it easy to distinguish program output from Valgrind 184commentary, and also easy to differentiate commentaries from different 185processes which have become merged together, for whatever reason.</p> 186<p>By default, Valgrind tools write only essential messages to the 187commentary, so as to avoid flooding you with information of secondary 188importance. If you want more information about what is happening, 189re-run, passing the <code class="option">-v</code> option to Valgrind. A second 190<code class="option">-v</code> gives yet more detail. 191</p> 192<p>You can direct the commentary to three different places:</p> 193<div class="orderedlist"><ol class="orderedlist" type="1"> 194<li class="listitem"> 195<p><a name="manual-core.out2fd"></a>The default: send it to a file descriptor, which is by default 196 2 (stderr). So, if you give the core no options, it will write 197 commentary to the standard error stream. If you want to send it to 198 some other file descriptor, for example number 9, you can specify 199 <code class="option">--log-fd=9</code>.</p> 200<p>This is the simplest and most common arrangement, but can 201 cause problems when Valgrinding entire trees of processes which 202 expect specific file descriptors, particularly stdin/stdout/stderr, 203 to be available for their own use.</p> 204</li> 205<li class="listitem"><p><a name="manual-core.out2file"></a>A less intrusive 206 option is to write the commentary to a file, which you specify by 207 <code class="option">--log-file=filename</code>. There are special format 208 specifiers that can be used to use a process ID or an environment 209 variable name in the log file name. These are useful/necessary if your 210 program invokes multiple processes (especially for MPI programs). 211 See the <a class="link" href="manual-core.html#manual-core.basicopts" title="2.6.2.�Basic Options">basic options section</a> 212 for more details.</p></li> 213<li class="listitem"> 214<p><a name="manual-core.out2socket"></a>The 215 least intrusive option is to send the commentary to a network 216 socket. The socket is specified as an IP address and port number 217 pair, like this: <code class="option">--log-socket=192.168.0.1:12345</code> if 218 you want to send the output to host IP 192.168.0.1 port 12345 219 (note: we 220 have no idea if 12345 is a port of pre-existing significance). You 221 can also omit the port number: 222 <code class="option">--log-socket=192.168.0.1</code>, in which case a default 223 port of 1500 is used. This default is defined by the constant 224 <code class="computeroutput">VG_CLO_DEFAULT_LOGPORT</code> in the 225 sources.</p> 226<p>Note, unfortunately, that you have to use an IP address here, 227 rather than a hostname.</p> 228<p>Writing to a network socket is pointless if you don't 229 have something listening at the other end. We provide a simple 230 listener program, 231 <code class="computeroutput">valgrind-listener</code>, which accepts 232 connections on the specified port and copies whatever it is sent to 233 stdout. Probably someone will tell us this is a horrible security 234 risk. It seems likely that people will write more sophisticated 235 listeners in the fullness of time.</p> 236<p><code class="computeroutput">valgrind-listener</code> can accept 237 simultaneous connections from up to 50 Valgrinded processes. In front 238 of each line of output it prints the current number of active 239 connections in round brackets.</p> 240<p><code class="computeroutput">valgrind-listener</code> accepts two 241 command-line options:</p> 242<div class="itemizedlist"><ul class="itemizedlist" type="disc"> 243<li class="listitem"><p><code class="option">-e</code> or <code class="option">--exit-at-zero</code>: 244 when the number of connected processes falls back to zero, 245 exit. Without this, it will run forever, that is, until you 246 send it Control-C.</p></li> 247<li class="listitem"><p><code class="option">portnumber</code>: changes the port it listens 248 on from the default (1500). The specified port must be in the 249 range 1024 to 65535. The same restriction applies to port 250 numbers specified by a <code class="option">--log-socket</code> to 251 Valgrind itself.</p></li> 252</ul></div> 253<p>If a Valgrinded process fails to connect to a listener, for 254 whatever reason (the listener isn't running, invalid or unreachable 255 host or port, etc), Valgrind switches back to writing the commentary 256 to stderr. The same goes for any process which loses an established 257 connection to a listener. In other words, killing the listener 258 doesn't kill the processes sending data to it.</p> 259</li> 260</ol></div> 261<p>Here is an important point about the relationship between the 262commentary and profiling output from tools. The commentary contains a 263mix of messages from the Valgrind core and the selected tool. If the 264tool reports errors, it will report them to the commentary. However, if 265the tool does profiling, the profile data will be written to a file of 266some kind, depending on the tool, and independent of what 267<code class="option">--log-*</code> options are in force. The commentary is 268intended to be a low-bandwidth, human-readable channel. Profiling data, 269on the other hand, is usually voluminous and not meaningful without 270further processing, which is why we have chosen this arrangement.</p> 271</div> 272<div class="sect1" title="2.4.�Reporting of errors"> 273<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 274<a name="manual-core.report"></a>2.4.�Reporting of errors</h2></div></div></div> 275<p>When an error-checking tool 276detects something bad happening in the program, an error 277message is written to the commentary. Here's an example from Memcheck:</p> 278<pre class="programlisting"> 279==25832== Invalid read of size 4 280==25832== at 0x8048724: BandMatrix::ReSize(int, int, int) (bogon.cpp:45) 281==25832== by 0x80487AF: main (bogon.cpp:66) 282==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd</pre> 283<p>This message says that the program did an illegal 4-byte read of 284address 0xBFFFF74C, which, as far as Memcheck can tell, is not a valid 285stack address, nor corresponds to any current heap blocks or recently freed 286heap blocks. The read is happening at line 45 of 287<code class="filename">bogon.cpp</code>, called from line 66 of the same file, 288etc. For errors associated with an identified (current or freed) heap block, 289for example reading freed memory, Valgrind reports not only the 290location where the error happened, but also where the associated heap block 291was allocated/freed.</p> 292<p>Valgrind remembers all error reports. When an error is detected, 293it is compared against old reports, to see if it is a duplicate. If so, 294the error is noted, but no further commentary is emitted. This avoids 295you being swamped with bazillions of duplicate error reports.</p> 296<p>If you want to know how many times each error occurred, run with 297the <code class="option">-v</code> option. When execution finishes, all the 298reports are printed out, along with, and sorted by, their occurrence 299counts. This makes it easy to see which errors have occurred most 300frequently.</p> 301<p>Errors are reported before the associated operation actually 302happens. For example, if you're using Memcheck and your program attempts to 303read from address zero, Memcheck will emit a message to this effect, and 304your program will then likely die with a segmentation fault.</p> 305<p>In general, you should try and fix errors in the order that they 306are reported. Not doing so can be confusing. For example, a program 307which copies uninitialised values to several memory locations, and later 308uses them, will generate several error messages, when run on Memcheck. 309The first such error message may well give the most direct clue to the 310root cause of the problem.</p> 311<p>The process of detecting duplicate errors is quite an 312expensive one and can become a significant performance overhead 313if your program generates huge quantities of errors. To avoid 314serious problems, Valgrind will simply stop collecting 315errors after 1,000 different errors have been seen, or 10,000,000 errors 316in total have been seen. In this situation you might as well 317stop your program and fix it, because Valgrind won't tell you 318anything else useful after this. Note that the 1,000/10,000,000 limits 319apply after suppressed errors are removed. These limits are 320defined in <code class="filename">m_errormgr.c</code> and can be increased 321if necessary.</p> 322<p>To avoid this cutoff you can use the 323<code class="option">--error-limit=no</code> option. Then Valgrind will always show 324errors, regardless of how many there are. Use this option carefully, 325since it may have a bad effect on performance.</p> 326</div> 327<div class="sect1" title="2.5.�Suppressing errors"> 328<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 329<a name="manual-core.suppress"></a>2.5.�Suppressing errors</h2></div></div></div> 330<p>The error-checking tools detect numerous problems in the system 331libraries, such as the C library, 332which come pre-installed with your OS. You can't easily fix 333these, but you don't want to see these errors (and yes, there are many!) 334So Valgrind reads a list of errors to suppress at startup. A default 335suppression file is created by the 336<code class="computeroutput">./configure</code> script when the system is 337built.</p> 338<p>You can modify and add to the suppressions file at your leisure, 339or, better, write your own. Multiple suppression files are allowed. 340This is useful if part of your project contains errors you can't or 341don't want to fix, yet you don't want to continuously be reminded of 342them.</p> 343<p title="Note:"><b>Note:�</b>By far the easiest way to add 344suppressions is to use the <code class="option">--gen-suppressions=yes</code> option 345described 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 346suppressions automatically. For best results, 347though, you may want to edit the output 348 of <code class="option">--gen-suppressions=yes</code> by hand, in which 349case it would be advisable to read through this section. 350</p> 351<p>Each error to be suppressed is described very specifically, to 352minimise the possibility that a suppression-directive inadvertently 353suppresses a bunch of similar errors which you did want to see. The 354suppression mechanism is designed to allow precise yet flexible 355specification of errors to suppress.</p> 356<p>If you use the <code class="option">-v</code> option, at the end of execution, 357Valgrind prints out one line for each used suppression, giving its name 358and the number of times it got used. Here's the suppressions used by a 359run of <code class="computeroutput">valgrind --tool=memcheck ls -l</code>:</p> 360<pre class="programlisting"> 361--27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getgrgid_r 362--27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getpwuid_r 363--27579-- supp: 6 strrchr/_dl_map_object_from_fd/_dl_map_object</pre> 364<p>Multiple suppressions files are allowed. By default, Valgrind 365uses <code class="filename">$PREFIX/lib/valgrind/default.supp</code>. You can 366ask to add suppressions from another file, by specifying 367<code class="option">--suppressions=/path/to/file.supp</code>. 368</p> 369<p>If you want to understand more about suppressions, look at an 370existing suppressions file whilst reading the following documentation. 371The file <code class="filename">glibc-2.3.supp</code>, in the source 372distribution, provides some good examples.</p> 373<p>Each suppression has the following components:</p> 374<div class="itemizedlist"><ul class="itemizedlist" type="disc"> 375<li class="listitem"><p>First line: its name. This merely gives a handy name to the 376 suppression, by which it is referred to in the summary of used 377 suppressions printed out when a program finishes. It's not 378 important what the name is; any identifying string will do.</p></li> 379<li class="listitem"> 380<p>Second line: name of the tool(s) that the suppression is for 381 (if more than one, comma-separated), and the name of the suppression 382 itself, separated by a colon (n.b.: no spaces are allowed), eg:</p> 383<pre class="programlisting"> 384tool_name1,tool_name2:suppression_name</pre> 385<p>Recall that Valgrind is a modular system, in which 386 different instrumentation tools can observe your program whilst it 387 is running. Since different tools detect different kinds of errors, 388 it is necessary to say which tool(s) the suppression is meaningful 389 to.</p> 390<p>Tools will complain, at startup, if a tool does not understand 391 any suppression directed to it. Tools ignore suppressions which are 392 not directed to them. As a result, it is quite practical to put 393 suppressions for all tools into the same suppression file.</p> 394</li> 395<li class="listitem"><p>Next line: a small number of suppression types have extra 396 information after the second line (eg. the <code class="varname">Param</code> 397 suppression for Memcheck)</p></li> 398<li class="listitem"> 399<p>Remaining lines: This is the calling context for the error -- 400 the chain of function calls that led to it. There can be up to 24 401 of these lines.</p> 402<p>Locations may be names of either shared objects or 403 functions. They begin 404 <code class="computeroutput">obj:</code> and 405 <code class="computeroutput">fun:</code> respectively. Function and 406 object names to match against may use the wildcard characters 407 <code class="computeroutput">*</code> and 408 <code class="computeroutput">?</code>.</p> 409<p><span class="command"><strong>Important note: </strong></span> C++ function names must be 410 <span class="command"><strong>mangled</strong></span>. If you are writing suppressions by 411 hand, use the <code class="option">--demangle=no</code> option to get the 412 mangled names in your error messages. An example of a mangled 413 C++ name is <code class="computeroutput">_ZN9QListView4showEv</code>. 414 This is the form that the GNU C++ compiler uses internally, and 415 the form that must be used in suppression files. The equivalent 416 demangled name, <code class="computeroutput">QListView::show()</code>, 417 is what you see at the C++ source code level. 418 </p> 419<p>A location line may also be 420 simply "<code class="computeroutput">...</code>" (three dots). This is 421 a frame-level wildcard, which matches zero or more frames. Frame 422 level wildcards are useful because they make it easy to ignore 423 varying numbers of uninteresting frames in between frames of 424 interest. That is often important when writing suppressions which 425 are intended to be robust against variations in the amount of 426 function inlining done by compilers.</p> 427</li> 428<li class="listitem"><p>Finally, the entire suppression must be between curly 429 braces. Each brace must be the first character on its own 430 line.</p></li> 431</ul></div> 432<p>A suppression only suppresses an error when the error matches all 433the details in the suppression. Here's an example:</p> 434<pre class="programlisting"> 435{ 436 __gconv_transform_ascii_internal/__mbrtowc/mbtowc 437 Memcheck:Value4 438 fun:__gconv_transform_ascii_internal 439 fun:__mbr*toc 440 fun:mbtowc 441}</pre> 442<p>What it means is: for Memcheck only, suppress a 443use-of-uninitialised-value error, when the data size is 4, when it 444occurs in the function 445<code class="computeroutput">__gconv_transform_ascii_internal</code>, when 446that is called from any function of name matching 447<code class="computeroutput">__mbr*toc</code>, when that is called from 448<code class="computeroutput">mbtowc</code>. It doesn't apply under any 449other circumstances. The string by which this suppression is identified 450to the user is 451<code class="computeroutput">__gconv_transform_ascii_internal/__mbrtowc/mbtowc</code>.</p> 452<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 453on the specifics of Memcheck's suppression kinds.)</p> 454<p>Another example, again for the Memcheck tool:</p> 455<pre class="programlisting"> 456{ 457 libX11.so.6.2/libX11.so.6.2/libXaw.so.7.0 458 Memcheck:Value4 459 obj:/usr/X11R6/lib/libX11.so.6.2 460 obj:/usr/X11R6/lib/libX11.so.6.2 461 obj:/usr/X11R6/lib/libXaw.so.7.0 462}</pre> 463<p>This suppresses any size 4 uninitialised-value error which occurs 464anywhere in <code class="filename">libX11.so.6.2</code>, when called from 465anywhere in the same library, when called from anywhere in 466<code class="filename">libXaw.so.7.0</code>. The inexact specification of 467locations is regrettable, but is about all you can hope for, given that 468the X11 libraries shipped on the Linux distro on which this example 469was made have had their symbol tables removed.</p> 470<p>Although the above two examples do not make this clear, you can 471freely mix <code class="computeroutput">obj:</code> and 472<code class="computeroutput">fun:</code> lines in a suppression.</p> 473<p>Finally, here's an example using three frame-level wildcards:</p> 474<pre class="programlisting"> 475{ 476 a-contrived-example 477 Memcheck:Leak 478 fun:malloc 479 ... 480 fun:ddd 481 ... 482 fun:ccc 483 ... 484 fun:main 485} 486</pre> 487This suppresses Memcheck memory-leak errors, in the case where 488the allocation was done by <code class="computeroutput">main</code> 489calling (though any number of intermediaries, including zero) 490<code class="computeroutput">ccc</code>, 491calling onwards via 492<code class="computeroutput">ddd</code> and eventually 493to <code class="computeroutput">malloc.</code>. 494</div> 495<div class="sect1" title="2.6.�Core Command-line Options"> 496<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 497<a name="manual-core.options"></a>2.6.�Core Command-line Options</h2></div></div></div> 498<p>As mentioned above, Valgrind's core accepts a common set of options. 499The tools also accept tool-specific options, which are documented 500separately for each tool.</p> 501<p>Valgrind's default settings succeed in giving reasonable behaviour 502in most cases. We group the available options by rough categories.</p> 503<div class="sect2" title="2.6.1.�Tool-selection Option"> 504<div class="titlepage"><div><div><h3 class="title"> 505<a name="manual-core.toolopts"></a>2.6.1.�Tool-selection Option</h3></div></div></div> 506<p>The single most important option.</p> 507<div class="variablelist"><dl> 508<dt> 509<a name="tool_name"></a><span class="term"> 510 <code class="option">--tool=<toolname> [default: memcheck] </code> 511 </span> 512</dt> 513<dd><p>Run the Valgrind tool called <code class="varname">toolname</code>, 514 e.g. Memcheck, Cachegrind, etc.</p></dd> 515</dl></div> 516</div> 517<div class="sect2" title="2.6.2.�Basic Options"> 518<div class="titlepage"><div><div><h3 class="title"> 519<a name="manual-core.basicopts"></a>2.6.2.�Basic Options</h3></div></div></div> 520<p><a name="basic.opts.para"></a>These options work with all tools.</p> 521<div class="variablelist"> 522<a name="basic.opts.list"></a><dl> 523<dt> 524<a name="opt.help"></a><span class="term"><code class="option">-h --help</code></span> 525</dt> 526<dd><p>Show help for all options, both for the core and for the 527 selected tool. If the option is repeated it is equivalent to giving 528 <code class="option">--help-debug</code>.</p></dd> 529<dt> 530<a name="opt.help-debug"></a><span class="term"><code class="option">--help-debug</code></span> 531</dt> 532<dd><p>Same as <code class="option">--help</code>, but also lists debugging 533 options which usually are only of use to Valgrind's 534 developers.</p></dd> 535<dt> 536<a name="opt.version"></a><span class="term"><code class="option">--version</code></span> 537</dt> 538<dd><p>Show the version number of the Valgrind core. Tools can have 539 their own version numbers. There is a scheme in place to ensure 540 that tools only execute when the core version is one they are 541 known to work with. This was done to minimise the chances of 542 strange problems arising from tool-vs-core version 543 incompatibilities.</p></dd> 544<dt> 545<a name="opt.quiet"></a><span class="term"><code class="option">-q</code>, <code class="option">--quiet</code></span> 546</dt> 547<dd><p>Run silently, and only print error messages. Useful if you 548 are running regression tests or have some other automated test 549 machinery.</p></dd> 550<dt> 551<a name="opt.verbose"></a><span class="term"><code class="option">-v</code>, <code class="option">--verbose</code></span> 552</dt> 553<dd><p>Be more verbose. Gives extra information on various aspects 554 of your program, such as: the shared objects loaded, the 555 suppressions used, the progress of the instrumentation and 556 execution engines, and warnings about unusual behaviour. Repeating 557 the option increases the verbosity level.</p></dd> 558<dt> 559<a name="opt.trace-children"></a><span class="term"> 560 <code class="option">--trace-children=<yes|no> [default: no] </code> 561 </span> 562</dt> 563<dd> 564<p>When enabled, Valgrind will trace into sub-processes 565 initiated via the <code class="varname">exec</code> system call. This is 566 necessary for multi-process programs. 567 </p> 568<p>Note that Valgrind does trace into the child of a 569 <code class="varname">fork</code> (it would be difficult not to, since 570 <code class="varname">fork</code> makes an identical copy of a process), so this 571 option is arguably badly named. However, most children of 572 <code class="varname">fork</code> calls immediately call <code class="varname">exec</code> 573 anyway. 574 </p> 575</dd> 576<dt> 577<a name="opt.trace-children-skip"></a><span class="term"> 578 <code class="option">--trace-children-skip=patt1,patt2 </code> 579 </span> 580</dt> 581<dd> 582<p>This option only has an effect when 583 <code class="option">--trace-children=yes</code> is specified. It allows 584 for some children to be skipped. The option takes a comma 585 separated list of patterns for the names of child executables 586 that Valgrind should not trace into. Patterns may include the 587 metacharacters <code class="computeroutput">?</code> 588 and <code class="computeroutput">*</code>, which have the usual 589 meaning.</p> 590<p> 591 This can be useful for pruning uninteresting branches from a 592 tree of processes being run on Valgrind. But you should be 593 careful when using it. When Valgrind skips tracing into an 594 executable, it doesn't just skip tracing that executable, it 595 also skips tracing any of that executable's child processes. 596 In other words, the flag doesn't merely cause tracing to stop 597 at the specified executables -- it skips tracing of entire 598 process subtrees rooted at any of the specified 599 executables.</p> 600</dd> 601<dt> 602<a name="opt.child-silent-after-fork"></a><span class="term"> 603 <code class="option">--child-silent-after-fork=<yes|no> [default: no] </code> 604 </span> 605</dt> 606<dd><p>When enabled, Valgrind will not show any debugging or 607 logging output for the child process resulting from 608 a <code class="varname">fork</code> call. This can make the output less 609 confusing (although more misleading) when dealing with processes 610 that create children. It is particularly useful in conjunction 611 with <code class="varname">--trace-children=</code>. Use of this option is also 612 strongly recommended if you are requesting XML output 613 (<code class="varname">--xml=yes</code>), since otherwise the XML from child and 614 parent may become mixed up, which usually makes it useless. 615 </p></dd> 616<dt> 617<a name="opt.track-fds"></a><span class="term"> 618 <code class="option">--track-fds=<yes|no> [default: no] </code> 619 </span> 620</dt> 621<dd><p>When enabled, Valgrind will print out a list of open file 622 descriptors on exit. Along with each file descriptor is printed a 623 stack backtrace of where the file was opened and any details 624 relating to the file descriptor such as the file name or socket 625 details.</p></dd> 626<dt> 627<a name="opt.time-stamp"></a><span class="term"> 628 <code class="option">--time-stamp=<yes|no> [default: no] </code> 629 </span> 630</dt> 631<dd><p>When enabled, each message is preceded with an indication of 632 the elapsed wallclock time since startup, expressed as days, 633 hours, minutes, seconds and milliseconds.</p></dd> 634<dt> 635<a name="opt.log-fd"></a><span class="term"> 636 <code class="option">--log-fd=<number> [default: 2, stderr] </code> 637 </span> 638</dt> 639<dd><p>Specifies that Valgrind should send all of its messages to 640 the specified file descriptor. The default, 2, is the standard 641 error channel (stderr). Note that this may interfere with the 642 client's own use of stderr, as Valgrind's output will be 643 interleaved with any output that the client sends to 644 stderr.</p></dd> 645<dt> 646<a name="opt.log-file"></a><span class="term"> 647 <code class="option">--log-file=<filename> </code> 648 </span> 649</dt> 650<dd> 651<p>Specifies that Valgrind should send all of its messages to 652 the specified file. If the file name is empty, it causes an abort. 653 There are three special format specifiers that can be used in the file 654 name.</p> 655<p><code class="option">%p</code> is replaced with the current process ID. 656 This is very useful for program that invoke multiple processes. 657 WARNING: If you use <code class="option">--trace-children=yes</code> and your 658 program invokes multiple processes OR your program forks without 659 calling exec afterwards, and you don't use this specifier 660 (or the <code class="option">%q</code> specifier below), the Valgrind output from 661 all those processes will go into one file, possibly jumbled up, and 662 possibly incomplete.</p> 663<p><code class="option">%q{FOO}</code> is replaced with the contents of the 664 environment variable <code class="varname">FOO</code>. If the 665 <code class="option">{FOO}</code> part is malformed, it causes an abort. This 666 specifier is rarely needed, but very useful in certain circumstances 667 (eg. when running MPI programs). The idea is that you specify a 668 variable which will be set differently for each process in the job, 669 for example <code class="computeroutput">BPROC_RANK</code> or whatever is 670 applicable in your MPI setup. If the named environment variable is not 671 set, it causes an abort. Note that in some shells, the 672 <code class="option">{</code> and <code class="option">}</code> characters may need to be 673 escaped with a backslash.</p> 674<p><code class="option">%%</code> is replaced with <code class="option">%</code>.</p> 675<p>If an <code class="option">%</code> is followed by any other character, it 676 causes an abort.</p> 677</dd> 678<dt> 679<a name="opt.log-socket"></a><span class="term"> 680 <code class="option">--log-socket=<ip-address:port-number> </code> 681 </span> 682</dt> 683<dd><p>Specifies that Valgrind should send all of its messages to 684 the specified port at the specified IP address. The port may be 685 omitted, in which case port 1500 is used. If a connection cannot 686 be made to the specified socket, Valgrind falls back to writing 687 output to the standard error (stderr). This option is intended to 688 be used in conjunction with the 689 <code class="computeroutput">valgrind-listener</code> program. For 690 further details, see 691 <a class="link" href="manual-core.html#manual-core.comment" title="2.3.�The Commentary">the commentary</a> 692 in the manual.</p></dd> 693</dl> 694</div> 695</div> 696<div class="sect2" title="2.6.3.�Error-related Options"> 697<div class="titlepage"><div><div><h3 class="title"> 698<a name="manual-core.erropts"></a>2.6.3.�Error-related Options</h3></div></div></div> 699<p><a name="error-related.opts.para"></a>These options are used by all tools 700that can report errors, e.g. Memcheck, but not Cachegrind.</p> 701<div class="variablelist"> 702<a name="error-related.opts.list"></a><dl> 703<dt> 704<a name="opt.xml"></a><span class="term"> 705 <code class="option">--xml=<yes|no> [default: no] </code> 706 </span> 707</dt> 708<dd> 709<p>When enabled, the important parts of the output (e.g. tool error 710 messages) will be in XML format rather than plain text. Furthermore, 711 the XML output will be sent to a different output channel than the 712 plain text output. Therefore, you also must use one of 713 <code class="option">--xml-fd</code>, <code class="option">--xml-file</code> or 714 <code class="option">--xml-socket</code> to specify where the XML is to be sent. 715 </p> 716<p>Less important messages will still be printed in plain text, but 717 because the XML output and plain text output are sent to different 718 output channels (the destination of the plain text output is still 719 controlled by <code class="option">--log-fd</code>, <code class="option">--log-file</code> 720 and <code class="option">--log-socket</code>) this should not cause problems. 721 </p> 722<p>This option is aimed at making life easier for tools that consume 723 Valgrind's output as input, such as GUI front ends. Currently this 724 option works with Memcheck, Helgrind and Ptrcheck. The output format 725 is specified in the file 726 <code class="computeroutput">docs/internals/xml-output-protocol4.txt</code> 727 in the source tree for Valgrind 3.5.0 or later.</p> 728<p>The recommended options for a GUI to pass, when requesting 729 XML output, are: <code class="option">--xml=yes</code> to enable XML output, 730 <code class="option">--xml-file</code> to send the XML output to a (presumably 731 GUI-selected) file, <code class="option">--log-file</code> to send the plain 732 text output to a second GUI-selected file, 733 <code class="option">--child-silent-after-fork=yes</code>, and 734 <code class="option">-q</code> to restrict the plain text output to critical 735 error messages created by Valgrind itself. For example, failure to 736 read a specified suppressions file counts as a critical error message. 737 In this way, for a successful run the text output file will be empty. 738 But if it isn't empty, then it will contain important information 739 which the GUI user should be made aware 740 of.</p> 741</dd> 742<dt> 743<a name="opt.xml-fd"></a><span class="term"> 744 <code class="option">--xml-fd=<number> [default: -1, disabled] </code> 745 </span> 746</dt> 747<dd><p>Specifies that Valgrind should send its XML output to the 748 specified file descriptor. It must be used in conjunction with 749 <code class="option">--xml=yes</code>.</p></dd> 750<dt> 751<a name="opt.xml-file"></a><span class="term"> 752 <code class="option">--xml-file=<filename> </code> 753 </span> 754</dt> 755<dd><p>Specifies that Valgrind should send its XML output 756 to the specified file. It must be used in conjunction with 757 <code class="option">--xml=yes</code>. Any <code class="option">%p</code> or 758 <code class="option">%q</code> sequences appearing in the filename are expanded 759 in exactly the same way as they are for <code class="option">--log-file</code>. 760 See the description of <code class="option">--log-file</code> for details. 761 </p></dd> 762<dt> 763<a name="opt.xml-socket"></a><span class="term"> 764 <code class="option">--xml-socket=<ip-address:port-number> </code> 765 </span> 766</dt> 767<dd><p>Specifies that Valgrind should send its XML output the 768 specified port at the specified IP address. It must be used in 769 conjunction with <code class="option">--xml=yes</code>. The form of the argument 770 is the same as that used by <code class="option">--log-socket</code>. 771 See the description of <code class="option">--log-socket</code> 772 for further details.</p></dd> 773<dt> 774<a name="opt.xml-user-comment"></a><span class="term"> 775 <code class="option">--xml-user-comment=<string> </code> 776 </span> 777</dt> 778<dd><p>Embeds an extra user comment string at the start of the XML 779 output. Only works when <code class="option">--xml=yes</code> is specified; 780 ignored otherwise.</p></dd> 781<dt> 782<a name="opt.demangle"></a><span class="term"> 783 <code class="option">--demangle=<yes|no> [default: yes] </code> 784 </span> 785</dt> 786<dd> 787<p>Enable/disable automatic demangling (decoding) of C++ names. 788 Enabled by default. When enabled, Valgrind will attempt to 789 translate encoded C++ names back to something approaching the 790 original. The demangler handles symbols mangled by g++ versions 791 2.X, 3.X and 4.X.</p> 792<p>An important fact about demangling is that function names 793 mentioned in suppressions files should be in their mangled form. 794 Valgrind does not demangle function names when searching for 795 applicable suppressions, because to do otherwise would make 796 suppression file contents dependent on the state of Valgrind's 797 demangling machinery, and also slow down suppression matching.</p> 798</dd> 799<dt> 800<a name="opt.num-callers"></a><span class="term"> 801 <code class="option">--num-callers=<number> [default: 12] </code> 802 </span> 803</dt> 804<dd> 805<p>Specifies the maximum number of entries shown in stack traces 806 that identify program locations. Note that errors are commoned up 807 using only the top four function locations (the place in the current 808 function, and that of its three immediate callers). So this doesn't 809 affect the total number of errors reported.</p> 810<p>The maximum value for this is 50. Note that higher settings 811 will make Valgrind run a bit more slowly and take a bit more 812 memory, but can be useful when working with programs with 813 deeply-nested call chains.</p> 814</dd> 815<dt> 816<a name="opt.error-limit"></a><span class="term"> 817 <code class="option">--error-limit=<yes|no> [default: yes] </code> 818 </span> 819</dt> 820<dd><p>When enabled, Valgrind stops reporting errors after 10,000,000 821 in total, or 1,000 different ones, have been seen. This is to 822 stop the error tracking machinery from becoming a huge performance 823 overhead in programs with many errors.</p></dd> 824<dt> 825<a name="opt.error-exitcode"></a><span class="term"> 826 <code class="option">--error-exitcode=<number> [default: 0] </code> 827 </span> 828</dt> 829<dd><p>Specifies an alternative exit code to return if Valgrind 830 reported any errors in the run. When set to the default value 831 (zero), the return value from Valgrind will always be the return 832 value of the process being simulated. When set to a nonzero value, 833 that value is returned instead, if Valgrind detects any errors. 834 This is useful for using Valgrind as part of an automated test 835 suite, since it makes it easy to detect test cases for which 836 Valgrind has reported errors, just by inspecting return codes.</p></dd> 837<dt> 838<a name="opt.stack-traces"></a><span class="term"> 839 <code class="option">--show-below-main=<yes|no> [default: no] </code> 840 </span> 841</dt> 842<dd> 843<p>By default, stack traces for errors do not show any 844 functions that appear beneath <code class="function">main</code> because 845 most of the time it's uninteresting C library stuff and/or 846 gobbledygook. Alternatively, if <code class="function">main</code> is not 847 present in the stack trace, stack traces will not show any functions 848 below <code class="function">main</code>-like functions such as glibc's 849 <code class="function">__libc_start_main</code>. Furthermore, if 850 <code class="function">main</code>-like functions are present in the trace, 851 they are normalised as <code class="function">(below main)</code>, in order to 852 make the output more deterministic.</p> 853<p>If this option is enabled, all stack trace entries will be 854 shown and <code class="function">main</code>-like functions will not be 855 normalised.</p> 856</dd> 857<dt> 858<a name="opt.fullpath-after"></a><span class="term"> 859 <code class="option">--fullpath-after=<string> 860 [default: don't show source paths] </code> 861 </span> 862</dt> 863<dd> 864<p>By default Valgrind only shows the filenames in stack 865 traces, but not full paths to source files. When using Valgrind 866 in large projects where the sources reside in multiple different 867 directories, this can be inconvenient. 868 <code class="option">--fullpath-after</code> provides a flexible solution 869 to this problem. When this option is present, the path to each 870 source file is shown, with the following all-important caveat: 871 if <code class="option">string</code> is found in the path, then the path 872 up to and including <code class="option">string</code> is omitted, else the 873 path is shown unmodified. Note that <code class="option">string</code> is 874 not required to be a prefix of the path.</p> 875<p>For example, consider a file named 876 <code class="computeroutput">/home/janedoe/blah/src/foo/bar/xyzzy.c</code>. 877 Specifying <code class="option">--fullpath-after=/home/janedoe/blah/src/</code> 878 will cause Valgrind to show the name 879 as <code class="computeroutput">foo/bar/xyzzy.c</code>.</p> 880<p>Because the string is not required to be a prefix, 881 <code class="option">--fullpath-after=src/</code> will produce the same 882 output. This is useful when the path contains arbitrary 883 machine-generated characters. For example, the 884 path 885 <code class="computeroutput">/my/build/dir/C32A1B47/blah/src/foo/xyzzy</code> 886 can be pruned to <code class="computeroutput">foo/xyzzy</code> 887 using 888 <code class="option">--fullpath-after=/blah/src/</code>.</p> 889<p>If you simply want to see the full path, just specify an 890 empty string: <code class="option">--fullpath-after=</code>. This isn't a 891 special case, merely a logical consequence of the above rules.</p> 892<p>Finally, you can use <code class="option">--fullpath-after</code> 893 multiple times. Any appearance of it causes Valgrind to switch 894 to producing full paths and applying the above filtering rule. 895 Each produced path is compared against all 896 the <code class="option">--fullpath-after</code>-specified strings, in the 897 order specified. The first string to match causes the path to 898 be truncated as described above. If none match, the full path 899 is shown. This facilitates chopping off prefixes when the 900 sources are drawn from a number of unrelated directories. 901 </p> 902</dd> 903<dt> 904<a name="opt.suppressions"></a><span class="term"> 905 <code class="option">--suppressions=<filename> [default: $PREFIX/lib/valgrind/default.supp] </code> 906 </span> 907</dt> 908<dd><p>Specifies an extra file from which to read descriptions of 909 errors to suppress. You may use up to 100 extra suppression 910 files.</p></dd> 911<dt> 912<a name="opt.gen-suppressions"></a><span class="term"> 913 <code class="option">--gen-suppressions=<yes|no|all> [default: no] </code> 914 </span> 915</dt> 916<dd> 917<p>When set to <code class="varname">yes</code>, Valgrind will pause 918 after every error shown and print the line: 919 </p> 920<div class="literallayout"><p><code class="computeroutput">����----�Print�suppression�?�---�[Return/N/n/Y/y/C/c]�----</code></p></div> 921<p> 922 923 The prompt's behaviour is the same as for the 924 <code class="option">--db-attach</code> option (see below).</p> 925<p>If you choose to, Valgrind will print out a suppression for 926 this error. You can then cut and paste it into a suppression file 927 if you don't want to hear about the error in the future.</p> 928<p>When set to <code class="varname">all</code>, Valgrind will print a 929 suppression for every reported error, without querying the 930 user.</p> 931<p>This option is particularly useful with C++ programs, as it 932 prints out the suppressions with mangled names, as 933 required.</p> 934<p>Note that the suppressions printed are as specific as 935 possible. You may want to common up similar ones, by adding 936 wildcards to function names, and by using frame-level wildcards. 937 The wildcarding facilities are powerful yet flexible, and with a 938 bit of careful editing, you may be able to suppress a whole 939 family of related errors with only a few suppressions. 940 941 </p> 942<p>Sometimes two different errors 943 are suppressed by the same suppression, in which case Valgrind 944 will output the suppression more than once, but you only need to 945 have one copy in your suppression file (but having more than one 946 won't cause problems). Also, the suppression name is given as 947 <code class="computeroutput"><insert a suppression name 948 here></code>; the name doesn't really matter, it's 949 only used with the <code class="option">-v</code> option which prints out all 950 used suppression records.</p> 951</dd> 952<dt> 953<a name="opt.db-attach"></a><span class="term"> 954 <code class="option">--db-attach=<yes|no> [default: no] </code> 955 </span> 956</dt> 957<dd> 958<p>When enabled, Valgrind will pause after every error shown 959 and print the line: 960 </p> 961<div class="literallayout"><p><code class="computeroutput">����----�Attach�to�debugger�?�---�[Return/N/n/Y/y/C/c]�----</code></p></div> 962<p> 963 964 Pressing <code class="varname">Ret</code>, or <code class="varname">N Ret</code> or 965 <code class="varname">n Ret</code>, causes Valgrind not to start a debugger 966 for this error.</p> 967<p>Pressing <code class="varname">Y Ret</code> or 968 <code class="varname">y Ret</code> causes Valgrind to start a debugger for 969 the program at this point. When you have finished with the 970 debugger, quit from it, and the program will continue. Trying to 971 continue from inside the debugger doesn't work.</p> 972<p><code class="varname">C Ret</code> or <code class="varname">c Ret</code> causes 973 Valgrind not to start a debugger, and not to ask again.</p> 974</dd> 975<dt> 976<a name="opt.db-command"></a><span class="term"> 977 <code class="option">--db-command=<command> [default: gdb -nw %f %p] </code> 978 </span> 979</dt> 980<dd> 981<p>Specify the debugger to use with the 982 <code class="option">--db-attach</code> command. The default debugger is 983 GDB. This option is a template that is expanded by Valgrind at 984 runtime. <code class="literal">%f</code> is replaced with the executable's 985 file name and <code class="literal">%p</code> is replaced by the process ID 986 of the executable.</p> 987<p>This specifies how Valgrind will invoke the debugger. By 988 default it will use whatever GDB is detected at build time, which 989 is usually <code class="computeroutput">/usr/bin/gdb</code>. Using 990 this command, you can specify some alternative command to invoke 991 the debugger you want to use.</p> 992<p>The command string given can include one or instances of the 993 <code class="literal">%p</code> and <code class="literal">%f</code> expansions. Each 994 instance of <code class="literal">%p</code> expands to the PID of the 995 process to be debugged and each instance of <code class="literal">%f</code> 996 expands to the path to the executable for the process to be 997 debugged.</p> 998<p>Since <code class="computeroutput"><command></code> is likely 999 to contain spaces, you will need to put this entire option in 1000 quotes to ensure it is correctly handled by the shell.</p> 1001</dd> 1002<dt> 1003<a name="opt.input-fd"></a><span class="term"> 1004 <code class="option">--input-fd=<number> [default: 0, stdin] </code> 1005 </span> 1006</dt> 1007<dd><p>When using <code class="option">--db-attach=yes</code> or 1008 <code class="option">--gen-suppressions=yes</code>, Valgrind will stop so as 1009 to read keyboard input from you when each error occurs. By 1010 default it reads from the standard input (stdin), which is 1011 problematic for programs which close stdin. This option allows 1012 you to specify an alternative file descriptor from which to read 1013 input.</p></dd> 1014<dt> 1015<a name="opt.dsymutil"></a><span class="term"> 1016 <code class="option">--dsymutil=no|yes [no] </code> 1017 </span> 1018</dt> 1019<dd> 1020<p>This option is only relevant when running Valgrind on 1021 Mac OS X.</p> 1022<p>Mac OS X uses a deferred debug information (debuginfo) 1023 linking scheme. When object files containing debuginfo are 1024 linked into a <code class="computeroutput">.dylib</code> or an 1025 executable, the debuginfo is not copied into the final file. 1026 Instead, the debuginfo must be linked manually by 1027 running <code class="computeroutput">dsymutil</code>, a 1028 system-provided utility, on the executable 1029 or <code class="computeroutput">.dylib</code>. The resulting 1030 combined debuginfo is placed in a directory alongside the 1031 executable or <code class="computeroutput">.dylib</code>, but with 1032 the extension <code class="computeroutput">.dSYM</code>.</p> 1033<p>With <code class="option">--dsymutil=no</code>, Valgrind 1034 will detect cases where the 1035 <code class="computeroutput">.dSYM</code> directory is either 1036 missing, or is present but does not appear to match the 1037 associated executable or <code class="computeroutput">.dylib</code>, 1038 most likely because it is out of date. In these cases, Valgrind 1039 will print a warning message but take no further action.</p> 1040<p>With <code class="option">--dsymutil=yes</code>, Valgrind 1041 will, in such cases, automatically 1042 run <code class="computeroutput">dsymutil</code> as necessary to 1043 bring the debuginfo up to date. For all practical purposes, if 1044 you always use <code class="option">--dsymutil=yes</code>, then 1045 there is never any need to 1046 run <code class="computeroutput">dsymutil</code> manually or as part 1047 of your applications's build system, since Valgrind will run it 1048 as necessary.</p> 1049<p>Valgrind will not attempt to 1050 run <code class="computeroutput">dsymutil</code> on any 1051 executable or library in 1052 <code class="computeroutput">/usr/</code>, 1053 <code class="computeroutput">/bin/</code>, 1054 <code class="computeroutput">/sbin/</code>, 1055 <code class="computeroutput">/opt/</code>, 1056 <code class="computeroutput">/sw/</code>, 1057 <code class="computeroutput">/System/</code>, 1058 <code class="computeroutput">/Library/</code> or 1059 <code class="computeroutput">/Applications/</code> 1060 since <code class="computeroutput">dsymutil</code> will always fail 1061 in such situations. It fails both because the debuginfo for 1062 such pre-installed system components is not available anywhere, 1063 and also because it would require write privileges in those 1064 directories.</p> 1065<p>Be careful when 1066 using <code class="option">--dsymutil=yes</code>, since it will 1067 cause pre-existing <code class="computeroutput">.dSYM</code> 1068 directories to be silently deleted and re-created. Also note that 1069 <code class="computeroutput">dsymutil</code> is quite slow, sometimes 1070 excessively so.</p> 1071</dd> 1072<dt> 1073<a name="opt.max-stackframe"></a><span class="term"> 1074 <code class="option">--max-stackframe=<number> [default: 2000000] </code> 1075 </span> 1076</dt> 1077<dd> 1078<p>The maximum size of a stack frame. If the stack pointer moves by 1079 more than this amount then Valgrind will assume that 1080 the program is switching to a different stack.</p> 1081<p>You may need to use this option if your program has large 1082 stack-allocated arrays. Valgrind keeps track of your program's 1083 stack pointer. If it changes by more than the threshold amount, 1084 Valgrind assumes your program is switching to a different stack, 1085 and Memcheck behaves differently than it would for a stack pointer 1086 change smaller than the threshold. Usually this heuristic works 1087 well. However, if your program allocates large structures on the 1088 stack, this heuristic will be fooled, and Memcheck will 1089 subsequently report large numbers of invalid stack accesses. This 1090 option allows you to change the threshold to a different 1091 value.</p> 1092<p>You should only consider use of this option if Valgrind's 1093 debug output directs you to do so. In that case it will tell you 1094 the new threshold you should specify.</p> 1095<p>In general, allocating large structures on the stack is a 1096 bad idea, because you can easily run out of stack space, 1097 especially on systems with limited memory or which expect to 1098 support large numbers of threads each with a small stack, and also 1099 because the error checking performed by Memcheck is more effective 1100 for heap-allocated data than for stack-allocated data. If you 1101 have to use this option, you may wish to consider rewriting your 1102 code to allocate on the heap rather than on the stack.</p> 1103</dd> 1104<dt> 1105<a name="opt.main-stacksize"></a><span class="term"> 1106 <code class="option">--main-stacksize=<number> 1107 [default: use current 'ulimit' value] </code> 1108 </span> 1109</dt> 1110<dd> 1111<p>Specifies the size of the main thread's stack.</p> 1112<p>To simplify its memory management, Valgrind reserves all 1113 required space for the main thread's stack at startup. That 1114 means it needs to know the required stack size at 1115 startup.</p> 1116<p>By default, Valgrind uses the current "ulimit" value for 1117 the stack size, or 16 MB, whichever is lower. In many cases 1118 this gives a stack size in the range 8 to 16 MB, which almost 1119 never overflows for most applications.</p> 1120<p>If you need a larger total stack size, 1121 use <code class="option">--main-stacksize</code> to specify it. Only set 1122 it as high as you need, since reserving far more space than you 1123 need (that is, hundreds of megabytes more than you need) 1124 constrains Valgrind's memory allocators and may reduce the total 1125 amount of memory that Valgrind can use. This is only really of 1126 significance on 32-bit machines.</p> 1127<p>On Linux, you may request a stack of size up to 2GB. 1128 Valgrind will stop with a diagnostic message if the stack cannot 1129 be allocated. On AIX5 the allowed stack size is restricted to 1130 128MB.</p> 1131<p><code class="option">--main-stacksize</code> only affects the stack 1132 size for the program's initial thread. It has no bearing on the 1133 size of thread stacks, as Valgrind does not allocate 1134 those.</p> 1135<p>You may need to use both <code class="option">--main-stacksize</code> 1136 and <code class="option">--max-stackframe</code> together. It is important 1137 to understand that <code class="option">--main-stacksize</code> sets the 1138 maximum total stack size, 1139 whilst <code class="option">--max-stackframe</code> specifies the largest 1140 size of any one stack frame. You will have to work out 1141 the <code class="option">--main-stacksize</code> value for yourself 1142 (usually, if your applications segfaults). But Valgrind will 1143 tell you the needed <code class="option">--max-stackframe</code> size, if 1144 necessary.</p> 1145<p>As discussed further in the description 1146 of <code class="option">--max-stackframe</code>, a requirement for a large 1147 stack is a sign of potential portability problems. You are best 1148 advised to place all large data in heap-allocated memory.</p> 1149</dd> 1150</dl> 1151</div> 1152</div> 1153<div class="sect2" title="2.6.4.�malloc-related Options"> 1154<div class="titlepage"><div><div><h3 class="title"> 1155<a name="manual-core.mallocopts"></a>2.6.4.�malloc-related Options</h3></div></div></div> 1156<p><a name="malloc-related.opts.para"></a>For tools that use their own version of 1157<code class="computeroutput">malloc</code> (e.g. Memcheck and 1158Massif), the following options apply.</p> 1159<div class="variablelist"> 1160<a name="malloc-related.opts.list"></a><dl> 1161<dt> 1162<a name="opt.alignment"></a><span class="term"> 1163 <code class="option">--alignment=<number> [default: 8 or 16, depending on the platform] </code> 1164 </span> 1165</dt> 1166<dd><p>By default Valgrind's <code class="function">malloc</code>, 1167 <code class="function">realloc</code>, etc, return a block whose starting 1168 address is 8-byte aligned or 16-byte aligned (the value depends on the 1169 platform and matches the platform default). This option allows you to 1170 specify a different alignment. The supplied value must be greater 1171 than or equal to the default, less than or equal to 4096, and must be 1172 a power of two.</p></dd> 1173</dl> 1174</div> 1175</div> 1176<div class="sect2" title="2.6.5.�Uncommon Options"> 1177<div class="titlepage"><div><div><h3 class="title"> 1178<a name="manual-core.rareopts"></a>2.6.5.�Uncommon Options</h3></div></div></div> 1179<p><a name="uncommon.opts.para"></a>These options apply to all tools, as they 1180affect certain obscure workings of the Valgrind core. Most people won't 1181need to use these.</p> 1182<div class="variablelist"> 1183<a name="uncommon.opts.list"></a><dl> 1184<dt> 1185<a name="opt.smc-check"></a><span class="term"> 1186 <code class="option">--smc-check=<none|stack|all> [default: stack] </code> 1187 </span> 1188</dt> 1189<dd> 1190<p>This option controls Valgrind's detection of self-modifying 1191 code. If no checking is done, if a program executes some code, then 1192 overwrites it with new code, and executes the new code, Valgrind will 1193 continue to execute the translations it made for the old code. This 1194 will likely lead to incorrect behaviour and/or crashes.</p> 1195<p>Valgrind has three levels of self-modifying code detection: 1196 no detection, detect self-modifying code on the stack (which is used by 1197 GCC to implement nested functions), or detect self-modifying code 1198 everywhere. Note that the default option will catch the vast majority 1199 of cases. The main case it will not catch is programs such as JIT 1200 compilers that dynamically generate code <span class="emphasis"><em>and</em></span> 1201 subsequently overwrite part or all of it. Running with 1202 <code class="varname">all</code> will slow Valgrind down noticeably. Running with 1203 <code class="varname">none</code> will rarely speed things up, since very little 1204 code gets put on the stack for most programs. The 1205 <code class="function">VALGRIND_DISCARD_TRANSLATIONS</code> client request is 1206 an alternative to <code class="option">--smc-check=all</code> that requires more 1207 effort but is much faster. 1208 1209 </p> 1210<p>Some architectures (including ppc32, ppc64 and ARM) require 1211 programs which create code at runtime to flush the instruction 1212 cache in between code generation and first use. Valgrind 1213 observes and honours such instructions. Hence, on ppc32/Linux, 1214 ppc64/Linux and ARM/Linux, Valgrind always provides complete, transparent 1215 support for self-modifying code. It is only on platforms such as 1216 x86/Linux, AMD64/Linux and x86/Darwin that you need to use this 1217 option.</p> 1218</dd> 1219<dt> 1220<a name="opt.read-var-info"></a><span class="term"> 1221 <code class="option">--read-var-info=<yes|no> [default: no] </code> 1222 </span> 1223</dt> 1224<dd> 1225<p>When enabled, Valgrind will read information about 1226 variable types and locations from DWARF3 debug info. 1227 This slows Valgrind down and makes it use more memory, but for 1228 the tools that can take advantage of it (Memcheck, Helgrind, 1229 DRD) it can result in more precise error messages. For example, 1230 here are some standard errors issued by Memcheck:</p> 1231<pre class="programlisting"> 1232==15516== Uninitialised byte(s) found during client check request 1233==15516== at 0x400633: croak (varinfo1.c:28) 1234==15516== by 0x4006B2: main (varinfo1.c:55) 1235==15516== Address 0x60103b is 7 bytes inside data symbol "global_i2" 1236==15516== 1237==15516== Uninitialised byte(s) found during client check request 1238==15516== at 0x400633: croak (varinfo1.c:28) 1239==15516== by 0x4006BC: main (varinfo1.c:56) 1240==15516== Address 0x7fefffefc is on thread 1's stack</pre> 1241<p>And here are the same errors with 1242 <code class="option">--read-var-info=yes</code>:</p> 1243<pre class="programlisting"> 1244==15522== Uninitialised byte(s) found during client check request 1245==15522== at 0x400633: croak (varinfo1.c:28) 1246==15522== by 0x4006B2: main (varinfo1.c:55) 1247==15522== Location 0x60103b is 0 bytes inside global_i2[7], 1248==15522== a global variable declared at varinfo1.c:41 1249==15522== 1250==15522== Uninitialised byte(s) found during client check request 1251==15522== at 0x400633: croak (varinfo1.c:28) 1252==15522== by 0x4006BC: main (varinfo1.c:56) 1253==15522== Location 0x7fefffefc is 0 bytes inside local var "local" 1254==15522== declared at varinfo1.c:46, in frame #1 of thread 1</pre> 1255</dd> 1256<dt> 1257<a name="opt.run-libc-freeres"></a><span class="term"> 1258 <code class="option">--run-libc-freeres=<yes|no> [default: yes] </code> 1259 </span> 1260</dt> 1261<dd> 1262<p>This option is only relevant when running Valgrind on Linux.</p> 1263<p>The GNU C library (<code class="function">libc.so</code>), which is 1264 used by all programs, may allocate memory for its own uses. 1265 Usually it doesn't bother to free that memory when the program 1266 ends—there would be no point, since the Linux kernel reclaims 1267 all process resources when a process exits anyway, so it would 1268 just slow things down.</p> 1269<p>The glibc authors realised that this behaviour causes leak 1270 checkers, such as Valgrind, to falsely report leaks in glibc, when 1271 a leak check is done at exit. In order to avoid this, they 1272 provided a routine called <code class="function">__libc_freeres</code> 1273 specifically to make glibc release all memory it has allocated. 1274 Memcheck therefore tries to run 1275 <code class="function">__libc_freeres</code> at exit.</p> 1276<p>Unfortunately, in some very old versions of glibc, 1277 <code class="function">__libc_freeres</code> is sufficiently buggy to cause 1278 segmentation faults. This was particularly noticeable on Red Hat 1279 7.1. So this option is provided in order to inhibit the run of 1280 <code class="function">__libc_freeres</code>. If your program seems to run 1281 fine on Valgrind, but segfaults at exit, you may find that 1282 <code class="option">--run-libc-freeres=no</code> fixes that, although at the 1283 cost of possibly falsely reporting space leaks in 1284 <code class="filename">libc.so</code>.</p> 1285</dd> 1286<dt> 1287<a name="opt.sim-hints"></a><span class="term"> 1288 <code class="option">--sim-hints=hint1,hint2,... </code> 1289 </span> 1290</dt> 1291<dd> 1292<p>Pass miscellaneous hints to Valgrind which slightly modify 1293 the simulated behaviour in nonstandard or dangerous ways, possibly 1294 to help the simulation of strange features. By default no hints 1295 are enabled. Use with caution! Currently known hints are:</p> 1296<div class="itemizedlist"><ul class="itemizedlist" type="disc"> 1297<li class="listitem"><p><code class="option">lax-ioctls: </code> Be very lax about ioctl 1298 handling; the only assumption is that the size is 1299 correct. Doesn't require the full buffer to be initialized 1300 when writing. Without this, using some device drivers with a 1301 large number of strange ioctl commands becomes very 1302 tiresome.</p></li> 1303<li class="listitem"><p><code class="option">enable-inner: </code> Enable some special 1304 magic needed when the program being run is itself 1305 Valgrind.</p></li> 1306</ul></div> 1307</dd> 1308<dt> 1309<a name="opt.kernel-variant"></a><span class="term"> 1310 <code class="option">--kernel-variant=variant1,variant2,...</code> 1311 </span> 1312</dt> 1313<dd> 1314<p>Handle system calls and ioctls arising from minor variants 1315 of the default kernel for this platform. This is useful for 1316 running on hacked kernels or with kernel modules which support 1317 nonstandard ioctls, for example. Use with caution. If you don't 1318 understand what this option does then you almost certainly don't 1319 need it. Currently known variants are:</p> 1320<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="option">bproc: </code> Support the 1321 <code class="function">sys_broc</code> system call on x86. This is for 1322 running on BProc, which is a minor variant of standard Linux which 1323 is sometimes used for building clusters.</p></li></ul></div> 1324</dd> 1325<dt> 1326<a name="opt.show-emwarns"></a><span class="term"> 1327 <code class="option">--show-emwarns=<yes|no> [default: no] </code> 1328 </span> 1329</dt> 1330<dd><p>When enabled, Valgrind will emit warnings about its CPU 1331 emulation in certain cases. These are usually not 1332 interesting.</p></dd> 1333<dt> 1334<a name="opt.require-text-symbol"></a><span class="term"> 1335 <code class="option">--require-text-symbol=:sonamepatt:fnnamepatt</code> 1336 </span> 1337</dt> 1338<dd> 1339<p>When a shared object whose soname 1340 matches <code class="varname">sonamepatt</code> is loaded into the 1341 process, examine all the text symbols it exports. If none of 1342 those match <code class="varname">fnnamepatt</code>, print an error 1343 message and abandon the run. This makes it possible to ensure 1344 that the run does not continue unless a given shared object 1345 contains a particular function name. 1346 </p> 1347<p> 1348 Both <code class="varname">sonamepatt</code> and 1349 <code class="varname">fnnamepatt</code> can be written using the usual 1350 <code class="varname">?</code> and <code class="varname">*</code> wildcards. For 1351 example: <code class="varname">":*libc.so*:foo?bar"</code>. You may use 1352 characters other than a colon to separate the two patterns. It 1353 is only important that the first character and the separator 1354 character are the same. For example, the above example could 1355 also be written <code class="varname">"Q*libc.so*Qfoo?bar"</code>. 1356 Multiple <code class="varname"> --require-text-symbol</code> flags are 1357 allowed, in which case shared objects that are loaded into 1358 the process will be checked against all of them. 1359 </p> 1360<p> 1361 The purpose of this is to support reliable usage of marked-up 1362 libraries. For example, suppose we have a version of GCC's 1363 <code class="varname">libgomp.so</code> which has been marked up with 1364 annotations to support Helgrind. It is only too easy and 1365 confusing to load the wrong, un-annotated 1366 <code class="varname">libgomp.so</code> into the application. So the idea 1367 is: add a text symbol in the marked-up library, for 1368 example <code class="varname">annotated_for_helgrind_3_6</code>, and then 1369 give the flag 1370 <code class="varname">--require-text-symbol=:*libgomp*so*:annotated_for_helgrind_3_6</code> 1371 so that when <code class="varname">libgomp.so</code> is loaded, Valgrind 1372 scans its symbol table, and if the symbol isn't present the run 1373 is aborted, rather than continuing silently with the 1374 un-marked-up library. Note that you should put the entire flag 1375 in quotes to stop shells expanding up the <code class="varname">*</code> 1376 and <code class="varname">?</code> wildcards. 1377 </p> 1378</dd> 1379</dl> 1380</div> 1381</div> 1382<div class="sect2" title="2.6.6.�Debugging Options"> 1383<div class="titlepage"><div><div><h3 class="title"> 1384<a name="manual-core.debugopts"></a>2.6.6.�Debugging Options</h3></div></div></div> 1385<p><a name="debug.opts.para"></a>There are also some options for debugging 1386Valgrind itself. You shouldn't need to use them in the normal run of 1387things. If you wish to see the list, use the 1388<code class="option">--help-debug</code> option.</p> 1389</div> 1390<div class="sect2" title="2.6.7.�Setting Default Options"> 1391<div class="titlepage"><div><div><h3 class="title"> 1392<a name="manual-core.defopts"></a>2.6.7.�Setting Default Options</h3></div></div></div> 1393<p>Note that Valgrind also reads options from three places:</p> 1394<div class="orderedlist"><ol class="orderedlist" type="1"> 1395<li class="listitem"><p>The file <code class="computeroutput">~/.valgrindrc</code></p></li> 1396<li class="listitem"><p>The environment variable 1397 <code class="computeroutput">$VALGRIND_OPTS</code></p></li> 1398<li class="listitem"><p>The file <code class="computeroutput">./.valgrindrc</code></p></li> 1399</ol></div> 1400<p>These are processed in the given order, before the 1401command-line options. Options processed later override those 1402processed earlier; for example, options in 1403<code class="computeroutput">./.valgrindrc</code> will take 1404precedence over those in 1405<code class="computeroutput">~/.valgrindrc</code>. 1406</p> 1407<p>Please note that the <code class="computeroutput">./.valgrindrc</code> 1408file is ignored if it is marked as world writeable or not owned 1409by the current user. This is because the 1410<code class="computeroutput">./.valgrindrc</code> can contain options that are 1411potentially harmful or can be used by a local attacker to execute code under 1412your user account. 1413</p> 1414<p>Any tool-specific options put in 1415<code class="computeroutput">$VALGRIND_OPTS</code> or the 1416<code class="computeroutput">.valgrindrc</code> files should be 1417prefixed with the tool name and a colon. For example, if you 1418want Memcheck to always do leak checking, you can put the 1419following entry in <code class="literal">~/.valgrindrc</code>:</p> 1420<pre class="programlisting"> 1421--memcheck:leak-check=yes</pre> 1422<p>This will be ignored if any tool other than Memcheck is 1423run. Without the <code class="computeroutput">memcheck:</code> 1424part, this will cause problems if you select other tools that 1425don't understand 1426<code class="option">--leak-check=yes</code>.</p> 1427</div> 1428</div> 1429<div class="sect1" title="2.7.�Support for Threads"> 1430<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1431<a name="manual-core.pthreads"></a>2.7.�Support for Threads</h2></div></div></div> 1432<p>Threaded programs are fully supported.</p> 1433<p>The main thing to point out with respect to threaded programs is 1434that your program will use the native threading library, but Valgrind 1435serialises execution so that only one (kernel) thread is running at a 1436time. This approach avoids the horrible implementation problems of 1437implementing a truly multithreaded version of Valgrind, but it does 1438mean that threaded apps run only on one CPU, even if you have a 1439multiprocessor or multicore machine.</p> 1440<p>Valgrind doesn't schedule the threads itself. It merely ensures 1441that only one thread runs at once, using a simple locking scheme. The 1442actual thread scheduling remains under control of the OS kernel. What 1443this does mean, though, is that your program will see very different 1444scheduling when run on Valgrind than it does when running normally. 1445This is both because Valgrind is serialising the threads, and because 1446the code runs so much slower than normal.</p> 1447<p>This difference in scheduling may cause your program to behave 1448differently, if you have some kind of concurrency, critical race, 1449locking, or similar, bugs. In that case you might consider using the 1450tools Helgrind and/or DRD to track them down.</p> 1451<p>On Linux, Valgrind also supports direct use of the 1452<code class="computeroutput">clone</code> system call, 1453<code class="computeroutput">futex</code> and so on. 1454<code class="computeroutput">clone</code> is supported where either 1455everything is shared (a thread) or nothing is shared (fork-like); partial 1456sharing will fail. 1457</p> 1458</div> 1459<div class="sect1" title="2.8.�Handling of Signals"> 1460<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1461<a name="manual-core.signals"></a>2.8.�Handling of Signals</h2></div></div></div> 1462<p>Valgrind has a fairly complete signal implementation. It should be 1463able to cope with any POSIX-compliant use of signals.</p> 1464<p>If you're using signals in clever ways (for example, catching 1465SIGSEGV, modifying page state and restarting the instruction), you're 1466probably relying on precise exceptions. In this case, you will need 1467to use <code class="option">--vex-iropt-precise-memory-exns=yes</code>. 1468</p> 1469<p>If your program dies as a result of a fatal core-dumping signal, 1470Valgrind will generate its own core file 1471(<code class="computeroutput">vgcore.NNNNN</code>) containing your program's 1472state. You may use this core file for post-mortem debugging with GDB or 1473similar. (Note: it will not generate a core if your core dump size limit is 14740.) At the time of writing the core dumps do not include all the floating 1475point register information.</p> 1476<p>In the unlikely event that Valgrind itself crashes, the operating system 1477will create a core dump in the usual way.</p> 1478</div> 1479<div class="sect1" title="2.9.�Building and Installing Valgrind"> 1480<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1481<a name="manual-core.install"></a>2.9.�Building and Installing Valgrind</h2></div></div></div> 1482<p>We use the standard Unix 1483<code class="computeroutput">./configure</code>, 1484<code class="computeroutput">make</code>, <code class="computeroutput">make 1485install</code> mechanism. Once you have completed 1486<code class="computeroutput">make install</code> you may then want 1487to run the regression tests 1488with <code class="computeroutput">make regtest</code>. 1489</p> 1490<p>In addition to the usual 1491<code class="option">--prefix=/path/to/install/tree</code>, there are three 1492 options which affect how Valgrind is built: 1493</p> 1494<div class="itemizedlist"><ul class="itemizedlist" type="disc"> 1495<li class="listitem"> 1496<p><code class="option">--enable-inner</code></p> 1497<p>This builds Valgrind with some special magic hacks which make 1498 it possible to run it on a standard build of Valgrind (what the 1499 developers call "self-hosting"). Ordinarily you should not use 1500 this option as various kinds of safety checks are disabled. 1501 </p> 1502</li> 1503<li class="listitem"> 1504<p><code class="option">--enable-only64bit</code></p> 1505<p><code class="option">--enable-only32bit</code></p> 1506<p>On 64-bit platforms (amd64-linux, ppc64-linux, 1507 amd64-darwin), Valgrind is by default built in such a way that 1508 both 32-bit and 64-bit executables can be run. Sometimes this 1509 cleverness is a problem for a variety of reasons. These two 1510 options allow for single-target builds in this situation. If you 1511 issue both, the configure script will complain. Note they are 1512 ignored on 32-bit-only platforms (x86-linux, ppc32-linux, 1513 arm-linux, x86-darwin). 1514 </p> 1515</li> 1516</ul></div> 1517<p> 1518</p> 1519<p>The <code class="computeroutput">configure</code> script tests 1520the version of the X server currently indicated by the current 1521<code class="computeroutput">$DISPLAY</code>. This is a known bug. 1522The intention was to detect the version of the current X 1523client libraries, so that correct suppressions could be selected 1524for them, but instead the test checks the server version. This 1525is just plain wrong.</p> 1526<p>If you are building a binary package of Valgrind for 1527distribution, please read <code class="literal">README_PACKAGERS</code> 1528<a class="xref" href="dist.readme-packagers.html" title="6.�README_PACKAGERS">Readme Packagers</a>. It contains some 1529important information.</p> 1530<p>Apart from that, there's not much excitement here. Let us 1531know if you have build problems.</p> 1532</div> 1533<div class="sect1" title="2.10.�If You Have Problems"> 1534<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1535<a name="manual-core.problems"></a>2.10.�If You Have Problems</h2></div></div></div> 1536<p>Contact us at <a class="ulink" href="http://www.valgrind.org/" target="_top">http://www.valgrind.org/</a>.</p> 1537<p>See <a class="xref" href="manual-core.html#manual-core.limits" title="2.11.�Limitations">Limitations</a> for the known 1538limitations of Valgrind, and for a list of programs which are 1539known not to work on it.</p> 1540<p>All parts of the system make heavy use of assertions and 1541internal self-checks. They are permanently enabled, and we have no 1542plans to disable them. If one of them breaks, please mail us!</p> 1543<p>If you get an assertion failure 1544in <code class="filename">m_mallocfree.c</code>, this may have happened because 1545your program wrote off the end of a heap block, or before its 1546beginning, thus corrupting head metadata. Valgrind hopefully will have 1547emitted a message to that effect before dying in this way.</p> 1548<p>Read the <a class="xref" href="FAQ.html" title="Valgrind FAQ">Valgrind FAQ</a> for more advice about common problems, 1549crashes, etc.</p> 1550</div> 1551<div class="sect1" title="2.11.�Limitations"> 1552<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1553<a name="manual-core.limits"></a>2.11.�Limitations</h2></div></div></div> 1554<p>The following list of limitations seems long. However, most 1555programs actually work fine.</p> 1556<p>Valgrind will run programs on the supported platforms 1557subject to the following constraints:</p> 1558<div class="itemizedlist"><ul class="itemizedlist" type="disc"> 1559<li class="listitem"><p>On x86 and amd64, there is no support for 3DNow! 1560 instructions. If the translator encounters these, Valgrind will 1561 generate a SIGILL when the instruction is executed. Apart from 1562 that, on x86 and amd64, essentially all instructions are supported, 1563 up to and including SSE4.2 in 64-bit mode and SSSE3 in 32-bit mode. 1564 Some exceptions: SSE4.2 AES instructions are not supported in 1565 64-bit mode, and 32-bit mode does in fact support the bare minimum 1566 SSE4 instructions to needed to run programs on MacOSX 10.6 on 1567 32-bit targets. 1568 </p></li> 1569<li class="listitem"><p>On ppc32 and ppc64, almost all integer, floating point and 1570 Altivec instructions are supported. Specifically: integer and FP 1571 insns that are mandatory for PowerPC, the "General-purpose 1572 optional" group (fsqrt, fsqrts, stfiwx), the "Graphics optional" 1573 group (fre, fres, frsqrte, frsqrtes), and the Altivec (also known 1574 as VMX) SIMD instruction set, are supported. Also, instructions 1575 from the Power ISA 2.05 specification, as present in POWER6 CPUs, 1576 are supported.</p></li> 1577<li class="listitem"><p>On ARM, essentially the entire ARMv7-A instruction set 1578 is supported, in both ARM and Thumb mode. ThumbEE and Jazelle are 1579 not supported. NEON and VFPv3 support is fairly complete. ARMv6 1580 media instruction support is mostly done but not yet complete. 1581 </p></li> 1582<li class="listitem"><p>If your program does its own memory management, rather than 1583 using malloc/new/free/delete, it should still work, but Memcheck's 1584 error checking won't be so effective. If you describe your 1585 program's memory management scheme using "client requests" (see 1586 <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 1587 better. Nevertheless, using malloc/new and free/delete is still 1588 the best approach.</p></li> 1589<li class="listitem"><p>Valgrind's signal simulation is not as robust as it could be. 1590 Basic POSIX-compliant sigaction and sigprocmask functionality is 1591 supplied, but it's conceivable that things could go badly awry if you 1592 do weird things with signals. Workaround: don't. Programs that do 1593 non-POSIX signal tricks are in any case inherently unportable, so 1594 should be avoided if possible.</p></li> 1595<li class="listitem"><p>Machine instructions, and system calls, have been implemented 1596 on demand. So it's possible, although unlikely, that a program will 1597 fall over with a message to that effect. If this happens, please 1598 report all the details printed out, so we can try and implement the 1599 missing feature.</p></li> 1600<li class="listitem"><p>Memory consumption of your program is majorly increased 1601 whilst running under Valgrind's Memcheck tool. This is due to the 1602 large amount of administrative information maintained behind the 1603 scenes. Another cause is that Valgrind dynamically translates the 1604 original executable. Translated, instrumented code is 12-18 times 1605 larger than the original so you can easily end up with 100+ MB of 1606 translations when running (eg) a web browser.</p></li> 1607<li class="listitem"> 1608<p>Valgrind can handle dynamically-generated code just fine. If 1609 you regenerate code over the top of old code (ie. at the same 1610 memory addresses), if the code is on the stack Valgrind will 1611 realise the code has changed, and work correctly. This is 1612 necessary to handle the trampolines GCC uses to implemented nested 1613 functions. If you regenerate code somewhere other than the stack, 1614 and you are running on an 32- or 64-bit x86 CPU, you will need to 1615 use the <code class="option">--smc-check=all</code> option, and Valgrind will 1616 run more slowly than normal. Or you can add client requests that 1617 tell Valgrind when your program has overwritten code. 1618 </p> 1619<p> On other platforms (ARM, PowerPC) Valgrind observes and 1620 honours the cache invalidation hints that programs are obliged to 1621 emit to notify new code, and so self-modifying-code support should 1622 work automatically, without the need 1623 for <code class="option">--smc-check=all</code>.</p> 1624</li> 1625<li class="listitem"> 1626<p>Valgrind has the following limitations 1627 in its implementation of x86/AMD64 floating point relative to 1628 IEEE754.</p> 1629<p>Precision: There is no support for 80 bit arithmetic. 1630 Internally, Valgrind represents all such "long double" numbers in 64 1631 bits, and so there may be some differences in results. Whether or 1632 not this is critical remains to be seen. Note, the x86/amd64 1633 fldt/fstpt instructions (read/write 80-bit numbers) are correctly 1634 simulated, using conversions to/from 64 bits, so that in-memory 1635 images of 80-bit numbers look correct if anyone wants to see.</p> 1636<p>The impression observed from many FP regression tests is that 1637 the accuracy differences aren't significant. Generally speaking, if 1638 a program relies on 80-bit precision, there may be difficulties 1639 porting it to non x86/amd64 platforms which only support 64-bit FP 1640 precision. Even on x86/amd64, the program may get different results 1641 depending on whether it is compiled to use SSE2 instructions (64-bits 1642 only), or x87 instructions (80-bit). The net effect is to make FP 1643 programs behave as if they had been run on a machine with 64-bit IEEE 1644 floats, for example PowerPC. On amd64 FP arithmetic is done by 1645 default on SSE2, so amd64 looks more like PowerPC than x86 from an FP 1646 perspective, and there are far fewer noticeable accuracy differences 1647 than with x86.</p> 1648<p>Rounding: Valgrind does observe the 4 IEEE-mandated rounding 1649 modes (to nearest, to +infinity, to -infinity, to zero) for the 1650 following conversions: float to integer, integer to float where 1651 there is a possibility of loss of precision, and float-to-float 1652 rounding. For all other FP operations, only the IEEE default mode 1653 (round to nearest) is supported.</p> 1654<p>Numeric exceptions in FP code: IEEE754 defines five types of 1655 numeric exception that can happen: invalid operation (sqrt of 1656 negative number, etc), division by zero, overflow, underflow, 1657 inexact (loss of precision).</p> 1658<p>For each exception, two courses of action are defined by IEEE754: 1659 either (1) a user-defined exception handler may be called, or (2) a 1660 default action is defined, which "fixes things up" and allows the 1661 computation to proceed without throwing an exception.</p> 1662<p>Currently Valgrind only supports the default fixup actions. 1663 Again, feedback on the importance of exception support would be 1664 appreciated.</p> 1665<p>When Valgrind detects that the program is trying to exceed any 1666 of these limitations (setting exception handlers, rounding mode, or 1667 precision control), it can print a message giving a traceback of 1668 where this has happened, and continue execution. This behaviour used 1669 to be the default, but the messages are annoying and so showing them 1670 is now disabled by default. Use <code class="option">--show-emwarns=yes</code> to see 1671 them.</p> 1672<p>The above limitations define precisely the IEEE754 'default' 1673 behaviour: default fixup on all exceptions, round-to-nearest 1674 operations, and 64-bit precision.</p> 1675</li> 1676<li class="listitem"> 1677<p>Valgrind has the following limitations in 1678 its implementation of x86/AMD64 SSE2 FP arithmetic, relative to 1679 IEEE754.</p> 1680<p>Essentially the same: no exceptions, and limited observance of 1681 rounding mode. Also, SSE2 has control bits which make it treat 1682 denormalised numbers as zero (DAZ) and a related action, flush 1683 denormals to zero (FTZ). Both of these cause SSE2 arithmetic to be 1684 less accurate than IEEE requires. Valgrind detects, ignores, and can 1685 warn about, attempts to enable either mode.</p> 1686</li> 1687<li class="listitem"> 1688<p>Valgrind has the following limitations in 1689 its implementation of ARM VFPv3 arithmetic, relative to 1690 IEEE754.</p> 1691<p>Essentially the same: no exceptions, and limited observance 1692 of rounding mode. Also, switching the VFP unit into vector mode 1693 will cause Valgrind to abort the program -- it has no way to 1694 emulate vector uses of VFP at a reasonable performance level. This 1695 is no big deal given that non-scalar uses of VFP instructions are 1696 in any case deprecated.</p> 1697</li> 1698<li class="listitem"> 1699<p>Valgrind has the following limitations 1700 in its implementation of PPC32 and PPC64 floating point 1701 arithmetic, relative to IEEE754.</p> 1702<p>Scalar (non-Altivec): Valgrind provides a bit-exact emulation of 1703 all floating point instructions, except for "fre" and "fres", which are 1704 done more precisely than required by the PowerPC architecture specification. 1705 All floating point operations observe the current rounding mode. 1706 </p> 1707<p>However, fpscr[FPRF] is not set after each operation. That could 1708 be done but would give measurable performance overheads, and so far 1709 no need for it has been found.</p> 1710<p>As on x86/AMD64, IEEE754 exceptions are not supported: all floating 1711 point exceptions are handled using the default IEEE fixup actions. 1712 Valgrind detects, ignores, and can warn about, attempts to unmask 1713 the 5 IEEE FP exception kinds by writing to the floating-point status 1714 and control register (fpscr). 1715 </p> 1716<p>Vector (Altivec, VMX): essentially as with x86/AMD64 SSE/SSE2: 1717 no exceptions, and limited observance of rounding mode. 1718 For Altivec, FP arithmetic 1719 is done in IEEE/Java mode, which is more accurate than the Linux default 1720 setting. "More accurate" means that denormals are handled properly, 1721 rather than simply being flushed to zero.</p> 1722</li> 1723</ul></div> 1724<p>Programs which are known not to work are:</p> 1725<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>emacs starts up but immediately concludes it is out of 1726 memory and aborts. It may be that Memcheck does not provide 1727 a good enough emulation of the 1728 <code class="computeroutput">mallinfo</code> function. 1729 Emacs works fine if you build it to use 1730 the standard malloc/free routines.</p></li></ul></div> 1731</div> 1732<div class="sect1" title="2.12.�An Example Run"> 1733<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1734<a name="manual-core.example"></a>2.12.�An Example Run</h2></div></div></div> 1735<p>This is the log for a run of a small program using Memcheck. 1736The program is in fact correct, and the reported error is as the 1737result of a potentially serious code generation bug in GNU g++ 1738(snapshot 20010527).</p> 1739<pre class="programlisting"> 1740sewardj@phoenix:~/newmat10$ ~/Valgrind-6/valgrind -v ./bogon 1741==25832== Valgrind 0.10, a memory error detector for x86 RedHat 7.1. 1742==25832== Copyright (C) 2000-2001, and GNU GPL'd, by Julian Seward. 1743==25832== Startup, with flags: 1744==25832== --suppressions=/home/sewardj/Valgrind/redhat71.supp 1745==25832== reading syms from /lib/ld-linux.so.2 1746==25832== reading syms from /lib/libc.so.6 1747==25832== reading syms from /mnt/pima/jrs/Inst/lib/libgcc_s.so.0 1748==25832== reading syms from /lib/libm.so.6 1749==25832== reading syms from /mnt/pima/jrs/Inst/lib/libstdc++.so.3 1750==25832== reading syms from /home/sewardj/Valgrind/valgrind.so 1751==25832== reading syms from /proc/self/exe 1752==25832== 1753==25832== Invalid read of size 4 1754==25832== at 0x8048724: BandMatrix::ReSize(int,int,int) (bogon.cpp:45) 1755==25832== by 0x80487AF: main (bogon.cpp:66) 1756==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd 1757==25832== 1758==25832== ERROR SUMMARY: 1 errors from 1 contexts (suppressed: 0 from 0) 1759==25832== malloc/free: in use at exit: 0 bytes in 0 blocks. 1760==25832== malloc/free: 0 allocs, 0 frees, 0 bytes allocated. 1761==25832== For a detailed leak analysis, rerun with: --leak-check=yes 1762</pre> 1763<p>The GCC folks fixed this about a week before GCC 3.0 1764shipped.</p> 1765</div> 1766<div class="sect1" title="2.13.�Warning Messages You Might See"> 1767<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1768<a name="manual-core.warnings"></a>2.13.�Warning Messages You Might See</h2></div></div></div> 1769<p>Some of these only appear if you run in verbose mode 1770(enabled by <code class="option">-v</code>):</p> 1771<div class="itemizedlist"><ul class="itemizedlist" type="disc"> 1772<li class="listitem"> 1773<p><code class="computeroutput">More than 100 errors detected. Subsequent 1774 errors will still be recorded, but in less detail than 1775 before.</code></p> 1776<p>After 100 different errors have been shown, Valgrind becomes 1777 more conservative about collecting them. It then requires only the 1778 program counters in the top two stack frames to match when deciding 1779 whether or not two errors are really the same one. Prior to this 1780 point, the PCs in the top four frames are required to match. This 1781 hack has the effect of slowing down the appearance of new errors 1782 after the first 100. The 100 constant can be changed by recompiling 1783 Valgrind.</p> 1784</li> 1785<li class="listitem"> 1786<p><code class="computeroutput">More than 1000 errors detected. I'm not 1787 reporting any more. Final error counts may be inaccurate. Go fix 1788 your program!</code></p> 1789<p>After 1000 different errors have been detected, Valgrind 1790 ignores any more. It seems unlikely that collecting even more 1791 different ones would be of practical help to anybody, and it avoids 1792 the danger that Valgrind spends more and more of its time comparing 1793 new errors against an ever-growing collection. As above, the 1000 1794 number is a compile-time constant.</p> 1795</li> 1796<li class="listitem"> 1797<p><code class="computeroutput">Warning: client switching stacks?</code></p> 1798<p>Valgrind spotted such a large change in the stack pointer 1799 that it guesses the client is switching to 1800 a different stack. At this point it makes a kludgey guess where the 1801 base of the new stack is, and sets memory permissions accordingly. 1802 You may get many bogus error messages following this, if Valgrind 1803 guesses wrong. At the moment "large change" is defined as a change 1804 of more that 2000000 in the value of the 1805 stack pointer register.</p> 1806</li> 1807<li class="listitem"> 1808<p><code class="computeroutput">Warning: client attempted to close Valgrind's 1809 logfile fd <number></code></p> 1810<p>Valgrind doesn't allow the client to close the logfile, 1811 because you'd never see any diagnostic information after that point. 1812 If you see this message, you may want to use the 1813 <code class="option">--log-fd=<number></code> option to specify a 1814 different logfile file-descriptor number.</p> 1815</li> 1816<li class="listitem"> 1817<p><code class="computeroutput">Warning: noted but unhandled ioctl 1818 <number></code></p> 1819<p>Valgrind observed a call to one of the vast family of 1820 <code class="computeroutput">ioctl</code> system calls, but did not 1821 modify its memory status info (because nobody has yet written a 1822 suitable wrapper). The call will still have gone through, but you may get 1823 spurious errors after this as a result of the non-update of the 1824 memory info.</p> 1825</li> 1826<li class="listitem"> 1827<p><code class="computeroutput">Warning: set address range perms: large range 1828 <number></code></p> 1829<p>Diagnostic message, mostly for benefit of the Valgrind 1830 developers, to do with memory permissions.</p> 1831</li> 1832</ul></div> 1833</div> 1834</div> 1835<div> 1836<br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer"> 1837<tr> 1838<td rowspan="2" width="40%" align="left"> 1839<a accesskey="p" href="manual-intro.html"><<�1.�Introduction</a>�</td> 1840<td width="20%" align="center"><a accesskey="u" href="manual.html">Up</a></td> 1841<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> 1842</td> 1843</tr> 1844<tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr> 1845</table> 1846</div> 1847</body> 1848</html> 1849
