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