1 <?xml version="1.0"?> <!-- -*- sgml -*- -->
2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
4 [ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
7 <chapter id="manual-core" xreflabel="Valgrind's core">
8 <title>Using and understanding the Valgrind core</title>
10 <para>This chapter describes the Valgrind core services, command-line
11 options and behaviours. That means it is relevant regardless of what
12 particular tool you are using. The information should be sufficient for you
13 to make effective day-to-day use of Valgrind. Advanced topics related to
14 the Valgrind core are described in <xref linkend="manual-core-adv"/>.
18 A point of terminology: most references to "Valgrind" in this chapter
19 refer to the Valgrind core services. </para>
23 <sect1 id="manual-core.whatdoes"
24 xreflabel="What Valgrind does with your program">
25 <title>What Valgrind does with your program</title>
27 <para>Valgrind is designed to be as non-intrusive as possible. It works
28 directly with existing executables. You don't need to recompile, relink,
29 or otherwise modify the program to be checked.</para>
31 <para>You invoke Valgrind like this:</para>
32 <programlisting><![CDATA[
33 valgrind [valgrind-options] your-prog [your-prog-options]]]></programlisting>
35 <para>The most important option is <option>--tool</option> which dictates
36 which Valgrind tool to run. For example, if want to run the command
37 <computeroutput>ls -l</computeroutput> using the memory-checking tool
38 Memcheck, issue this command:</para>
40 <programlisting><![CDATA[
41 valgrind --tool=memcheck ls -l]]></programlisting>
43 <para>However, Memcheck is the default, so if you want to use it you can
44 omit the <option>--tool</option> option.</para>
46 <para>Regardless of which tool is in use, Valgrind takes control of your
47 program before it starts. Debugging information is read from the
48 executable and associated libraries, so that error messages and other
49 outputs can be phrased in terms of source code locations, when
52 <para>Your program is then run on a synthetic CPU provided by the
53 Valgrind core. As new code is executed for the first time, the core
54 hands the code to the selected tool. The tool adds its own
55 instrumentation code to this and hands the result back to the core,
56 which coordinates the continued execution of this instrumented
59 <para>The amount of instrumentation code added varies widely between
60 tools. At one end of the scale, Memcheck adds code to check every
61 memory access and every value computed,
62 making it run 10-50 times slower than natively.
63 At the other end of the spectrum, the minimal tool, called Nulgrind,
64 adds no instrumentation at all and causes in total "only" about a 4 times
67 <para>Valgrind simulates every single instruction your program executes.
68 Because of this, the active tool checks, or profiles, not only the code
69 in your application but also in all supporting dynamically-linked libraries,
70 including the C library, graphical libraries, and so on.</para>
72 <para>If you're using an error-detection tool, Valgrind may
73 detect errors in system libraries, for example the GNU C or X11
74 libraries, which you have to use. You might not be interested in these
75 errors, since you probably have no control over that code. Therefore,
76 Valgrind allows you to selectively suppress errors, by recording them in
77 a suppressions file which is read when Valgrind starts up. The build
78 mechanism selects default suppressions which give reasonable
79 behaviour for the OS and libraries detected on your machine.
80 To make it easier to write suppressions, you can use the
81 <option>--gen-suppressions=yes</option> option. This tells Valgrind to
82 print out a suppression for each reported error, which you can then
83 copy into a suppressions file.</para>
85 <para>Different error-checking tools report different kinds of errors.
86 The suppression mechanism therefore allows you to say which tool or
87 tool(s) each suppression applies to.</para>
92 <sect1 id="manual-core.started" xreflabel="Getting started">
93 <title>Getting started</title>
95 <para>First off, consider whether it might be beneficial to recompile
96 your application and supporting libraries with debugging info enabled
97 (the <option>-g</option> option). Without debugging info, the best
98 Valgrind tools will be able to do is guess which function a particular
99 piece of code belongs to, which makes both error messages and profiling
100 output nearly useless. With <option>-g</option>, you'll get
101 messages which point directly to the relevant source code lines.</para>
103 <para>Another option you might like to consider, if you are working with
104 C++, is <option>-fno-inline</option>. That makes it easier to see the
105 function-call chain, which can help reduce confusion when navigating
106 around large C++ apps. For example, debugging
107 OpenOffice.org with Memcheck is a bit easier when using this option. You
108 don't have to do this, but doing so helps Valgrind produce more accurate
109 and less confusing error reports. Chances are you're set up like this
110 already, if you intended to debug your program with GNU GDB, or some
111 other debugger. Alternatively, the Valgrind option
112 <option>--read-inline-info=yes</option> instructs Valgrind to read
113 the debug information describing inlining information. With this,
114 function call chain will be properly shown, even when your application
115 is compiled with inlining. </para>
117 <para>If you are planning to use Memcheck: On rare
118 occasions, compiler optimisations (at <option>-O2</option>
119 and above, and sometimes <option>-O1</option>) have been
120 observed to generate code which fools Memcheck into wrongly reporting
121 uninitialised value errors, or missing uninitialised value errors. We have
122 looked in detail into fixing this, and unfortunately the result is that
123 doing so would give a further significant slowdown in what is already a slow
124 tool. So the best solution is to turn off optimisation altogether. Since
125 this often makes things unmanageably slow, a reasonable compromise is to use
126 <option>-O</option>. This gets you the majority of the
127 benefits of higher optimisation levels whilst keeping relatively small the
128 chances of false positives or false negatives from Memcheck. Also, you
129 should compile your code with <option>-Wall</option> because
130 it can identify some or all of the problems that Valgrind can miss at the
131 higher optimisation levels. (Using <option>-Wall</option>
132 is also a good idea in general.) All other tools (as far as we know) are
133 unaffected by optimisation level, and for profiling tools like Cachegrind it
134 is better to compile your program at its normal optimisation level.</para>
136 <para>Valgrind understands the DWARF2/3/4 formats used by GCC 3.1 and
137 later. The reader for "stabs" debugging format (used by GCC versions
138 prior to 3.1) has been disabled in Valgrind 3.9.0.</para>
140 <para>When you're ready to roll, run Valgrind as described above.
141 Note that you should run the real
142 (machine-code) executable here. If your application is started by, for
143 example, a shell or Perl script, you'll need to modify it to invoke
144 Valgrind on the real executables. Running such scripts directly under
145 Valgrind will result in you getting error reports pertaining to
146 <filename>/bin/sh</filename>,
147 <filename>/usr/bin/perl</filename>, or whatever interpreter
148 you're using. This may not be what you want and can be confusing. You
149 can force the issue by giving the option
150 <option>--trace-children=yes</option>, but confusion is still
156 <!-- Referenced from both the manual and manpage -->
157 <sect1 id="&vg-comment-id;" xreflabel="&vg-comment-label;">
158 <title>The Commentary</title>
160 <para>Valgrind tools write a commentary, a stream of text, detailing
161 error reports and other significant events. All lines in the commentary
164 <programlisting><![CDATA[
165 ==12345== some-message-from-Valgrind]]></programlisting>
168 <para>The <computeroutput>12345</computeroutput> is the process ID.
169 This scheme makes it easy to distinguish program output from Valgrind
170 commentary, and also easy to differentiate commentaries from different
171 processes which have become merged together, for whatever reason.</para>
173 <para>By default, Valgrind tools write only essential messages to the
174 commentary, so as to avoid flooding you with information of secondary
175 importance. If you want more information about what is happening,
176 re-run, passing the <option>-v</option> option to Valgrind. A second
177 <option>-v</option> gives yet more detail.
180 <para>You can direct the commentary to three different places:</para>
184 <listitem id="manual-core.out2fd" xreflabel="Directing output to fd">
185 <para>The default: send it to a file descriptor, which is by default
186 2 (stderr). So, if you give the core no options, it will write
187 commentary to the standard error stream. If you want to send it to
188 some other file descriptor, for example number 9, you can specify
189 <option>--log-fd=9</option>.</para>
191 <para>This is the simplest and most common arrangement, but can
192 cause problems when Valgrinding entire trees of processes which
193 expect specific file descriptors, particularly stdin/stdout/stderr,
194 to be available for their own use.</para>
197 <listitem id="manual-core.out2file"
198 xreflabel="Directing output to file"> <para>A less intrusive
199 option is to write the commentary to a file, which you specify by
200 <option>--log-file=filename</option>. There are special format
201 specifiers that can be used to use a process ID or an environment
202 variable name in the log file name. These are useful/necessary if your
203 program invokes multiple processes (especially for MPI programs).
204 See the <link linkend="manual-core.basicopts">basic options section</link>
205 for more details.</para>
208 <listitem id="manual-core.out2socket"
209 xreflabel="Directing output to network socket"> <para>The
210 least intrusive option is to send the commentary to a network
211 socket. The socket is specified as an IP address and port number
212 pair, like this: <option>--log-socket=192.168.0.1:12345</option> if
213 you want to send the output to host IP 192.168.0.1 port 12345
215 have no idea if 12345 is a port of pre-existing significance). You
216 can also omit the port number:
217 <option>--log-socket=192.168.0.1</option>, in which case a default
218 port of 1500 is used. This default is defined by the constant
219 <computeroutput>VG_CLO_DEFAULT_LOGPORT</computeroutput> in the
222 <para>Note, unfortunately, that you have to use an IP address here,
223 rather than a hostname.</para>
225 <para>Writing to a network socket is pointless if you don't
226 have something listening at the other end. We provide a simple
228 <computeroutput>valgrind-listener</computeroutput>, which accepts
229 connections on the specified port and copies whatever it is sent to
230 stdout. Probably someone will tell us this is a horrible security
231 risk. It seems likely that people will write more sophisticated
232 listeners in the fullness of time.</para>
234 <para><computeroutput>valgrind-listener</computeroutput> can accept
235 simultaneous connections from up to 50 Valgrinded processes. In front
236 of each line of output it prints the current number of active
237 connections in round brackets.</para>
239 <para><computeroutput>valgrind-listener</computeroutput> accepts three
240 command-line options:</para>
241 <!-- start of xi:include in the manpage -->
242 <variablelist id="listener.opts.list">
244 <term><option>-e --exit-at-zero</option></term>
246 <para>When the number of connected processes falls back to zero,
247 exit. Without this, it will run forever, that is, until you
248 send it Control-C.</para>
252 <term><option>--max-connect=INTEGER</option></term>
254 <para>By default, the listener can connect to up to 50 processes.
255 Occasionally, that number is too small. Use this option to
256 provide a different limit. E.g.
257 <computeroutput>--max-connect=100</computeroutput>.
262 <term><option>portnumber</option></term>
264 <para>Changes the port it listens on from the default (1500).
265 The specified port must be in the range 1024 to 65535.
266 The same restriction applies to port numbers specified by a
267 <option>--log-socket</option> to Valgrind itself.</para>
271 <!-- end of xi:include in the manpage -->
273 <para>If a Valgrinded process fails to connect to a listener, for
274 whatever reason (the listener isn't running, invalid or unreachable
275 host or port, etc), Valgrind switches back to writing the commentary
276 to stderr. The same goes for any process which loses an established
277 connection to a listener. In other words, killing the listener
278 doesn't kill the processes sending data to it.</para>
283 <para>Here is an important point about the relationship between the
284 commentary and profiling output from tools. The commentary contains a
285 mix of messages from the Valgrind core and the selected tool. If the
286 tool reports errors, it will report them to the commentary. However, if
287 the tool does profiling, the profile data will be written to a file of
288 some kind, depending on the tool, and independent of what
289 <option>--log-*</option> options are in force. The commentary is
290 intended to be a low-bandwidth, human-readable channel. Profiling data,
291 on the other hand, is usually voluminous and not meaningful without
292 further processing, which is why we have chosen this arrangement.</para>
297 <sect1 id="manual-core.report" xreflabel="Reporting of errors">
298 <title>Reporting of errors</title>
300 <para>When an error-checking tool
301 detects something bad happening in the program, an error
302 message is written to the commentary. Here's an example from Memcheck:</para>
304 <programlisting><![CDATA[
305 ==25832== Invalid read of size 4
306 ==25832== at 0x8048724: BandMatrix::ReSize(int, int, int) (bogon.cpp:45)
307 ==25832== by 0x80487AF: main (bogon.cpp:66)
308 ==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd]]></programlisting>
310 <para>This message says that the program did an illegal 4-byte read of
311 address 0xBFFFF74C, which, as far as Memcheck can tell, is not a valid
312 stack address, nor corresponds to any current heap blocks or recently freed
313 heap blocks. The read is happening at line 45 of
314 <filename>bogon.cpp</filename>, called from line 66 of the same file,
315 etc. For errors associated with an identified (current or freed) heap block,
316 for example reading freed memory, Valgrind reports not only the
317 location where the error happened, but also where the associated heap block
318 was allocated/freed.</para>
320 <para>Valgrind remembers all error reports. When an error is detected,
321 it is compared against old reports, to see if it is a duplicate. If so,
322 the error is noted, but no further commentary is emitted. This avoids
323 you being swamped with bazillions of duplicate error reports.</para>
325 <para>If you want to know how many times each error occurred, run with
326 the <option>-v</option> option. When execution finishes, all the
327 reports are printed out, along with, and sorted by, their occurrence
328 counts. This makes it easy to see which errors have occurred most
331 <para>Errors are reported before the associated operation actually
332 happens. For example, if you're using Memcheck and your program attempts to
333 read from address zero, Memcheck will emit a message to this effect, and
334 your program will then likely die with a segmentation fault.</para>
336 <para>In general, you should try and fix errors in the order that they
337 are reported. Not doing so can be confusing. For example, a program
338 which copies uninitialised values to several memory locations, and later
339 uses them, will generate several error messages, when run on Memcheck.
340 The first such error message may well give the most direct clue to the
341 root cause of the problem.</para>
343 <para>The process of detecting duplicate errors is quite an
344 expensive one and can become a significant performance overhead
345 if your program generates huge quantities of errors. To avoid
346 serious problems, Valgrind will simply stop collecting
347 errors after 1,000 different errors have been seen, or 10,000,000 errors
348 in total have been seen. In this situation you might as well
349 stop your program and fix it, because Valgrind won't tell you
350 anything else useful after this. Note that the 1,000/10,000,000 limits
351 apply after suppressed errors are removed. These limits are
352 defined in <filename>m_errormgr.c</filename> and can be increased
355 <para>To avoid this cutoff you can use the
356 <option>--error-limit=no</option> option. Then Valgrind will always show
357 errors, regardless of how many there are. Use this option carefully,
358 since it may have a bad effect on performance.</para>
363 <sect1 id="manual-core.suppress" xreflabel="Suppressing errors">
364 <title>Suppressing errors</title>
366 <para>The error-checking tools detect numerous problems in the system
367 libraries, such as the C library,
368 which come pre-installed with your OS. You can't easily fix
369 these, but you don't want to see these errors (and yes, there are many!)
370 So Valgrind reads a list of errors to suppress at startup. A default
371 suppression file is created by the
372 <computeroutput>./configure</computeroutput> script when the system is
375 <para>You can modify and add to the suppressions file at your leisure,
376 or, better, write your own. Multiple suppression files are allowed.
377 This is useful if part of your project contains errors you can't or
378 don't want to fix, yet you don't want to continuously be reminded of
381 <formalpara><title>Note:</title> <para>By far the easiest way to add
382 suppressions is to use the <option>--gen-suppressions=yes</option> option
383 described in <xref linkend="manual-core.options"/>. This generates
384 suppressions automatically. For best results,
385 though, you may want to edit the output
386 of <option>--gen-suppressions=yes</option> by hand, in which
387 case it would be advisable to read through this section.
391 <para>Each error to be suppressed is described very specifically, to
392 minimise the possibility that a suppression-directive inadvertently
393 suppresses a bunch of similar errors which you did want to see. The
394 suppression mechanism is designed to allow precise yet flexible
395 specification of errors to suppress.</para>
397 <para>If you use the <option>-v</option> option, at the end of execution,
398 Valgrind prints out one line for each used suppression, giving the number of times
399 it got used, its name and the filename and line number where the suppression is
400 defined. Depending on the suppression kind, the filename and line number are optionally
401 followed by additional information (such as the number of blocks and bytes suppressed
402 by a Memcheck leak suppression). Here's the suppressions used by a
403 run of <computeroutput>valgrind -v --tool=memcheck ls -l</computeroutput>:</para>
405 <programlisting><![CDATA[
406 --1610-- used_suppression: 2 dl-hack3-cond-1 /usr/lib/valgrind/default.supp:1234
407 --1610-- used_suppression: 2 glibc-2.5.x-on-SUSE-10.2-(PPC)-2a /usr/lib/valgrind/default.supp:1234
410 <para>Multiple suppressions files are allowed. Valgrind loads suppression
411 patterns from <filename>$PREFIX/lib/valgrind/default.supp</filename> unless
412 <option>--default-suppressions=no</option> has been specified. You can
413 ask to add suppressions from additional files by specifying
414 <option>--suppressions=/path/to/file.supp</option> one or more times.
417 <para>If you want to understand more about suppressions, look at an
418 existing suppressions file whilst reading the following documentation.
419 The file <filename>glibc-2.3.supp</filename>, in the source
420 distribution, provides some good examples.</para>
422 <para>Each suppression has the following components:</para>
427 <para>First line: its name. This merely gives a handy name to the
428 suppression, by which it is referred to in the summary of used
429 suppressions printed out when a program finishes. It's not
430 important what the name is; any identifying string will do.</para>
434 <para>Second line: name of the tool(s) that the suppression is for
435 (if more than one, comma-separated), and the name of the suppression
436 itself, separated by a colon (n.b.: no spaces are allowed), eg:</para>
437 <programlisting><![CDATA[
438 tool_name1,tool_name2:suppression_name]]></programlisting>
440 <para>Recall that Valgrind is a modular system, in which
441 different instrumentation tools can observe your program whilst it
442 is running. Since different tools detect different kinds of errors,
443 it is necessary to say which tool(s) the suppression is meaningful
446 <para>Tools will complain, at startup, if a tool does not understand
447 any suppression directed to it. Tools ignore suppressions which are
448 not directed to them. As a result, it is quite practical to put
449 suppressions for all tools into the same suppression file.</para>
453 <para>Next line: a small number of suppression types have extra
454 information after the second line (eg. the <varname>Param</varname>
455 suppression for Memcheck)</para>
459 <para>Remaining lines: This is the calling context for the error --
460 the chain of function calls that led to it. There can be up to 24
461 of these lines.</para>
463 <para>Locations may be names of either shared objects, functions,
464 or source lines. They begin with
465 <computeroutput>obj:</computeroutput>,
466 <computeroutput>fun:</computeroutput>, or
467 <computeroutput>src:</computeroutput> respectively. Function,
468 object, and file names to match against may use the wildcard characters
469 <computeroutput>*</computeroutput> and
470 <computeroutput>?</computeroutput>. Source lines are specified
471 using the form <filename>filename[:lineNumber]</filename>.</para>
473 <para><command>Important note: </command> C++ function names must be
474 <command>mangled</command>. If you are writing suppressions by
475 hand, use the <option>--demangle=no</option> option to get the
476 mangled names in your error messages. An example of a mangled
477 C++ name is <computeroutput>_ZN9QListView4showEv</computeroutput>.
478 This is the form that the GNU C++ compiler uses internally, and
479 the form that must be used in suppression files. The equivalent
480 demangled name, <computeroutput>QListView::show()</computeroutput>,
481 is what you see at the C++ source code level.
484 <para>A location line may also be
485 simply "<computeroutput>...</computeroutput>" (three dots). This is
486 a frame-level wildcard, which matches zero or more frames. Frame
487 level wildcards are useful because they make it easy to ignore
488 varying numbers of uninteresting frames in between frames of
489 interest. That is often important when writing suppressions which
490 are intended to be robust against variations in the amount of
491 function inlining done by compilers.</para>
495 <para>Finally, the entire suppression must be between curly
496 braces. Each brace must be the first character on its own
502 <para>A suppression only suppresses an error when the error matches all
503 the details in the suppression. Here's an example:</para>
505 <programlisting><![CDATA[
507 __gconv_transform_ascii_internal/__mbrtowc/mbtowc
509 fun:__gconv_transform_ascii_internal
512 }]]></programlisting>
515 <para>What it means is: for Memcheck only, suppress a
516 use-of-uninitialised-value error, when the data size is 4, when it
517 occurs in the function
518 <computeroutput>__gconv_transform_ascii_internal</computeroutput>, when
519 that is called from any function of name matching
520 <computeroutput>__mbr*toc</computeroutput>, when that is called from
521 <computeroutput>mbtowc</computeroutput>. It doesn't apply under any
522 other circumstances. The string by which this suppression is identified
524 <computeroutput>__gconv_transform_ascii_internal/__mbrtowc/mbtowc</computeroutput>.</para>
526 <para>(See <xref linkend="mc-manual.suppfiles"/> for more details
527 on the specifics of Memcheck's suppression kinds.)</para>
529 <para>Another example, again for the Memcheck tool:</para>
531 <programlisting><![CDATA[
533 libX11.so.6.2/libX11.so.6.2/libXaw.so.7.0
535 obj:/usr/X11R6/lib/libX11.so.6.2
536 obj:/usr/X11R6/lib/libX11.so.6.2
537 obj:/usr/X11R6/lib/libXaw.so.7.0
538 }]]></programlisting>
540 <para>This suppresses any size 4 uninitialised-value error which occurs
541 anywhere in <filename>libX11.so.6.2</filename>, when called from
542 anywhere in the same library, when called from anywhere in
543 <filename>libXaw.so.7.0</filename>. The inexact specification of
544 locations is regrettable, but is about all you can hope for, given that
545 the X11 libraries shipped on the Linux distro on which this example
546 was made have had their symbol tables removed.</para>
548 <para>An example of the src: specification, again for the Memcheck tool:</para>
550 <programlisting><![CDATA[
552 libX11.so.6.2/libX11.so.6.2/libXaw.so.7.0
555 }]]></programlisting>
557 <para>This suppresses any size-4 uninitialised-value error which occurs
558 at line 321 in <filename>valid.c</filename>.</para>
560 <para>Although the above two examples do not make this clear, you can
561 freely mix <computeroutput>obj:</computeroutput>,
562 <computeroutput>fun:</computeroutput>, and
563 <computeroutput>src:</computeroutput>
564 lines in a suppression.</para>
566 <para>Finally, here's an example using three frame-level wildcards:</para>
568 <programlisting><![CDATA[
581 This suppresses Memcheck memory-leak errors, in the case where
582 the allocation was done by <computeroutput>main</computeroutput>
583 calling (though any number of intermediaries, including zero)
584 <computeroutput>ccc</computeroutput>,
586 <computeroutput>ddd</computeroutput> and eventually
587 to <computeroutput>malloc.</computeroutput>.
591 <sect1 id="manual-core.options"
592 xreflabel="Core Command-line Options">
593 <title>Core Command-line Options</title>
595 <para>As mentioned above, Valgrind's core accepts a common set of options.
596 The tools also accept tool-specific options, which are documented
597 separately for each tool.</para>
599 <para>Valgrind's default settings succeed in giving reasonable behaviour
600 in most cases. We group the available options by rough categories.</para>
602 <sect2 id="manual-core.toolopts" xreflabel="Tool-selection Option">
603 <title>Tool-selection Option</title>
605 <para id="tool.opts.para">The single most important option.</para>
607 <variablelist id="tool.opts.list">
609 <varlistentry id="tool_name" xreflabel="--tool">
611 <option><![CDATA[--tool=<toolname> [default: memcheck] ]]></option>
614 <para>Run the Valgrind tool called <varname>toolname</varname>,
615 e.g. memcheck, cachegrind, callgrind, helgrind, drd, massif,
616 dhat, lackey, none, exp-sgcheck, exp-bbv, etc.</para>
626 <sect2 id="manual-core.basicopts" xreflabel="Basic Options">
627 <title>Basic Options</title>
629 <!-- start of xi:include in the manpage -->
630 <para id="basic.opts.para">These options work with all tools.</para>
632 <variablelist id="basic.opts.list">
634 <varlistentry id="opt.help" xreflabel="--help">
635 <term><option>-h --help</option></term>
637 <para>Show help for all options, both for the core and for the
638 selected tool. If the option is repeated it is equivalent to giving
639 <option>--help-debug</option>.</para>
643 <varlistentry id="opt.help-debug" xreflabel="--help-debug">
644 <term><option>--help-debug</option></term>
646 <para>Same as <option>--help</option>, but also lists debugging
647 options which usually are only of use to Valgrind's
652 <varlistentry id="opt.version" xreflabel="--version">
653 <term><option>--version</option></term>
655 <para>Show the version number of the Valgrind core. Tools can have
656 their own version numbers. There is a scheme in place to ensure
657 that tools only execute when the core version is one they are
658 known to work with. This was done to minimise the chances of
659 strange problems arising from tool-vs-core version
660 incompatibilities.</para>
664 <varlistentry id="opt.quiet" xreflabel="--quiet">
665 <term><option>-q</option>, <option>--quiet</option></term>
667 <para>Run silently, and only print error messages. Useful if you
668 are running regression tests or have some other automated test
673 <varlistentry id="opt.verbose" xreflabel="--verbose">
674 <term><option>-v</option>, <option>--verbose</option></term>
676 <para>Be more verbose. Gives extra information on various aspects
677 of your program, such as: the shared objects loaded, the
678 suppressions used, the progress of the instrumentation and
679 execution engines, and warnings about unusual behaviour. Repeating
680 the option increases the verbosity level.</para>
684 <varlistentry id="opt.trace-children" xreflabel="--trace-children">
686 <option><![CDATA[--trace-children=<yes|no> [default: no] ]]></option>
689 <para>When enabled, Valgrind will trace into sub-processes
690 initiated via the <varname>exec</varname> system call. This is
691 necessary for multi-process programs.
693 <para>Note that Valgrind does trace into the child of a
694 <varname>fork</varname> (it would be difficult not to, since
695 <varname>fork</varname> makes an identical copy of a process), so this
696 option is arguably badly named. However, most children of
697 <varname>fork</varname> calls immediately call <varname>exec</varname>
703 <varlistentry id="opt.trace-children-skip" xreflabel="--trace-children-skip">
705 <option><![CDATA[--trace-children-skip=patt1,patt2,... ]]></option>
708 <para>This option only has an effect when
709 <option>--trace-children=yes</option> is specified. It allows
710 for some children to be skipped. The option takes a comma
711 separated list of patterns for the names of child executables
712 that Valgrind should not trace into. Patterns may include the
713 metacharacters <computeroutput>?</computeroutput>
714 and <computeroutput>*</computeroutput>, which have the usual
717 This can be useful for pruning uninteresting branches from a
718 tree of processes being run on Valgrind. But you should be
719 careful when using it. When Valgrind skips tracing into an
720 executable, it doesn't just skip tracing that executable, it
721 also skips tracing any of that executable's child processes.
722 In other words, the flag doesn't merely cause tracing to stop
723 at the specified executables -- it skips tracing of entire
724 process subtrees rooted at any of the specified
729 <varlistentry id="opt.trace-children-skip-by-arg"
730 xreflabel="--trace-children-skip-by-arg">
732 <option><![CDATA[--trace-children-skip-by-arg=patt1,patt2,... ]]></option>
735 <para>This is the same as
736 <option>--trace-children-skip</option>, with one difference:
737 the decision as to whether to trace into a child process is
738 made by examining the arguments to the child process, rather
739 than the name of its executable.</para>
743 <varlistentry id="opt.child-silent-after-fork"
744 xreflabel="--child-silent-after-fork">
746 <option><![CDATA[--child-silent-after-fork=<yes|no> [default: no] ]]></option>
749 <para>When enabled, Valgrind will not show any debugging or
750 logging output for the child process resulting from
751 a <varname>fork</varname> call. This can make the output less
752 confusing (although more misleading) when dealing with processes
753 that create children. It is particularly useful in conjunction
754 with <varname>--trace-children=</varname>. Use of this option is also
755 strongly recommended if you are requesting XML output
756 (<varname>--xml=yes</varname>), since otherwise the XML from child and
757 parent may become mixed up, which usually makes it useless.
762 <varlistentry id="opt.vgdb" xreflabel="--vgdb">
764 <option><![CDATA[--vgdb=<no|yes|full> [default: yes] ]]></option>
768 <para>Valgrind will provide "gdbserver" functionality when
769 <option>--vgdb=yes</option> or <option>--vgdb=full</option> is
770 specified. This allows an external GNU GDB debugger to control
771 and debug your program when it runs on Valgrind.
772 <option>--vgdb=full</option> incurs significant performance
773 overheads, but provides more precise breakpoints and
774 watchpoints. See <xref linkend="manual-core-adv.gdbserver"/> for
775 a detailed description.
778 <para> If the embedded gdbserver is enabled but no gdb is
779 currently being used, the <xref linkend="manual-core-adv.vgdb"/>
780 command line utility can send "monitor commands" to Valgrind
781 from a shell. The Valgrind core provides a set of
782 <xref linkend="manual-core-adv.valgrind-monitor-commands"/>. A tool
783 can optionally provide tool specific monitor commands, which are
784 documented in the tool specific chapter.
790 <varlistentry id="opt.vgdb-error" xreflabel="--vgdb-error">
792 <option><![CDATA[--vgdb-error=<number> [default: 999999999] ]]></option>
795 <para> Use this option when the Valgrind gdbserver is enabled with
796 <option>--vgdb=yes</option> or <option>--vgdb=full</option>.
797 Tools that report errors will wait
798 for "<computeroutput>number</computeroutput>" errors to be
799 reported before freezing the program and waiting for you to
800 connect with GDB. It follows that a value of zero will cause
801 the gdbserver to be started before your program is executed.
802 This is typically used to insert GDB breakpoints before
803 execution, and also works with tools that do not report
804 errors, such as Massif.
809 <varlistentry id="opt.vgdb-stop-at" xreflabel="--vgdb-stop-at">
811 <option><![CDATA[--vgdb-stop-at=<set> [default: none] ]]></option>
814 <para> Use this option when the Valgrind gdbserver is enabled with
815 <option>--vgdb=yes</option> or <option>--vgdb=full</option>.
816 The Valgrind gdbserver will be invoked for each error after
817 <option>--vgdb-error</option> have been reported.
818 You can additionally ask the Valgrind gdbserver to be invoked
819 for other events, specified in one of the following ways: </para>
821 <listitem><para>a comma separated list of one or more of
822 <option>startup exit valgrindabexit</option>.</para>
824 <para>The values <option>startup</option> <option>exit</option>
825 <option>valgrindabexit</option> respectively indicate to
826 invoke gdbserver before your program is executed, after the
827 last instruction of your program, on Valgrind abnormal exit
828 (e.g. internal error, out of memory, ...).</para>
830 <para>Note: <option>startup</option> and
831 <option>--vgdb-error=0</option> will both cause Valgrind
832 gdbserver to be invoked before your program is executed. The
833 <option>--vgdb-error=0</option> will in addition cause your
834 program to stop on all subsequent errors.</para>
838 <listitem><para><option>all</option> to specify the complete set.
840 <option>--vgdb-stop-at=startup,exit,valgrindabexit</option>.</para>
843 <listitem><para><option>none</option> for the empty set.</para>
849 <varlistentry id="opt.track-fds" xreflabel="--track-fds">
851 <option><![CDATA[--track-fds=<yes|no> [default: no] ]]></option>
854 <para>When enabled, Valgrind will print out a list of open file
855 descriptors on exit or on request, via the gdbserver monitor
856 command <varname>v.info open_fds</varname>. Along with each
857 file descriptor is printed a stack backtrace of where the file
858 was opened and any details relating to the file descriptor such
859 as the file name or socket details.</para>
863 <varlistentry id="opt.time-stamp" xreflabel="--time-stamp">
865 <option><![CDATA[--time-stamp=<yes|no> [default: no] ]]></option>
868 <para>When enabled, each message is preceded with an indication of
869 the elapsed wallclock time since startup, expressed as days,
870 hours, minutes, seconds and milliseconds.</para>
874 <varlistentry id="opt.log-fd" xreflabel="--log-fd">
876 <option><![CDATA[--log-fd=<number> [default: 2, stderr] ]]></option>
879 <para>Specifies that Valgrind should send all of its messages to
880 the specified file descriptor. The default, 2, is the standard
881 error channel (stderr). Note that this may interfere with the
882 client's own use of stderr, as Valgrind's output will be
883 interleaved with any output that the client sends to
888 <varlistentry id="opt.log-file" xreflabel="--log-file">
890 <option><![CDATA[--log-file=<filename> ]]></option>
893 <para>Specifies that Valgrind should send all of its messages to
894 the specified file. If the file name is empty, it causes an abort.
895 There are three special format specifiers that can be used in the file
898 <para><option>%p</option> is replaced with the current process ID.
899 This is very useful for program that invoke multiple processes.
900 WARNING: If you use <option>--trace-children=yes</option> and your
901 program invokes multiple processes OR your program forks without
902 calling exec afterwards, and you don't use this specifier
903 (or the <option>%q</option> specifier below), the Valgrind output from
904 all those processes will go into one file, possibly jumbled up, and
905 possibly incomplete. Note: If the program forks and calls exec afterwards,
906 Valgrind output of the child from the period between fork and exec
907 will be lost. Fortunately this gap is really tiny for most programs;
908 and modern programs use <computeroutput>posix_spawn</computeroutput>
911 <para><option>%n</option> is replaced with a file sequence number
912 unique for this process.
913 This is useful for processes that produces several files
914 from the same filename template.</para>
917 <para><option>%q{FOO}</option> is replaced with the contents of the
918 environment variable <varname>FOO</varname>. If the
919 <option>{FOO}</option> part is malformed, it causes an abort. This
920 specifier is rarely needed, but very useful in certain circumstances
921 (eg. when running MPI programs). The idea is that you specify a
922 variable which will be set differently for each process in the job,
923 for example <computeroutput>BPROC_RANK</computeroutput> or whatever is
924 applicable in your MPI setup. If the named environment variable is not
925 set, it causes an abort. Note that in some shells, the
926 <option>{</option> and <option>}</option> characters may need to be
927 escaped with a backslash.</para>
929 <para><option>%%</option> is replaced with <option>%</option>.</para>
931 <para>If an <option>%</option> is followed by any other character, it
932 causes an abort.</para>
934 <para>If the file name specifies a relative file name, it is put
935 in the program's initial working directory: this is the current
936 directory when the program started its execution after the fork
937 or after the exec. If it specifies an absolute file name (ie.
938 starts with '/') then it is put there.
943 <varlistentry id="opt.log-socket" xreflabel="--log-socket">
945 <option><![CDATA[--log-socket=<ip-address:port-number> ]]></option>
948 <para>Specifies that Valgrind should send all of its messages to
949 the specified port at the specified IP address. The port may be
950 omitted, in which case port 1500 is used. If a connection cannot
951 be made to the specified socket, Valgrind falls back to writing
952 output to the standard error (stderr). This option is intended to
953 be used in conjunction with the
954 <computeroutput>valgrind-listener</computeroutput> program. For
956 <link linkend="&vg-comment-id;">the commentary</link>
957 in the manual.</para>
962 <!-- end of xi:include in the manpage -->
967 <sect2 id="manual-core.erropts" xreflabel="Error-related Options">
968 <title>Error-related Options</title>
970 <!-- start of xi:include in the manpage -->
971 <para id="error-related.opts.para">These options are used by all tools
972 that can report errors, e.g. Memcheck, but not Cachegrind.</para>
974 <variablelist id="error-related.opts.list">
976 <varlistentry id="opt.xml" xreflabel="--xml">
978 <option><![CDATA[--xml=<yes|no> [default: no] ]]></option>
981 <para>When enabled, the important parts of the output (e.g. tool error
982 messages) will be in XML format rather than plain text. Furthermore,
983 the XML output will be sent to a different output channel than the
984 plain text output. Therefore, you also must use one of
985 <option>--xml-fd</option>, <option>--xml-file</option> or
986 <option>--xml-socket</option> to specify where the XML is to be sent.
989 <para>Less important messages will still be printed in plain text, but
990 because the XML output and plain text output are sent to different
991 output channels (the destination of the plain text output is still
992 controlled by <option>--log-fd</option>, <option>--log-file</option>
993 and <option>--log-socket</option>) this should not cause problems.
996 <para>This option is aimed at making life easier for tools that consume
997 Valgrind's output as input, such as GUI front ends. Currently this
998 option works with Memcheck, Helgrind, DRD and SGcheck. The output
999 format is specified in the file
1000 <computeroutput>docs/internals/xml-output-protocol4.txt</computeroutput>
1001 in the source tree for Valgrind 3.5.0 or later.</para>
1003 <para>The recommended options for a GUI to pass, when requesting
1004 XML output, are: <option>--xml=yes</option> to enable XML output,
1005 <option>--xml-file</option> to send the XML output to a (presumably
1006 GUI-selected) file, <option>--log-file</option> to send the plain
1007 text output to a second GUI-selected file,
1008 <option>--child-silent-after-fork=yes</option>, and
1009 <option>-q</option> to restrict the plain text output to critical
1010 error messages created by Valgrind itself. For example, failure to
1011 read a specified suppressions file counts as a critical error message.
1012 In this way, for a successful run the text output file will be empty.
1013 But if it isn't empty, then it will contain important information
1014 which the GUI user should be made aware
1019 <varlistentry id="opt.xml-fd" xreflabel="--xml-fd">
1021 <option><![CDATA[--xml-fd=<number> [default: -1, disabled] ]]></option>
1024 <para>Specifies that Valgrind should send its XML output to the
1025 specified file descriptor. It must be used in conjunction with
1026 <option>--xml=yes</option>.</para>
1030 <varlistentry id="opt.xml-file" xreflabel="--xml-file">
1032 <option><![CDATA[--xml-file=<filename> ]]></option>
1035 <para>Specifies that Valgrind should send its XML output
1036 to the specified file. It must be used in conjunction with
1037 <option>--xml=yes</option>. Any <option>%p</option> or
1038 <option>%q</option> sequences appearing in the filename are expanded
1039 in exactly the same way as they are for <option>--log-file</option>.
1040 See the description of <xref linkend="opt.log-file"/> for details.
1045 <varlistentry id="opt.xml-socket" xreflabel="--xml-socket">
1047 <option><![CDATA[--xml-socket=<ip-address:port-number> ]]></option>
1050 <para>Specifies that Valgrind should send its XML output the
1051 specified port at the specified IP address. It must be used in
1052 conjunction with <option>--xml=yes</option>. The form of the argument
1053 is the same as that used by <option>--log-socket</option>.
1054 See the description of <option>--log-socket</option>
1055 for further details.</para>
1059 <varlistentry id="opt.xml-user-comment" xreflabel="--xml-user-comment">
1061 <option><![CDATA[--xml-user-comment=<string> ]]></option>
1064 <para>Embeds an extra user comment string at the start of the XML
1065 output. Only works when <option>--xml=yes</option> is specified;
1066 ignored otherwise.</para>
1070 <varlistentry id="opt.demangle" xreflabel="--demangle">
1072 <option><![CDATA[--demangle=<yes|no> [default: yes] ]]></option>
1075 <para>Enable/disable automatic demangling (decoding) of C++ names.
1076 Enabled by default. When enabled, Valgrind will attempt to
1077 translate encoded C++ names back to something approaching the
1078 original. The demangler handles symbols mangled by g++ versions
1079 2.X, 3.X and 4.X.</para>
1081 <para>An important fact about demangling is that function names
1082 mentioned in suppressions files should be in their mangled form.
1083 Valgrind does not demangle function names when searching for
1084 applicable suppressions, because to do otherwise would make
1085 suppression file contents dependent on the state of Valgrind's
1086 demangling machinery, and also slow down suppression matching.</para>
1090 <varlistentry id="opt.num-callers" xreflabel="--num-callers">
1092 <option><![CDATA[--num-callers=<number> [default: 12] ]]></option>
1095 <para>Specifies the maximum number of entries shown in stack traces
1096 that identify program locations. Note that errors are commoned up
1097 using only the top four function locations (the place in the current
1098 function, and that of its three immediate callers). So this doesn't
1099 affect the total number of errors reported.</para>
1101 <para>The maximum value for this is 500. Note that higher settings
1102 will make Valgrind run a bit more slowly and take a bit more
1103 memory, but can be useful when working with programs with
1104 deeply-nested call chains.</para>
1108 <varlistentry id="opt.unw-stack-scan-thresh"
1109 xreflabel="--unw-stack-scan-thresh">
1111 <option><![CDATA[--unw-stack-scan-thresh=<number> [default: 0] ]]></option>
1114 <option><![CDATA[--unw-stack-scan-frames=<number> [default: 5] ]]></option>
1117 <para>Stack-scanning support is available only on ARM
1120 <para>These flags enable and control stack unwinding by stack
1121 scanning. When the normal stack unwinding mechanisms -- usage
1122 of Dwarf CFI records, and frame-pointer following -- fail, stack
1123 scanning may be able to recover a stack trace.</para>
1125 <para>Note that stack scanning is an imprecise, heuristic
1126 mechanism that may give very misleading results, or none at all.
1127 It should be used only in emergencies, when normal unwinding
1128 fails, and it is important to nevertheless have stack
1131 <para>Stack scanning is a simple technique: the unwinder reads
1132 words from the stack, and tries to guess which of them might be
1133 return addresses, by checking to see if they point just after
1134 ARM or Thumb call instructions. If so, the word is added to the
1137 <para>The main danger occurs when a function call returns,
1138 leaving its return address exposed, and a new function is
1139 called, but the new function does not overwrite the old address.
1140 The result of this is that the backtrace may contain entries for
1141 functions which have already returned, and so be very
1144 <para>A second limitation of this implementation is that it will
1145 scan only the page (4KB, normally) containing the starting stack
1146 pointer. If the stack frames are large, this may result in only
1147 a few (or not even any) being present in the trace. Also, if
1148 you are unlucky and have an initial stack pointer near the end
1149 of its containing page, the scan may miss all interesting
1152 <para>By default stack scanning is disabled. The normal use
1153 case is to ask for it when a stack trace would otherwise be very
1154 short. So, to enable it,
1155 use <computeroutput>--unw-stack-scan-thresh=number</computeroutput>.
1156 This requests Valgrind to try using stack scanning to "extend"
1157 stack traces which contain fewer
1158 than <computeroutput>number</computeroutput> frames.</para>
1160 <para>If stack scanning does take place, it will only generate
1161 at most the number of frames specified
1162 by <computeroutput>--unw-stack-scan-frames</computeroutput>.
1163 Typically, stack scanning generates so many garbage entries that
1164 this value is set to a low value (5) by default. In no case
1165 will a stack trace larger than the value specified
1166 by <computeroutput>--num-callers</computeroutput> be
1171 <varlistentry id="opt.error-limit" xreflabel="--error-limit">
1173 <option><![CDATA[--error-limit=<yes|no> [default: yes] ]]></option>
1176 <para>When enabled, Valgrind stops reporting errors after 10,000,000
1177 in total, or 1,000 different ones, have been seen. This is to
1178 stop the error tracking machinery from becoming a huge performance
1179 overhead in programs with many errors.</para>
1183 <varlistentry id="opt.error-exitcode" xreflabel="--error-exitcode">
1185 <option><![CDATA[--error-exitcode=<number> [default: 0] ]]></option>
1188 <para>Specifies an alternative exit code to return if Valgrind
1189 reported any errors in the run. When set to the default value
1190 (zero), the return value from Valgrind will always be the return
1191 value of the process being simulated. When set to a nonzero value,
1192 that value is returned instead, if Valgrind detects any errors.
1193 This is useful for using Valgrind as part of an automated test
1194 suite, since it makes it easy to detect test cases for which
1195 Valgrind has reported errors, just by inspecting return codes.</para>
1199 <varlistentry id="opt.exit-on-first-error" xreflabel="--exit-on-first-error">
1201 <option><![CDATA[--exit-on-first-error=<yes|no> [default: no] ]]></option>
1204 <para>If this option is enabled, Valgrind exits on the first error.
1205 A nonzero exit value must be defined using
1206 <computeroutput>--error-exitcode</computeroutput> option.
1207 Useful if you are running regression tests or have some other
1208 automated test machinery.</para>
1212 <varlistentry id="opt.error-markers" xreflabel="--error-markers">
1214 <option><![CDATA[--error-markers=<begin>,<end> [default: none]]]></option>
1217 <para>When errors are output as plain text (i.e. XML not used),
1218 <option>--error-markers</option> instructs to output a line
1219 containing the <option>begin</option> (<option>end</option>)
1220 string before (after) each error. </para>
1221 <para> Such marker lines facilitate searching for errors and/or
1222 extracting errors in an output file that contain valgrind errors mixed
1223 with the program output. </para>
1224 <para> Note that empty markers are accepted. So, only using a begin
1225 (or an end) marker is possible.</para>
1229 <varlistentry id="opt.show-error-list" xreflabel="--show-error-list">
1231 <option><![CDATA[--show-error-list=no|yes [default: no]]]></option>
1234 <para>If this option is enabled, for tools that report errors, valgrind
1235 will show the list of detected errors and the list of used suppressions
1238 <para>Note that at verbosity 2 and above, valgrind automatically shows
1239 the list of detected errors and the list of used suppressions
1240 at exit, unless <option>--show-error-list=no</option> is selected.
1245 <varlistentry id="opt.s" xreflabel="-s">
1247 <option><![CDATA[-s]]></option>
1250 <para>Specifying <option>-s</option> is equivalent to
1251 <option>--show-error-list=yes</option>.
1257 <varlistentry id="opt.sigill-diagnostics" xreflabel="--sigill-diagnostics">
1259 <option><![CDATA[--sigill-diagnostics=<yes|no> [default: yes] ]]></option>
1262 <para>Enable/disable printing of illegal instruction diagnostics.
1263 Enabled by default, but defaults to disabled when
1264 <option>--quiet</option> is given. The default can always be explicitly
1265 overridden by giving this option.</para>
1267 <para>When enabled, a warning message will be printed, along with some
1268 diagnostics, whenever an instruction is encountered that Valgrind
1269 cannot decode or translate, before the program is given a SIGILL signal.
1270 Often an illegal instruction indicates a bug in the program or missing
1271 support for the particular instruction in Valgrind. But some programs
1272 do deliberately try to execute an instruction that might be missing
1273 and trap the SIGILL signal to detect processor features. Using
1274 this flag makes it possible to avoid the diagnostic output
1275 that you would otherwise get in such cases.</para>
1279 <varlistentry id="opt.keep-debuginfo" xreflabel="--keep-debuginfo">
1281 <option><![CDATA[--keep-debuginfo=<yes|no> [default: no] ]]></option>
1284 <para>When enabled, keep ("archive") symbols and all other debuginfo
1285 for unloaded code. This allows saved stack traces to include file/line
1286 info for code that has been dlclose'd (or similar). Be careful with
1287 this, since it can lead to unbounded memory use for programs which
1288 repeatedly load and unload shared objects.</para>
1289 <para>Some tools and some functionalities have only limited support
1290 for archived debug info. Memcheck fully supports it. Generally,
1291 tools that report errors can use archived debug info to show the error
1292 stack traces. The known limitations are: Helgrind's past access stack
1293 trace of a race condition is does not use archived debug info. Massif
1294 (and more generally the xtree Massif output format) does not make use
1295 of archived debug info. Only Memcheck has been (somewhat) tested
1296 with <option>--keep-debuginfo=yes</option>, so other tools may have
1297 unknown limitations. </para>
1301 <varlistentry id="opt.show-below-main" xreflabel="--show-below-main">
1303 <option><![CDATA[--show-below-main=<yes|no> [default: no] ]]></option>
1306 <para>By default, stack traces for errors do not show any
1307 functions that appear beneath <function>main</function> because
1308 most of the time it's uninteresting C library stuff and/or
1309 gobbledygook. Alternatively, if <function>main</function> is not
1310 present in the stack trace, stack traces will not show any functions
1311 below <function>main</function>-like functions such as glibc's
1312 <function>__libc_start_main</function>. Furthermore, if
1313 <function>main</function>-like functions are present in the trace,
1314 they are normalised as <function>(below main)</function>, in order to
1315 make the output more deterministic.</para>
1317 <para>If this option is enabled, all stack trace entries will be
1318 shown and <function>main</function>-like functions will not be
1323 <varlistentry id="opt.fullpath-after" xreflabel="--fullpath-after">
1325 <option><![CDATA[--fullpath-after=<string>
1326 [default: don't show source paths] ]]></option>
1329 <para>By default Valgrind only shows the filenames in stack
1330 traces, but not full paths to source files. When using Valgrind
1331 in large projects where the sources reside in multiple different
1332 directories, this can be inconvenient.
1333 <option>--fullpath-after</option> provides a flexible solution
1334 to this problem. When this option is present, the path to each
1335 source file is shown, with the following all-important caveat:
1336 if <option>string</option> is found in the path, then the path
1337 up to and including <option>string</option> is omitted, else the
1338 path is shown unmodified. Note that <option>string</option> is
1339 not required to be a prefix of the path.</para>
1341 <para>For example, consider a file named
1342 <computeroutput>/home/janedoe/blah/src/foo/bar/xyzzy.c</computeroutput>.
1343 Specifying <option>--fullpath-after=/home/janedoe/blah/src/</option>
1344 will cause Valgrind to show the name
1345 as <computeroutput>foo/bar/xyzzy.c</computeroutput>.</para>
1347 <para>Because the string is not required to be a prefix,
1348 <option>--fullpath-after=src/</option> will produce the same
1349 output. This is useful when the path contains arbitrary
1350 machine-generated characters. For example, the
1352 <computeroutput>/my/build/dir/C32A1B47/blah/src/foo/xyzzy</computeroutput>
1353 can be pruned to <computeroutput>foo/xyzzy</computeroutput>
1355 <option>--fullpath-after=/blah/src/</option>.</para>
1357 <para>If you simply want to see the full path, just specify an
1358 empty string: <option>--fullpath-after=</option>. This isn't a
1359 special case, merely a logical consequence of the above rules.</para>
1361 <para>Finally, you can use <option>--fullpath-after</option>
1362 multiple times. Any appearance of it causes Valgrind to switch
1363 to producing full paths and applying the above filtering rule.
1364 Each produced path is compared against all
1365 the <option>--fullpath-after</option>-specified strings, in the
1366 order specified. The first string to match causes the path to
1367 be truncated as described above. If none match, the full path
1368 is shown. This facilitates chopping off prefixes when the
1369 sources are drawn from a number of unrelated directories.
1374 <varlistentry id="opt.extra-debuginfo-path" xreflabel="--extra-debuginfo-path">
1376 <option><![CDATA[--extra-debuginfo-path=<path> [default: undefined and unused] ]]></option>
1379 <para>By default Valgrind searches in several well-known paths
1380 for debug objects, such
1381 as <computeroutput>/usr/lib/debug/</computeroutput>.</para>
1383 <para>However, there may be scenarios where you may wish to put
1384 debug objects at an arbitrary location, such as external storage
1385 when running Valgrind on a mobile device with limited local
1386 storage. Another example might be a situation where you do not
1387 have permission to install debug object packages on the system
1388 where you are running Valgrind.</para>
1390 <para>In these scenarios, you may provide an absolute path as an extra,
1391 final place for Valgrind to search for debug objects by specifying
1392 <option>--extra-debuginfo-path=/path/to/debug/objects</option>.
1393 The given path will be prepended to the absolute path name of
1394 the searched-for object. For example, if Valgrind is looking
1396 for <computeroutput>/w/x/y/zz.so</computeroutput>
1397 and <option>--extra-debuginfo-path=/a/b/c</option> is specified,
1398 it will look for a debug object at
1399 <computeroutput>/a/b/c/w/x/y/zz.so</computeroutput>.</para>
1401 <para>This flag should only be specified once. If it is
1402 specified multiple times, only the last instance is
1407 <varlistentry id="opt.debuginfo-server" xreflabel="--debuginfo-server">
1409 <option><![CDATA[--debuginfo-server=ipaddr:port [default: undefined and unused]]]></option>
1412 <para>This is a new, experimental, feature introduced in version
1415 <para>In some scenarios it may be convenient to read debuginfo
1416 from objects stored on a different machine. With this flag,
1417 Valgrind will query a debuginfo server running
1418 on <computeroutput>ipaddr</computeroutput> and listening on
1419 port <computeroutput>port</computeroutput>, if it cannot find
1420 the debuginfo object in the local filesystem.</para>
1422 <para>The debuginfo server must accept TCP connections on
1423 port <computeroutput>port</computeroutput>. The debuginfo
1424 server is contained in the source
1425 file <computeroutput>auxprogs/valgrind-di-server.c</computeroutput>.
1426 It will only serve from the directory it is started
1427 in. <computeroutput>port</computeroutput> defaults to 1500 in
1428 both client and server if not specified.</para>
1430 <para>If Valgrind looks for the debuginfo for
1431 <computeroutput>/w/x/y/zz.so</computeroutput> by using the
1432 debuginfo server, it will strip the pathname components and
1433 merely request <computeroutput>zz.so</computeroutput> on the
1434 server. That in turn will look only in its current working
1435 directory for a matching debuginfo object.</para>
1437 <para>The debuginfo data is transmitted in small fragments (8
1438 KB) as requested by Valgrind. Each block is compressed using
1439 LZO to reduce transmission time. The implementation has been
1440 tuned for best performance over a single-stage 802.11g (WiFi)
1441 network link.</para>
1443 <para>Note that checks for matching primary vs debug objects,
1444 using GNU debuglink CRC scheme, are performed even when using
1445 the debuginfo server. To disable such checking, you need to
1447 <computeroutput>--allow-mismatched-debuginfo=yes</computeroutput>.
1450 <para>By default the Valgrind build system will
1451 build <computeroutput>valgrind-di-server</computeroutput> for
1452 the target platform, which is almost certainly not what you
1453 want. So far we have been unable to find out how to get
1454 automake/autoconf to build it for the build platform. If
1455 you want to use it, you will have to recompile it by hand using
1456 the command shown at the top
1457 of <computeroutput>auxprogs/valgrind-di-server.c</computeroutput>.</para>
1461 <varlistentry id="opt.allow-mismatched-debuginfo"
1462 xreflabel="--allow-mismatched-debuginfo">
1464 <option><![CDATA[--allow-mismatched-debuginfo=no|yes [no] ]]></option>
1467 <para>When reading debuginfo from separate debuginfo objects,
1468 Valgrind will by default check that the main and debuginfo
1469 objects match, using the GNU debuglink mechanism. This
1470 guarantees that it does not read debuginfo from out of date
1471 debuginfo objects, and also ensures that Valgrind can't crash as
1472 a result of mismatches.</para>
1474 <para>This check can be overridden using
1475 <computeroutput>--allow-mismatched-debuginfo=yes</computeroutput>.
1476 This may be useful when the debuginfo and main objects have not
1477 been split in the proper way. Be careful when using this,
1478 though: it disables all consistency checking, and Valgrind has
1479 been observed to crash when the main and debuginfo objects don't
1484 <varlistentry id="opt.suppressions" xreflabel="--suppressions">
1486 <option><![CDATA[--suppressions=<filename> [default: $PREFIX/lib/valgrind/default.supp] ]]></option>
1489 <para>Specifies an extra file from which to read descriptions of
1490 errors to suppress. You may use up to 100 extra suppression
1495 <varlistentry id="opt.gen-suppressions" xreflabel="--gen-suppressions">
1497 <option><![CDATA[--gen-suppressions=<yes|no|all> [default: no] ]]></option>
1500 <para>When set to <varname>yes</varname>, Valgrind will pause
1501 after every error shown and print the line:
1502 <literallayout><computeroutput> ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ----</computeroutput></literallayout>
1504 Pressing <varname>Ret</varname>, or <varname>N Ret</varname> or
1505 <varname>n Ret</varname>, causes Valgrind continue execution without
1506 printing a suppression for this error.</para>
1508 <para>Pressing <varname>Y Ret</varname> or
1509 <varname>y Ret</varname> causes Valgrind to write a suppression
1510 for this error. You can then cut and paste it into a suppression file
1511 if you don't want to hear about the error in the future.</para>
1513 <para>When set to <varname>all</varname>, Valgrind will print a
1514 suppression for every reported error, without querying the
1517 <para>This option is particularly useful with C++ programs, as it
1518 prints out the suppressions with mangled names, as
1521 <para>Note that the suppressions printed are as specific as
1522 possible. You may want to common up similar ones, by adding
1523 wildcards to function names, and by using frame-level wildcards.
1524 The wildcarding facilities are powerful yet flexible, and with a
1525 bit of careful editing, you may be able to suppress a whole
1526 family of related errors with only a few suppressions.
1527 <!-- commented out because it causes broken links in the man page
1528 For details on how to do this, see
1529 <xref linkend="manual-core.suppress"/>.
1533 <para>Sometimes two different errors
1534 are suppressed by the same suppression, in which case Valgrind
1535 will output the suppression more than once, but you only need to
1536 have one copy in your suppression file (but having more than one
1537 won't cause problems). Also, the suppression name is given as
1538 <computeroutput><insert a suppression name
1539 here></computeroutput>; the name doesn't really matter, it's
1540 only used with the <option>-v</option> option which prints out all
1541 used suppression records.</para>
1545 <varlistentry id="opt.input-fd" xreflabel="--input-fd">
1547 <option><![CDATA[--input-fd=<number> [default: 0, stdin] ]]></option>
1551 <option>--gen-suppressions=yes</option>, Valgrind will stop so as
1552 to read keyboard input from you when each error occurs. By
1553 default it reads from the standard input (stdin), which is
1554 problematic for programs which close stdin. This option allows
1555 you to specify an alternative file descriptor from which to read
1560 <varlistentry id="opt.dsymutil" xreflabel="--dsymutil">
1562 <option><![CDATA[--dsymutil=no|yes [yes] ]]></option>
1565 <para>This option is only relevant when running Valgrind on
1568 <para>Mac OS X uses a deferred debug information (debuginfo)
1569 linking scheme. When object files containing debuginfo are
1570 linked into a <computeroutput>.dylib</computeroutput> or an
1571 executable, the debuginfo is not copied into the final file.
1572 Instead, the debuginfo must be linked manually by
1573 running <computeroutput>dsymutil</computeroutput>, a
1574 system-provided utility, on the executable
1575 or <computeroutput>.dylib</computeroutput>. The resulting
1576 combined debuginfo is placed in a directory alongside the
1577 executable or <computeroutput>.dylib</computeroutput>, but with
1578 the extension <computeroutput>.dSYM</computeroutput>.</para>
1580 <para>With <option>--dsymutil=no</option>, Valgrind
1581 will detect cases where the
1582 <computeroutput>.dSYM</computeroutput> directory is either
1583 missing, or is present but does not appear to match the
1584 associated executable or <computeroutput>.dylib</computeroutput>,
1585 most likely because it is out of date. In these cases, Valgrind
1586 will print a warning message but take no further action.</para>
1588 <para>With <option>--dsymutil=yes</option>, Valgrind
1589 will, in such cases, automatically
1590 run <computeroutput>dsymutil</computeroutput> as necessary to
1591 bring the debuginfo up to date. For all practical purposes, if
1592 you always use <option>--dsymutil=yes</option>, then
1593 there is never any need to
1594 run <computeroutput>dsymutil</computeroutput> manually or as part
1595 of your applications's build system, since Valgrind will run it
1596 as necessary.</para>
1598 <para>Valgrind will not attempt to
1599 run <computeroutput>dsymutil</computeroutput> on any
1600 executable or library in
1601 <computeroutput>/usr/</computeroutput>,
1602 <computeroutput>/bin/</computeroutput>,
1603 <computeroutput>/sbin/</computeroutput>,
1604 <computeroutput>/opt/</computeroutput>,
1605 <computeroutput>/sw/</computeroutput>,
1606 <computeroutput>/System/</computeroutput>,
1607 <computeroutput>/Library/</computeroutput> or
1608 <computeroutput>/Applications/</computeroutput>
1609 since <computeroutput>dsymutil</computeroutput> will always fail
1610 in such situations. It fails both because the debuginfo for
1611 such pre-installed system components is not available anywhere,
1612 and also because it would require write privileges in those
1615 <para>Be careful when
1616 using <option>--dsymutil=yes</option>, since it will
1617 cause pre-existing <computeroutput>.dSYM</computeroutput>
1618 directories to be silently deleted and re-created. Also note that
1619 <computeroutput>dsymutil</computeroutput> is quite slow, sometimes
1620 excessively so.</para>
1624 <varlistentry id="opt.max-stackframe" xreflabel="--max-stackframe">
1626 <option><![CDATA[--max-stackframe=<number> [default: 2000000] ]]></option>
1629 <para>The maximum size of a stack frame. If the stack pointer moves by
1630 more than this amount then Valgrind will assume that
1631 the program is switching to a different stack.</para>
1633 <para>You may need to use this option if your program has large
1634 stack-allocated arrays. Valgrind keeps track of your program's
1635 stack pointer. If it changes by more than the threshold amount,
1636 Valgrind assumes your program is switching to a different stack,
1637 and Memcheck behaves differently than it would for a stack pointer
1638 change smaller than the threshold. Usually this heuristic works
1639 well. However, if your program allocates large structures on the
1640 stack, this heuristic will be fooled, and Memcheck will
1641 subsequently report large numbers of invalid stack accesses. This
1642 option allows you to change the threshold to a different
1645 <para>You should only consider use of this option if Valgrind's
1646 debug output directs you to do so. In that case it will tell you
1647 the new threshold you should specify.</para>
1649 <para>In general, allocating large structures on the stack is a
1650 bad idea, because you can easily run out of stack space,
1651 especially on systems with limited memory or which expect to
1652 support large numbers of threads each with a small stack, and also
1653 because the error checking performed by Memcheck is more effective
1654 for heap-allocated data than for stack-allocated data. If you
1655 have to use this option, you may wish to consider rewriting your
1656 code to allocate on the heap rather than on the stack.</para>
1660 <varlistentry id="opt.main-stacksize" xreflabel="--main-stacksize">
1662 <option><![CDATA[--main-stacksize=<number>
1663 [default: use current 'ulimit' value] ]]></option>
1666 <para>Specifies the size of the main thread's stack.</para>
1668 <para>To simplify its memory management, Valgrind reserves all
1669 required space for the main thread's stack at startup. That
1670 means it needs to know the required stack size at
1673 <para>By default, Valgrind uses the current "ulimit" value for
1674 the stack size, or 16 MB, whichever is lower. In many cases
1675 this gives a stack size in the range 8 to 16 MB, which almost
1676 never overflows for most applications.</para>
1678 <para>If you need a larger total stack size,
1679 use <option>--main-stacksize</option> to specify it. Only set
1680 it as high as you need, since reserving far more space than you
1681 need (that is, hundreds of megabytes more than you need)
1682 constrains Valgrind's memory allocators and may reduce the total
1683 amount of memory that Valgrind can use. This is only really of
1684 significance on 32-bit machines.</para>
1686 <para>On Linux, you may request a stack of size up to 2GB.
1687 Valgrind will stop with a diagnostic message if the stack cannot
1688 be allocated.</para>
1690 <para><option>--main-stacksize</option> only affects the stack
1691 size for the program's initial thread. It has no bearing on the
1692 size of thread stacks, as Valgrind does not allocate
1695 <para>You may need to use both <option>--main-stacksize</option>
1696 and <option>--max-stackframe</option> together. It is important
1697 to understand that <option>--main-stacksize</option> sets the
1698 maximum total stack size,
1699 whilst <option>--max-stackframe</option> specifies the largest
1700 size of any one stack frame. You will have to work out
1701 the <option>--main-stacksize</option> value for yourself
1702 (usually, if your applications segfaults). But Valgrind will
1703 tell you the needed <option>--max-stackframe</option> size, if
1706 <para>As discussed further in the description
1707 of <option>--max-stackframe</option>, a requirement for a large
1708 stack is a sign of potential portability problems. You are best
1709 advised to place all large data in heap-allocated memory.</para>
1713 <varlistentry id="opt.max-threads" xreflabel="--max-threads">
1715 <option><![CDATA[--max-threads=<number> [default: 500] ]]></option>
1718 <para>By default, Valgrind can handle to up to 500 threads.
1719 Occasionally, that number is too small. Use this option to
1720 provide a different limit. E.g.
1721 <computeroutput>--max-threads=3000</computeroutput>.
1727 <!-- end of xi:include in the manpage -->
1732 <sect2 id="manual-core.mallocopts" xreflabel="malloc-related Options">
1733 <title>malloc-related Options</title>
1735 <!-- start of xi:include in the manpage -->
1736 <para id="malloc-related.opts.para">For tools that use their own version of
1737 <computeroutput>malloc</computeroutput> (e.g. Memcheck,
1738 Massif, Helgrind, DRD), the following options apply.</para>
1740 <variablelist id="malloc-related.opts.list">
1742 <varlistentry id="opt.alignment" xreflabel="--alignment">
1744 <option><![CDATA[--alignment=<number> [default: 8 or 16, depending on the platform] ]]></option>
1747 <para>By default Valgrind's <function>malloc</function>,
1748 <function>realloc</function>, etc, return a block whose starting
1749 address is 8-byte aligned or 16-byte aligned (the value depends on the
1750 platform and matches the platform default). This option allows you to
1751 specify a different alignment. The supplied value must be greater
1752 than or equal to the default, less than or equal to 4096, and must be
1753 a power of two.</para>
1757 <varlistentry id="opt.redzone-size" xreflabel="--redzone-size">
1759 <option><![CDATA[--redzone-size=<number> [default: depends on the tool] ]]></option>
1762 <para> Valgrind's <function>malloc, realloc,</function> etc, add
1763 padding blocks before and after each heap block allocated by the
1764 program being run. Such padding blocks are called redzones. The
1765 default value for the redzone size depends on the tool. For
1766 example, Memcheck adds and protects a minimum of 16 bytes before
1767 and after each block allocated by the client. This allows it to
1768 detect block underruns or overruns of up to 16 bytes.
1770 <para>Increasing the redzone size makes it possible to detect
1771 overruns of larger distances, but increases the amount of memory
1772 used by Valgrind. Decreasing the redzone size will reduce the
1773 memory needed by Valgrind but also reduces the chances of
1774 detecting over/underruns, so is not recommended.</para>
1778 <varlistentry id="opt.xtree-memory" xreflabel="--xtree-memory">
1780 <option><![CDATA[--xtree-memory=none|allocs|full [none] ]]></option>
1783 <para> Tools replacing Valgrind's <function>malloc,
1784 realloc,</function> etc, can optionally produce an execution
1785 tree detailing which piece of code is responsible for heap
1786 memory usage. See <xref linkend="manual-core.xtree"/>
1787 for a detailed explanation about execution trees. </para>
1789 <para> When set to <varname>none</varname>, no memory execution
1790 tree is produced.</para>
1792 <para> When set to <varname>allocs</varname>, the memory
1793 execution tree gives the current number of allocated bytes and
1794 the current number of allocated blocks. </para>
1796 <para> When set to <varname>full</varname>, the memory execution
1797 tree gives 6 different measurements : the current number of
1798 allocated bytes and blocks (same values as
1799 for <varname>allocs</varname>), the total number of allocated
1800 bytes and blocks, the total number of freed bytes and
1803 <para>Note that the overhead in cpu and memory to produce
1804 an xtree depends on the tool. The overhead in cpu is small for
1805 the value <varname>allocs</varname>, as the information needed
1806 to produce this report is maintained in any case by the tool.
1807 For massif and helgrind, specifying <varname>full</varname>
1808 implies to capture a stack trace for each free operation,
1809 while normally these tools only capture an allocation stack
1810 trace. For Memcheck, the cpu overhead for the
1811 value <varname>full</varname> is small, as this can only be
1812 used in combination with
1813 <option>--keep-stacktraces=alloc-and-free</option> or
1814 <option>--keep-stacktraces=alloc-then-free</option>, which
1815 already records a stack trace for each free operation. The
1816 memory overhead varies between 5 and 10 words per unique
1817 stacktrace in the xtree, plus the memory needed to record the
1818 stack trace for the free operations, if needed specifically
1824 <varlistentry id="opt.xtree-memory-file" xreflabel="--xtree-memory-file">
1826 <option><![CDATA[--xtree-memory-file=<filename> [default:
1827 xtmemory.kcg.%p] ]]></option>
1830 <para>Specifies that Valgrind should produce the xtree memory
1831 report in the specified file. Any <option>%p</option> or
1832 <option>%q</option> sequences appearing in the filename are expanded
1833 in exactly the same way as they are for <option>--log-file</option>.
1834 See the description of <xref linkend="opt.log-file"/>
1835 for details. </para>
1836 <para>If the filename contains the extension <option>.ms</option>,
1837 then the produced file format will be a massif output file format.
1838 If the filename contains the extension <option>.kcg</option>
1839 or no extension is provided or recognised,
1840 then the produced file format will be a callgrind output format.</para>
1841 <para>See <xref linkend="manual-core.xtree"/>
1842 for a detailed explanation about execution trees formats. </para>
1847 <!-- end of xi:include in the manpage -->
1852 <sect2 id="manual-core.rareopts" xreflabel="Uncommon Options">
1853 <title>Uncommon Options</title>
1855 <!-- start of xi:include in the manpage -->
1856 <para id="uncommon.opts.para">These options apply to all tools, as they
1857 affect certain obscure workings of the Valgrind core. Most people won't
1858 need to use them.</para>
1860 <variablelist id="uncommon.opts.list">
1862 <varlistentry id="opt.smc-check" xreflabel="--smc-check">
1864 <option><![CDATA[--smc-check=<none|stack|all|all-non-file>
1865 [default: all-non-file for x86/amd64/s390x, stack for other archs] ]]></option>
1868 <para>This option controls Valgrind's detection of self-modifying
1869 code. If no checking is done, when a program executes some code, then
1870 overwrites it with new code, and executes the new code, Valgrind will
1871 continue to execute the translations it made for the old code. This
1872 will likely lead to incorrect behaviour and/or crashes.</para>
1873 <para>For "modern" architectures -- anything that's not x86,
1874 amd64 or s390x -- the default is <varname>stack</varname>.
1875 This is because a correct program must take explicit action
1876 to reestablish D-I cache coherence following code
1877 modification. Valgrind observes and honours such actions,
1878 with the result that self-modifying code is transparently
1879 handled with zero extra cost.</para>
1880 <para>For x86, amd64 and s390x, the program is not required to
1881 notify the hardware of required D-I coherence syncing. Hence
1882 the default is <varname>all-non-file</varname>, which covers
1883 the normal case of generating code into an anonymous
1884 (non-file-backed) mmap'd area.</para>
1885 <para>The meanings of the four available settings are as
1886 follows. No detection (<varname>none</varname>),
1887 detect self-modifying code
1888 on the stack (which is used by GCC to implement nested
1889 functions) (<varname>stack</varname>), detect self-modifying code
1890 everywhere (<varname>all</varname>), and detect
1891 self-modifying code everywhere except in file-backed
1892 mappings (<varname>all-non-file</varname>).</para>
1893 <para>Running with <varname>all</varname> will slow Valgrind
1894 down noticeably. Running with <varname>none</varname> will
1895 rarely speed things up, since very little code gets
1896 dynamically generated in most programs. The
1897 <function>VALGRIND_DISCARD_TRANSLATIONS</function> client
1898 request is an alternative to <option>--smc-check=all</option>
1899 and <option>--smc-check=all-non-file</option>
1900 that requires more programmer effort but allows Valgrind to run
1901 your program faster, by telling it precisely when translations
1903 <!-- commented out because it causes broken links in the man page
1905 linkend="manual-core-adv.clientreq"/> for more details.
1908 <para><option>--smc-check=all-non-file</option> provides a
1909 cheaper but more limited version
1910 of <option>--smc-check=all</option>. It adds checks to any
1911 translations that do not originate from file-backed memory
1912 mappings. Typical applications that generate code, for example
1913 JITs in web browsers, generate code into anonymous mmaped areas,
1914 whereas the "fixed" code of the browser always lives in
1915 file-backed mappings. <option>--smc-check=all-non-file</option>
1916 takes advantage of this observation, limiting the overhead of
1917 checking to code which is likely to be JIT generated.</para>
1921 <varlistentry id="opt.read-inline-info" xreflabel="--read-inline-info">
1923 <option><![CDATA[--read-inline-info=<yes|no> [default: see below] ]]></option>
1926 <para>When enabled, Valgrind will read information about inlined
1927 function calls from DWARF3 debug info. This slows Valgrind
1928 startup and makes it use more memory (typically for each inlined
1929 piece of code, 6 words and space for the function name), but it
1930 results in more descriptive stacktraces. Currently,
1931 this functionality is enabled by default only for Linux,
1932 Android and Solaris targets and only for the tools Memcheck, Massif,
1933 Helgrind and DRD. Here is an example of some stacktraces with
1934 <option>--read-inline-info=no</option>:
1936 <programlisting><![CDATA[
1937 ==15380== Conditional jump or move depends on uninitialised value(s)
1938 ==15380== at 0x80484EA: main (inlinfo.c:6)
1940 ==15380== Conditional jump or move depends on uninitialised value(s)
1941 ==15380== at 0x8048550: fun_noninline (inlinfo.c:6)
1942 ==15380== by 0x804850E: main (inlinfo.c:34)
1944 ==15380== Conditional jump or move depends on uninitialised value(s)
1945 ==15380== at 0x8048520: main (inlinfo.c:6)
1946 ]]></programlisting>
1947 <para>And here are the same errors with
1948 <option>--read-inline-info=yes</option>:</para>
1949 <programlisting><![CDATA[
1950 ==15377== Conditional jump or move depends on uninitialised value(s)
1951 ==15377== at 0x80484EA: fun_d (inlinfo.c:6)
1952 ==15377== by 0x80484EA: fun_c (inlinfo.c:14)
1953 ==15377== by 0x80484EA: fun_b (inlinfo.c:20)
1954 ==15377== by 0x80484EA: fun_a (inlinfo.c:26)
1955 ==15377== by 0x80484EA: main (inlinfo.c:33)
1957 ==15377== Conditional jump or move depends on uninitialised value(s)
1958 ==15377== at 0x8048550: fun_d (inlinfo.c:6)
1959 ==15377== by 0x8048550: fun_noninline (inlinfo.c:41)
1960 ==15377== by 0x804850E: main (inlinfo.c:34)
1962 ==15377== Conditional jump or move depends on uninitialised value(s)
1963 ==15377== at 0x8048520: fun_d (inlinfo.c:6)
1964 ==15377== by 0x8048520: main (inlinfo.c:35)
1965 ]]></programlisting>
1969 <varlistentry id="opt.read-var-info" xreflabel="--read-var-info">
1971 <option><![CDATA[--read-var-info=<yes|no> [default: no] ]]></option>
1974 <para>When enabled, Valgrind will read information about
1975 variable types and locations from DWARF3 debug info.
1976 This slows Valgrind startup significantly and makes it use significantly
1977 more memory, but for the tools that can take advantage of it (Memcheck,
1978 Helgrind, DRD) it can result in more precise error messages. For example,
1979 here are some standard errors issued by Memcheck:</para>
1980 <programlisting><![CDATA[
1981 ==15363== Uninitialised byte(s) found during client check request
1982 ==15363== at 0x80484A9: croak (varinfo1.c:28)
1983 ==15363== by 0x8048544: main (varinfo1.c:55)
1984 ==15363== Address 0x80497f7 is 7 bytes inside data symbol "global_i2"
1986 ==15363== Uninitialised byte(s) found during client check request
1987 ==15363== at 0x80484A9: croak (varinfo1.c:28)
1988 ==15363== by 0x8048550: main (varinfo1.c:56)
1989 ==15363== Address 0xbea0d0cc is on thread 1's stack
1990 ==15363== in frame #1, created by main (varinfo1.c:45)
1991 ]]></programlisting>
1993 <para>And here are the same errors with
1994 <option>--read-var-info=yes</option>:</para>
1996 <programlisting><![CDATA[
1997 ==15370== Uninitialised byte(s) found during client check request
1998 ==15370== at 0x80484A9: croak (varinfo1.c:28)
1999 ==15370== by 0x8048544: main (varinfo1.c:55)
2000 ==15370== Location 0x80497f7 is 0 bytes inside global_i2[7],
2001 ==15370== a global variable declared at varinfo1.c:41
2003 ==15370== Uninitialised byte(s) found during client check request
2004 ==15370== at 0x80484A9: croak (varinfo1.c:28)
2005 ==15370== by 0x8048550: main (varinfo1.c:56)
2006 ==15370== Location 0xbeb4a0cc is 0 bytes inside local var "local"
2007 ==15370== declared at varinfo1.c:46, in frame #1 of thread 1
2008 ]]></programlisting>
2012 <varlistentry id="opt.vgdb-poll" xreflabel="--vgdb-poll">
2014 <option><![CDATA[--vgdb-poll=<number> [default: 5000] ]]></option>
2017 <para> As part of its main loop, the Valgrind scheduler will
2018 poll to check if some activity (such as an external command or
2019 some input from a gdb) has to be handled by gdbserver. This
2020 activity poll will be done after having run the given number of
2021 basic blocks (or slightly more than the given number of basic
2022 blocks). This poll is quite cheap so the default value is set
2023 relatively low. You might further decrease this value if vgdb
2024 cannot use ptrace system call to interrupt Valgrind if all
2025 threads are (most of the time) blocked in a system call.
2030 <varlistentry id="opt.vgdb-shadow-registers" xreflabel="--vgdb-shadow-registers">
2032 <option><![CDATA[--vgdb-shadow-registers=no|yes [default: no] ]]></option>
2035 <para> When activated, gdbserver will expose the Valgrind shadow registers
2036 to GDB. With this, the value of the Valgrind shadow registers can be examined
2037 or changed using GDB. Exposing shadow registers only works with GDB version
2043 <varlistentry id="opt.vgdb-prefix" xreflabel="--vgdb-prefix">
2045 <option><![CDATA[--vgdb-prefix=<prefix> [default: /tmp/vgdb-pipe] ]]></option>
2048 <para> To communicate with gdb/vgdb, the Valgrind gdbserver
2049 creates 3 files (2 named FIFOs and a mmap shared memory
2050 file). The prefix option controls the directory and prefix for
2051 the creation of these files.
2056 <varlistentry id="opt.run-libc-freeres" xreflabel="--run-libc-freeres">
2058 <option><![CDATA[--run-libc-freeres=<yes|no> [default: yes] ]]></option>
2061 <para>This option is only relevant when running Valgrind on Linux.</para>
2063 <para>The GNU C library (<function>libc.so</function>), which is
2064 used by all programs, may allocate memory for its own uses.
2065 Usually it doesn't bother to free that memory when the program
2066 ends—there would be no point, since the Linux kernel reclaims
2067 all process resources when a process exits anyway, so it would
2068 just slow things down.</para>
2070 <para>The glibc authors realised that this behaviour causes leak
2071 checkers, such as Valgrind, to falsely report leaks in glibc, when
2072 a leak check is done at exit. In order to avoid this, they
2073 provided a routine called <function>__libc_freeres</function>
2074 specifically to make glibc release all memory it has allocated.
2075 Memcheck therefore tries to run
2076 <function>__libc_freeres</function> at exit.</para>
2078 <para>Unfortunately, in some very old versions of glibc,
2079 <function>__libc_freeres</function> is sufficiently buggy to cause
2080 segmentation faults. This was particularly noticeable on Red Hat
2081 7.1. So this option is provided in order to inhibit the run of
2082 <function>__libc_freeres</function>. If your program seems to run
2083 fine on Valgrind, but segfaults at exit, you may find that
2084 <option>--run-libc-freeres=no</option> fixes that, although at the
2085 cost of possibly falsely reporting space leaks in
2086 <filename>libc.so</filename>.</para>
2090 <varlistentry id="opt.run-cxx-freeres" xreflabel="--run-cxx-freeres">
2092 <option><![CDATA[--run-cxx-freeres=<yes|no> [default: yes] ]]></option>
2095 <para>This option is only relevant when running Valgrind on Linux
2096 or Solaris C++ programs.</para>
2098 <para>The GNU Standard C++ library (<function>libstdc++.so</function>),
2099 which is used by all C++ programs compiled with g++, may allocate memory
2100 for its own uses. Usually it doesn't bother to free that memory when
2101 the program ends—there would be no point, since the kernel reclaims
2102 all process resources when a process exits anyway, so it would
2103 just slow things down.</para>
2105 <para>The gcc authors realised that this behaviour causes leak
2106 checkers, such as Valgrind, to falsely report leaks in libstdc++, when
2107 a leak check is done at exit. In order to avoid this, they
2108 provided a routine called <function>__gnu_cxx::__freeres</function>
2109 specifically to make libstdc++ release all memory it has allocated.
2110 Memcheck therefore tries to run
2111 <function>__gnu_cxx::__freeres</function> at exit.</para>
2113 <para>For the sake of flexibility and unforeseen problems with
2114 <function>__gnu_cxx::__freeres</function>, option
2115 <option>--run-cxx-freeres=no</option> exists,
2116 although at the cost of possibly falsely reporting space leaks in
2117 <filename>libstdc++.so</filename>.</para>
2121 <varlistentry id="opt.sim-hints" xreflabel="--sim-hints">
2123 <option><![CDATA[--sim-hints=hint1,hint2,... ]]></option>
2126 <para>Pass miscellaneous hints to Valgrind which slightly modify
2127 the simulated behaviour in nonstandard or dangerous ways, possibly
2128 to help the simulation of strange features. By default no hints
2129 are enabled. Use with caution! Currently known hints are:</para>
2133 <para><option>lax-ioctls: </option> Be very lax about ioctl
2134 handling; the only assumption is that the size is
2135 correct. Doesn't require the full buffer to be initialised
2136 when writing. Without this, using some device drivers with a
2137 large number of strange ioctl commands becomes very
2142 <para><option>fuse-compatible: </option> Enable special
2143 handling for certain system calls that may block in a FUSE
2144 file-system. This may be necessary when running Valgrind
2145 on a multi-threaded program that uses one thread to manage
2146 a FUSE file-system and another thread to access that
2152 <para><option>enable-outer: </option> Enable some special
2153 magic needed when the program being run is itself
2158 <para><option>no-inner-prefix: </option> Disable printing
2159 a prefix <option>></option> in front of each stdout or
2160 stderr output line in an inner Valgrind being run by an
2161 outer Valgrind. This is useful when running Valgrind
2162 regression tests in an outer/inner setup. Note that the
2163 prefix <option>></option> will always be printed in
2164 front of the inner debug logging lines.</para>
2167 <para><option>no-nptl-pthread-stackcache: </option>
2168 This hint is only relevant when running Valgrind on Linux;
2169 it is ignored on Solaris and Mac OS X.</para>
2171 <para>The GNU glibc pthread library
2172 (<function>libpthread.so</function>), which is used by
2173 pthread programs, maintains a cache of pthread stacks.
2174 When a pthread terminates, the memory used for the pthread
2175 stack and some thread local storage related data structure
2176 are not always directly released. This memory is kept in
2177 a cache (up to a certain size), and is re-used if a new
2178 thread is started.</para>
2180 <para>This cache causes the helgrind tool to report some
2181 false positive race condition errors on this cached
2182 memory, as helgrind does not understand the internal glibc
2183 cache synchronisation primitives. So, when using helgrind,
2184 disabling the cache helps to avoid false positive race
2185 conditions, in particular when using thread local storage
2186 variables (e.g. variables using the
2187 <function>__thread</function> qualifier).</para>
2189 <para>When using the memcheck tool, disabling the cache
2190 ensures the memory used by glibc to handle __thread
2191 variables is directly released when a thread
2194 <para>Note: Valgrind disables the cache using some internal
2195 knowledge of the glibc stack cache implementation and by
2196 examining the debug information of the pthread
2197 library. This technique is thus somewhat fragile and might
2198 not work for all glibc versions. This has been successfully
2199 tested with various glibc versions (e.g. 2.11, 2.16, 2.18)
2200 on various platforms.</para>
2203 <para><option>lax-doors: </option> (Solaris only) Be very lax
2204 about door syscall handling over unrecognised door file
2205 descriptors. Does not require that full buffer is initialised
2206 when writing. Without this, programs using libdoor(3LIB)
2207 functionality with completely proprietary semantics may report
2208 large number of false positives.</para>
2211 <para><option>fallback-llsc: </option>(MIPS and ARM64 only): Enables
2212 an alternative implementation of Load-Linked (LL) and
2213 Store-Conditional (SC) instructions. The standard implementation
2214 gives more correct behaviour, but can cause indefinite looping on
2215 certain processor implementations that are intolerant of extra
2216 memory references between LL and SC. So far this is known only to
2217 happen on Cavium 3 cores.
2219 You should not need to use this flag, since the relevant cores are
2220 detected at startup and the alternative implementation is
2221 automatically enabled if necessary. There is no equivalent
2222 anti-flag: you cannot force-disable the alternative
2223 implementation, if it is automatically enabled.
2225 The underlying problem exists because the "standard"
2226 implementation of LL and SC is done by copying through LL and SC
2227 instructions into the instrumented code. However, tools may
2228 insert extra instrumentation memory references in between the LL
2229 and SC instructions. These memory references are not present in
2230 the original uninstrumented code, and their presence in the
2231 instrumented code can cause the SC instructions to persistently
2232 fail, leading to indefinite looping in LL-SC blocks.
2234 The alternative implementation gives correct behaviour of LL and
2235 SC instructions between threads in a process, up to and including
2236 the ABA scenario. It also gives correct behaviour between a
2237 Valgrinded thread and a non-Valgrinded thread running in a
2238 different process, that communicate via shared memory, but only up
2239 to and including correct CAS behaviour -- in this case the ABA
2240 scenario may not be correctly handled.
2247 <varlistentry id="opt.fair-sched" xreflabel="--fair-sched">
2249 <option><![CDATA[--fair-sched=<no|yes|try> [default: no] ]]></option>
2252 <listitem> <para>The <option>--fair-sched</option> option controls
2253 the locking mechanism used by Valgrind to serialise thread
2254 execution. The locking mechanism controls the way the threads
2255 are scheduled, and different settings give different trade-offs
2256 between fairness and performance. For more details about the
2257 Valgrind thread serialisation scheme and its impact on
2258 performance and thread scheduling, see
2259 <xref linkend="&vg-pthreads-perf-sched-id;"/>.</para>
2262 <listitem> <para>The value <option>--fair-sched=yes</option>
2263 activates a fair scheduler. In short, if multiple threads are
2264 ready to run, the threads will be scheduled in a round robin
2265 fashion. This mechanism is not available on all platforms or
2266 Linux versions. If not available,
2267 using <option>--fair-sched=yes</option> will cause Valgrind to
2268 terminate with an error.</para>
2269 <para>You may find this setting improves overall
2270 responsiveness if you are running an interactive
2271 multithreaded program, for example a web browser, on
2275 <listitem> <para>The value <option>--fair-sched=try</option>
2276 activates fair scheduling if available on the
2277 platform. Otherwise, it will automatically fall back
2278 to <option>--fair-sched=no</option>.</para>
2281 <listitem> <para>The value <option>--fair-sched=no</option> activates
2282 a scheduler which does not guarantee fairness
2283 between threads ready to run, but which in general gives the
2284 highest performance.</para>
2291 <varlistentry id="opt.kernel-variant" xreflabel="--kernel-variant">
2293 <option>--kernel-variant=variant1,variant2,...</option>
2296 <para>Handle system calls and ioctls arising from minor variants
2297 of the default kernel for this platform. This is useful for
2298 running on hacked kernels or with kernel modules which support
2299 nonstandard ioctls, for example. Use with caution. If you don't
2300 understand what this option does then you almost certainly don't
2301 need it. Currently known variants are:</para>
2304 <para><option>bproc</option>: support the
2305 <function>sys_broc</function> system call on x86. This is for
2306 running on BProc, which is a minor variant of standard Linux which
2307 is sometimes used for building clusters.
2311 <para><option>android-no-hw-tls</option>: some
2312 versions of the Android emulator for ARM do not provide a
2313 hardware TLS (thread-local state) register, and Valgrind
2314 crashes at startup. Use this variant to select software
2319 <para><option>android-gpu-sgx5xx</option>: use this to
2320 support handling of proprietary ioctls for the PowerVR SGX
2321 5XX series of GPUs on Android devices. Failure to select
2322 this does not cause stability problems, but may cause
2323 Memcheck to report false errors after the program performs
2324 GPU-specific ioctls.
2328 <para><option>android-gpu-adreno3xx</option>: similarly, use
2329 this to support handling of proprietary ioctls for the
2330 Qualcomm Adreno 3XX series of GPUs on Android devices.
2337 <varlistentry id="opt.merge-recursive-frames" xreflabel="--merge-recursive-frames">
2339 <option><![CDATA[--merge-recursive-frames=<number> [default: 0] ]]></option>
2342 <para>Some recursive algorithms, for example balanced binary
2343 tree implementations, create many different stack traces, each
2344 containing cycles of calls. A cycle is defined as two identical
2345 program counter values separated by zero or more other program
2346 counter values. Valgrind may then use a lot of memory to store
2347 all these stack traces. This is a poor use of memory
2348 considering that such stack traces contain repeated
2349 uninteresting recursive calls instead of more interesting
2350 information such as the function that has initiated the
2353 <para>The option <option>--merge-recursive-frames=<number></option>
2354 instructs Valgrind to detect and merge recursive call cycles
2355 having a size of up to <option><number></option>
2356 frames. When such a cycle is detected, Valgrind records the
2357 cycle in the stack trace as a unique program counter.
2360 The value 0 (the default) causes no recursive call merging.
2361 A value of 1 will cause stack traces of simple recursive algorithms
2362 (for example, a factorial implementation) to be collapsed.
2363 A value of 2 will usually be needed to collapse stack traces produced
2364 by recursive algorithms such as binary trees, quick sort, etc.
2365 Higher values might be needed for more complex recursive algorithms.
2367 <para>Note: recursive calls are detected by analysis of program
2368 counter values. They are not detected by looking at function
2373 <varlistentry id="opt.num-transtab-sectors" xreflabel="--num-transtab-sectors">
2375 <option><![CDATA[--num-transtab-sectors=<number> [default: 6
2376 for Android platforms, 16 for all others] ]]></option>
2379 <para>Valgrind translates and instruments your program's machine
2380 code in small fragments (basic blocks). The translations are stored in a
2381 translation cache that is divided into a number of sections
2382 (sectors). If the cache is full, the sector containing the
2383 oldest translations is emptied and reused. If these old
2384 translations are needed again, Valgrind must re-translate and
2385 re-instrument the corresponding machine code, which is
2386 expensive. If the "executed instructions" working set of a
2387 program is big, increasing the number of sectors may improve
2388 performance by reducing the number of re-translations needed.
2389 Sectors are allocated on demand. Once allocated, a sector can
2390 never be freed, and occupies considerable space, depending on the tool
2391 and the value of <option>--avg-transtab-entry-size</option>
2392 (about 40 MB per sector for Memcheck). Use the
2393 option <option>--stats=yes</option> to obtain precise
2394 information about the memory used by a sector and the allocation
2395 and recycling of sectors.</para>
2399 <varlistentry id="opt.avg-transtab-entry-size" xreflabel="--avg-transtab-entry-size">
2401 <option><![CDATA[--avg-transtab-entry-size=<number> [default: 0,
2402 meaning use tool provided default] ]]></option>
2405 <para>Average size of translated basic block. This average size
2406 is used to dimension the size of a sector.
2407 Each tool provides a default value to be used.
2408 If this default value is too small, the translation sectors
2409 will become full too quickly. If this default value is too big,
2410 a significant part of the translation sector memory will be unused.
2411 Note that the average size of a basic block translation depends
2412 on the tool, and might depend on tool options. For example,
2413 the memcheck option <option>--track-origins=yes</option>
2414 increases the size of the basic block translations.
2415 Use <option>--avg-transtab-entry-size</option> to tune the size of the
2416 sectors, either to gain memory or to avoid too many retranslations.
2421 <varlistentry id="opt.aspace-minaddr" xreflabel="----aspace-minaddr">
2423 <option><![CDATA[--aspace-minaddr=<address> [default: depends
2424 on the platform] ]]></option>
2427 <para>To avoid potential conflicts with some system libraries,
2428 Valgrind does not use the address space
2429 below <option>--aspace-minaddr</option> value, keeping it
2430 reserved in case a library specifically requests memory in this
2431 region. So, some "pessimistic" value is guessed by Valgrind
2432 depending on the platform. On linux, by default, Valgrind avoids
2433 using the first 64MB even if typically there is no conflict in
2434 this complete zone. You can use the
2435 option <option>--aspace-minaddr</option> to have your memory
2436 hungry application benefitting from more of this lower memory.
2437 On the other hand, if you encounter a conflict, increasing
2438 aspace-minaddr value might solve it. Conflicts will typically
2439 manifest themselves with mmap failures in the low range of the
2441 provided <computeroutput>address</computeroutput> must be page
2442 aligned and must be equal or bigger to 0x1000 (4KB). To find the
2443 default value on your platform, do something such as
2444 <computeroutput>valgrind -d -d date 2>&1 | grep -i minaddr</computeroutput>.
2445 Values lower than 0x10000 (64KB) are known to create problems
2446 on some distributions.
2451 <varlistentry id="opt.valgrind-stacksize" xreflabel="----valgrind-stacksize">
2453 <option><![CDATA[--valgrind-stacksize=<number> [default: 1MB] ]]></option>
2456 <para>For each thread, Valgrind needs its own 'private' stack.
2457 The default size for these stacks is largely dimensioned, and so
2458 should be sufficient in most cases. In case the size is too small,
2459 Valgrind will segfault. Before segfaulting, a warning might be produced
2460 by Valgrind when approaching the limit.
2463 Use the option <option>--valgrind-stacksize</option> if such an (unlikely)
2464 warning is produced, or Valgrind dies due to a segmentation violation.
2465 Such segmentation violations have been seen when demangling huge C++
2468 <para>If your application uses many threads and needs a lot of memory, you can
2469 gain some memory by reducing the size of these Valgrind stacks using
2470 the option <option>--valgrind-stacksize</option>.
2475 <varlistentry id="opt.show-emwarns" xreflabel="--show-emwarns">
2477 <option><![CDATA[--show-emwarns=<yes|no> [default: no] ]]></option>
2480 <para>When enabled, Valgrind will emit warnings about its CPU
2481 emulation in certain cases. These are usually not
2486 <varlistentry id="opt.require-text-symbol"
2487 xreflabel="--require-text-symbol">
2489 <option><![CDATA[--require-text-symbol=:sonamepatt:fnnamepatt]]></option>
2492 <para>When a shared object whose soname
2493 matches <varname>sonamepatt</varname> is loaded into the
2494 process, examine all the text symbols it exports. If none of
2495 those match <varname>fnnamepatt</varname>, print an error
2496 message and abandon the run. This makes it possible to ensure
2497 that the run does not continue unless a given shared object
2498 contains a particular function name.
2501 Both <varname>sonamepatt</varname> and
2502 <varname>fnnamepatt</varname> can be written using the usual
2503 <varname>?</varname> and <varname>*</varname> wildcards. For
2504 example: <varname>":*libc.so*:foo?bar"</varname>. You may use
2505 characters other than a colon to separate the two patterns. It
2506 is only important that the first character and the separator
2507 character are the same. For example, the above example could
2508 also be written <varname>"Q*libc.so*Qfoo?bar"</varname>.
2509 Multiple <varname> --require-text-symbol</varname> flags are
2510 allowed, in which case shared objects that are loaded into
2511 the process will be checked against all of them.
2514 The purpose of this is to support reliable usage of marked-up
2515 libraries. For example, suppose we have a version of GCC's
2516 <varname>libgomp.so</varname> which has been marked up with
2517 annotations to support Helgrind. It is only too easy and
2518 confusing to load the wrong, un-annotated
2519 <varname>libgomp.so</varname> into the application. So the idea
2520 is: add a text symbol in the marked-up library, for
2521 example <varname>annotated_for_helgrind_3_6</varname>, and then
2523 <varname>--require-text-symbol=:*libgomp*so*:annotated_for_helgrind_3_6</varname>
2524 so that when <varname>libgomp.so</varname> is loaded, Valgrind
2525 scans its symbol table, and if the symbol isn't present the run
2526 is aborted, rather than continuing silently with the
2527 un-marked-up library. Note that you should put the entire flag
2528 in quotes to stop shells expanding up the <varname>*</varname>
2529 and <varname>?</varname> wildcards.
2534 <varlistentry id="opt.soname-synonyms"
2535 xreflabel="--soname-synonyms">
2537 <option><![CDATA[--soname-synonyms=syn1=pattern1,syn2=pattern2,...]]></option>
2540 <para>When a shared library is loaded, Valgrind checks for
2541 functions in the library that must be replaced or wrapped. For
2542 example, Memcheck replaces some string and memory functions
2543 (strchr, strlen, strcpy, memchr, memcpy, memmove, etc.) with its
2544 own versions. Such replacements are normally done only in shared
2545 libraries whose soname matches a predefined soname pattern (e.g.
2546 <varname>libc.so*</varname> on linux). By default, no
2547 replacement is done for a statically linked binary or for
2548 alternative libraries, except for the allocation functions
2549 (malloc, free, calloc, memalign, realloc, operator new, operator
2550 delete, etc.) Such allocation functions are intercepted by
2551 default in any shared library or in the executable if they are
2552 exported as global symbols. This means that if a replacement
2553 allocation library such as tcmalloc is found, its functions are
2554 also intercepted by default.
2556 In some cases, the replacements allow
2557 <option>--soname-synonyms</option> to specify one additional
2558 synonym pattern, giving flexibility in the replacement. Or to
2559 prevent interception of all public allocation symbols.</para>
2561 <para>Currently, this flexibility is only allowed for the
2562 malloc related functions, using the
2563 synonym <varname>somalloc</varname>. This synonym is usable for
2564 all tools doing standard replacement of malloc related functions
2565 (e.g. memcheck, helgrind, drd, massif, dhat, exp-sgcheck).
2571 <para>Alternate malloc library: to replace the malloc
2572 related functions in a specific alternate library with
2573 soname <varname>mymalloclib.so</varname> (and not in any
2575 option <option>--soname-synonyms=somalloc=mymalloclib.so</option>.
2576 A pattern can be used to match multiple libraries sonames.
2578 example, <option>--soname-synonyms=somalloc=*tcmalloc*</option>
2579 will match the soname of all variants of the tcmalloc
2580 library (native, debug, profiled, ... tcmalloc
2582 <para>Note: the soname of a elf shared library can be
2583 retrieved using the readelf utility. </para>
2588 <para>Replacements in a statically linked library are done
2589 by using the <varname>NONE</varname> pattern. For example,
2590 if you link with <varname>libtcmalloc.a</varname>, and only
2591 want to intercept the malloc related functions in the
2592 executable (and standard libraries) themselves, but not any
2593 other shared libraries, you can give the
2594 option <option>--soname-synonyms=somalloc=NONE</option>.
2595 Note that a NONE pattern will match the main executable and
2596 any shared library having no soname. </para>
2600 <para>To run a "default" Firefox build for Linux, in which
2601 JEMalloc is linked in to the main executable,
2602 use <option>--soname-synonyms=somalloc=NONE</option>.
2607 <para>To only intercept allocation symbols in the default
2608 system libraries, but not in any other shared library or the
2609 executable defining public malloc or operator new related
2610 functions use a non-existing library name
2611 like <option>--soname-synonyms=somalloc=nouserintercepts</option>
2612 (where <varname>nouserintercepts</varname> can be any
2613 non-existing library name).
2618 <para>Shared library of the dynamic (runtime) linker is excluded from
2619 searching for global public symbols, such as those for the malloc
2620 related functions (identified by <varname>somalloc</varname> synonym).
2628 <varlistentry id="opt.progress-interval" xreflabel="--progress-interval">
2630 <option><![CDATA[--progress-interval=<number> [default: 0, meaning 'disabled'] ]]></option>
2633 <para>This is an enhancement to Valgrind's debugging output. It is
2634 unlikely to be of interest to end users.</para>
2635 <para>When <varname>number</varname> is set to a non-zero value,
2636 Valgrind will print a one-line progress summary
2637 every <varname>number</varname> seconds. Valid settings
2638 for <varname>number</varname> are between 0 and 3600
2639 inclusive. Here's some example output
2640 with <varname>number</varname>
2642 <programlisting><![CDATA[
2643 PROGRESS: U 110s, W 113s, 97.3% CPU, EvC 414.79M, TIn 616.7k, TOut 0.5k, #thr 67
2644 PROGRESS: U 120s, W 124s, 96.8% CPU, EvC 505.27M, TIn 636.6k, TOut 3.0k, #thr 64
2645 PROGRESS: U 130s, W 134s, 97.0% CPU, EvC 574.90M, TIn 657.5k, TOut 3.0k, #thr 63
2646 ]]></programlisting>
2649 <listitem><varname>U</varname>: total user time</listitem>
2650 <listitem><varname>W</varname>: total wallclock time</listitem>
2651 <listitem><varname>CPU</varname>: overall average cpu use</listitem>
2652 <listitem><varname>EvC</varname>: number of event checks. An event
2653 check is a backwards branch in the simulated program, so this is a
2654 measure of forward progress of the program</listitem>
2655 <listitem><varname>TIn</varname>: number of code blocks instrumented
2656 by the JIT</listitem>
2657 <listitem><varname>TOut</varname>: number of instrumented code
2658 blocks that have been thrown away</listitem>
2659 <listitem><varname>#thr</varname>: number of threads in the
2662 From the progress of these, it is possible to observe:
2664 <listitem>when the program is compute bound (<varname>TIn</varname>
2665 rises slowly, <varname>EvC</varname> rises rapidly)</listitem>
2666 <listitem>when the program is in a spinloop
2667 (<varname>TIn</varname>/<varname>TOut</varname>
2668 fixed, <varname>EvC</varname> rises rapidly)</listitem>
2669 <listitem>when the program is JIT-bound (<varname>TIn</varname>
2670 rises rapidly)</listitem>
2671 <listitem>when the program is rapidly discarding code
2672 (<varname>TOut</varname> rises rapidly)</listitem>
2673 <listitem>when the program is about to achieve some expected state
2674 (<varname>EvC</varname> arrives at some value you
2676 <listitem> when the program is idling (<varname>U</varname> rises
2677 more slowly than <varname>W</varname>)</listitem>
2684 <!-- end of xi:include in the manpage -->
2689 <sect2 id="manual-core.debugopts" xreflabel="Debugging Options">
2690 <title>Debugging Options</title>
2692 <!-- start of xi:include in the manpage -->
2693 <para id="debug.opts.para">There are also some options for debugging
2694 Valgrind itself. You shouldn't need to use them in the normal run of
2695 things. If you wish to see the list, use the
2696 <option>--help-debug</option> option.</para>
2698 <para>If you wish to debug your program rather than debugging
2699 Valgrind itself, then you should use the options
2700 <option>--vgdb=yes</option> or <option>--vgdb=full</option>.
2703 <!-- end of xi:include in the manpage -->
2708 <sect2 id="manual-core.defopts" xreflabel="Setting Default Options">
2709 <title>Setting Default Options</title>
2711 <para>Note that Valgrind also reads options from three places:</para>
2715 <para>The file <computeroutput>~/.valgrindrc</computeroutput></para>
2719 <para>The environment variable
2720 <computeroutput>$VALGRIND_OPTS</computeroutput></para>
2724 <para>The file <computeroutput>./.valgrindrc</computeroutput></para>
2728 <para>These are processed in the given order, before the
2729 command-line options. Options processed later override those
2730 processed earlier; for example, options in
2731 <computeroutput>./.valgrindrc</computeroutput> will take
2732 precedence over those in
2733 <computeroutput>~/.valgrindrc</computeroutput>.
2736 <para>Please note that the <computeroutput>./.valgrindrc</computeroutput>
2737 file is ignored if it is not a regular file, or is marked as world writeable,
2738 or is not owned by the current user. This is because the
2739 <computeroutput>./.valgrindrc</computeroutput> can contain options that are
2740 potentially harmful or can be used by a local attacker to execute code under
2744 <para>Any tool-specific options put in
2745 <computeroutput>$VALGRIND_OPTS</computeroutput> or the
2746 <computeroutput>.valgrindrc</computeroutput> files should be
2747 prefixed with the tool name and a colon. For example, if you
2748 want Memcheck to always do leak checking, you can put the
2749 following entry in <literal>~/.valgrindrc</literal>:</para>
2751 <programlisting><![CDATA[
2752 --memcheck:leak-check=yes]]></programlisting>
2754 <para>This will be ignored if any tool other than Memcheck is
2755 run. Without the <computeroutput>memcheck:</computeroutput>
2756 part, this will cause problems if you select other tools that
2758 <option>--leak-check=yes</option>.</para>
2766 <sect1 id="manual-core.pthreads" xreflabel="Support for Threads">
2767 <title>Support for Threads</title>
2769 <para>Threaded programs are fully supported.</para>
2771 <para>The main thing to point out with respect to threaded programs is
2772 that your program will use the native threading library, but Valgrind
2773 serialises execution so that only one (kernel) thread is running at a
2774 time. This approach avoids the horrible implementation problems of
2775 implementing a truly multithreaded version of Valgrind, but it does
2776 mean that threaded apps never use more than one CPU simultaneously,
2777 even if you have a multiprocessor or multicore machine.</para>
2779 <para>Valgrind doesn't schedule the threads itself. It merely ensures
2780 that only one thread runs at once, using a simple locking scheme. The
2781 actual thread scheduling remains under control of the OS kernel. What
2782 this does mean, though, is that your program will see very different
2783 scheduling when run on Valgrind than it does when running normally.
2784 This is both because Valgrind is serialising the threads, and because
2785 the code runs so much slower than normal.</para>
2787 <para>This difference in scheduling may cause your program to behave
2788 differently, if you have some kind of concurrency, critical race,
2789 locking, or similar, bugs. In that case you might consider using the
2790 tools Helgrind and/or DRD to track them down.</para>
2792 <para>On Linux, Valgrind also supports direct use of the
2793 <computeroutput>clone</computeroutput> system call,
2794 <computeroutput>futex</computeroutput> and so on.
2795 <computeroutput>clone</computeroutput> is supported where either
2796 everything is shared (a thread) or nothing is shared (fork-like); partial
2800 <!-- Referenced from both the manual and manpage -->
2801 <sect2 id="&vg-pthreads-perf-sched-id;" xreflabel="&vg-pthreads-perf-sched-label;">
2802 <title>Scheduling and Multi-Thread Performance</title>
2804 <para>A thread executes code only when it holds the abovementioned
2805 lock. After executing some number of instructions, the running thread
2806 will release the lock. All threads ready to run will then compete to
2807 acquire the lock.</para>
2809 <para>The <option>--fair-sched</option> option controls the locking mechanism
2810 used to serialise thread execution.</para>
2812 <para>The default pipe based locking mechanism
2813 (<option>--fair-sched=no</option>) is available on all
2814 platforms. Pipe based locking does not guarantee fairness between
2815 threads: it is quite likely that a thread that has just released the
2816 lock reacquires it immediately, even though other threads are ready to
2817 run. When using pipe based locking, different runs of the same
2818 multithreaded application might give very different thread
2821 <para>An alternative locking mechanism, based on futexes, is available
2822 on some platforms. If available, it is activated
2823 by <option>--fair-sched=yes</option> or
2824 <option>--fair-sched=try</option>. Futex based locking ensures
2825 fairness (round-robin scheduling) between threads: if multiple threads
2826 are ready to run, the lock will be given to the thread which first
2827 requested the lock. Note that a thread which is blocked in a system
2828 call (e.g. in a blocking read system call) has not (yet) requested the
2829 lock: such a thread requests the lock only after the system call is
2832 <para> The fairness of the futex based locking produces better
2833 reproducibility of thread scheduling for different executions of a
2834 multithreaded application. This better reproducibility is particularly
2835 helpful when using Helgrind or DRD.</para>
2837 <para>Valgrind's use of thread serialisation implies that only one
2838 thread at a time may run. On a multiprocessor/multicore system, the
2839 running thread is assigned to one of the CPUs by the OS kernel
2840 scheduler. When a thread acquires the lock, sometimes the thread will
2841 be assigned to the same CPU as the thread that just released the
2842 lock. Sometimes, the thread will be assigned to another CPU. When
2843 using pipe based locking, the thread that just acquired the lock
2844 will usually be scheduled on the same CPU as the thread that just
2845 released the lock. With the futex based mechanism, the thread that
2846 just acquired the lock will more often be scheduled on another
2849 <para>Valgrind's thread serialisation and CPU assignment by the OS
2850 kernel scheduler can interact badly with the CPU frequency scaling
2851 available on many modern CPUs. To decrease power consumption, the
2852 frequency of a CPU or core is automatically decreased if the CPU/core
2853 has not been used recently. If the OS kernel often assigns the thread
2854 which just acquired the lock to another CPU/core, it is quite likely
2855 that this CPU/core is currently at a low frequency. The frequency of
2856 this CPU will be increased after some time. However, during this
2857 time, the (only) running thread will have run at the low frequency.
2858 Once this thread has run for some time, it will release the lock.
2859 Another thread will acquire this lock, and might be scheduled again on
2860 another CPU whose clock frequency was decreased in the
2863 <para>The futex based locking causes threads to change CPUs/cores more
2864 often. So, if CPU frequency scaling is activated, the futex based
2865 locking might decrease significantly the performance of a
2866 multithreaded app running under Valgrind. Performance losses of up to
2867 50% degradation have been observed, as compared to running on a
2868 machine for which CPU frequency scaling has been disabled. The pipe
2869 based locking locking scheme also interacts badly with CPU frequency
2870 scaling, with performance losses in the range 10..20% having been
2873 <para>To avoid such performance degradation, you should indicate to
2874 the kernel that all CPUs/cores should always run at maximum clock
2875 speed. Depending on your Linux distribution, CPU frequency scaling
2876 may be controlled using a graphical interface or using command line
2878 <computeroutput>cpufreq-selector</computeroutput> or
2879 <computeroutput>cpufreq-set</computeroutput>.
2882 <para>An alternative way to avoid these problems is to tell the
2883 OS scheduler to tie a Valgrind process to a specific (fixed) CPU using the
2884 <computeroutput>taskset</computeroutput> command. This should ensure
2885 that the selected CPU does not fall below its maximum frequency
2886 setting so long as any thread of the program has work to do.
2894 <sect1 id="manual-core.signals" xreflabel="Handling of Signals">
2895 <title>Handling of Signals</title>
2897 <para>Valgrind has a fairly complete signal implementation. It should be
2898 able to cope with any POSIX-compliant use of signals.</para>
2900 <para>If you're using signals in clever ways (for example, catching
2901 SIGSEGV, modifying page state and restarting the instruction), you're
2902 probably relying on precise exceptions. In this case, you will need
2903 to use <option>--vex-iropt-register-updates=allregs-at-mem-access</option>
2904 or <option>--vex-iropt-register-updates=allregs-at-each-insn</option>.
2907 <para>If your program dies as a result of a fatal core-dumping signal,
2908 Valgrind will generate its own core file
2909 (<computeroutput>vgcore.NNNNN</computeroutput>) containing your program's
2910 state. You may use this core file for post-mortem debugging with GDB or
2911 similar. (Note: it will not generate a core if your core dump size limit is
2912 0.) At the time of writing the core dumps do not include all the floating
2913 point register information.</para>
2915 <para>In the unlikely event that Valgrind itself crashes, the operating system
2916 will create a core dump in the usual way.</para>
2921 <sect1 id="manual-core.xtree" xreflabel="Execution Trees">
2922 <title>Execution Trees</title>
2924 <para>An execution tree (xtree) is made of a set of stack traces, each
2925 stack trace is associated with some resource consumptions or event
2926 counts. Depending on the xtree, different event counts/resource
2927 consumptions can be recorded in the xtree. Multiple tools can
2928 produce memory use xtree. Memcheck can output the leak search results
2931 <para> A typical usage for an xtree is to show a graphical or textual
2932 representation of the heap usage of a program. The below figure is
2933 a heap usage xtree graphical representation produced by
2934 kcachegrind. In the kcachegrind output, you can see that main
2935 current heap usage (allocated indirectly) is 528 bytes : 388 bytes
2936 allocated indirectly via a call to function f1 and 140 bytes
2937 indirectly allocated via a call to function f2. f2 has allocated
2938 memory by calling g2, while f1 has allocated memory by calling g11
2939 and g12. g11, g12 and g1 have directly called a memory allocation
2940 function (malloc), and so have a non zero 'Self' value. Note that when
2941 kcachegrind shows an xtree, the 'Called' column and call nr indications in
2942 the Call Graph are not significant (always set to 0 or 1, independently
2943 of the real nr of calls. The kcachegrind versions >= 0.8.0 do not show
2944 anymore such irrelevant xtree call number information.</para>
2946 <graphic fileref="images/kcachegrind_xtree.png" scalefit="1"/>
2948 <para>An xtree heap memory report is produced at the end of the
2949 execution when required using the
2950 option <option>--xtree-memory</option>. It can also be produced on
2951 demand using the <option>xtmemory</option> monitor command (see
2952 <xref linkend="manual-core-adv.valgrind-monitor-commands"/>). Currently,
2953 an xtree heap memory report can be produced by
2954 the <option>memcheck</option>, <option>helgrind</option>
2955 and <option>massif</option> tools.</para>
2957 <para>The xtrees produced by the option
2958 <xref linkend="opt.xtree-memory"/> or the <option>xtmemory</option>
2959 monitor command are showing the following events/resource
2960 consumption describing heap usage:</para>
2963 <para><option>curB</option> current number of Bytes allocated. The
2964 number of allocated bytes is added to the <option>curB</option>
2965 value of a stack trace for each allocation. It is decreased when
2966 a block allocated by this stack trace is released (by another
2967 "freeing" stack trace)</para>
2971 <para><option>curBk</option> current number of Blocks allocated,
2972 maintained similary to curB : +1 for each allocation, -1 when
2973 the block is freed.</para>
2977 <para><option>totB</option> total allocated Bytes. This is
2978 increased for each allocation with the number of allocated bytes.</para>
2982 <para><option>totBk</option> total allocated Blocks, maintained similary
2983 to totB : +1 for each allocation.</para>
2987 <para><option>totFdB</option> total Freed Bytes, increased each time
2988 a block is released by this ("freeing") stack trace : + nr freed bytes
2989 for each free operation.</para>
2993 <para><option>totFdBk</option> total Freed Blocks, maintained similarly
2994 to totFdB : +1 for each free operation.</para>
2997 <para>Note that the last 4 counts are produced only when the
2998 <option>--xtree-memory=full</option> was given at startup.</para>
3000 <para>Xtrees can be saved in 2 file formats, the "Callgrind Format" and
3001 the "Massif Format".</para>
3005 <para>Callgrind Format</para>
3006 <para>An xtree file in the Callgrind Format contains a single callgraph,
3007 associating each stack trace with the values recorded
3008 in the xtree. </para>
3009 <para>Different Callgrind Format file visualisers are available:</para>
3010 <para>Valgrind distribution includes the <option>callgrind_annotate</option>
3011 command line utility that reads in the xtree data, and prints a sorted
3012 lists of functions, optionally with source annotation. Note that due to
3013 xtree specificities, you must give the option
3014 <option>--inclusive=yes</option> to callgrind_annotate.</para>
3015 <para>For graphical visualization of the data, you can use
3016 <ulink url="&cl-gui-url;">KCachegrind</ulink>, which is a KDE/Qt based
3017 GUI that makes it easy to navigate the large amount of data that
3018 an xtree can contain.</para>
3019 <para>Note that xtree Callgrind Format does not make use of the inline
3020 information even when specifying <option>--read-inline-info=yes</option>.
3025 <para>Massif Format</para>
3026 <para>An xtree file in the Massif Format contains one detailed tree
3027 callgraph data for each type of event recorded in the xtree. So,
3028 for <option>--xtree-memory=alloc</option>, the output file will
3029 contain 2 detailed trees (for the counts <option>curB</option>
3030 and <option>curBk</option>),
3031 while <option>--xtree-memory=full</option> will give a file
3032 with 6 detailed trees.</para>
3033 <para>Different Massif Format file visualisers are available. Valgrind
3034 distribution includes the <option>ms_print</option>
3035 command line utility that produces an easy to read reprentation of
3036 a massif output file. See <xref linkend="ms-manual.using-print"/> and
3037 <xref linkend="ms-manual.using-visualizer"/> for more details
3038 about visualising Massif Format output files.</para>
3039 <para>Note that xtree Massif Format makes use of the inline
3040 information when specifying <option>--read-inline-info=yes</option>.
3046 <para>Note that for equivalent information, the Callgrind Format is more compact
3047 than the Massif Format. However, the Callgrind Format always contains the
3048 full data: there is no filtering done during file production, filtering is
3049 done by visualisers such as kcachegrind. kcachegrind is particularly easy to
3050 use to analyse big xtree data containing multiple events counts or resources
3051 consumption. The Massif Format (optionally) only contains a part of the data.
3052 For example, the Massif tool might filter some of the data, according to the
3053 <option>--threshold</option> option.
3056 <para>To clarify the xtree concept, the below gives several extracts of
3057 the output produced by the following commands:
3059 valgrind --xtree-memory=full --xtree-memory-file=xtmemory.kcg mfg
3060 callgrind_annotate --auto=yes --inclusive=yes --sort=curB:100,curBk:100,totB:100,totBk:100,totFdB:100,totFdBk:100 xtmemory.kcg
3064 <para>The below extract shows that the program mfg has allocated in
3065 total 770 bytes in 60 different blocks. Of these 60 blocks, 19 were
3066 freed, releasing a total of 242 bytes. The heap currently contains
3067 528 bytes in 41 blocks.</para>
3069 --------------------------------------------------------------------------------
3070 curB curBk totB totBk totFdB totFdBk
3071 --------------------------------------------------------------------------------
3072 528 41 770 60 242 19 PROGRAM TOTALS
3075 <para>The below gives more details about which functions have
3076 allocated or released memory. As an example, we see that main has
3077 (directly or indirectly) allocated 770 bytes of memory and freed
3078 (directly or indirectly) 242 bytes of memory. The function f1 has
3079 (directly or indirectly) allocated 570 bytes of memory, and has not
3080 (directly or indirectly) freed memory. Of the 570 bytes allocated
3081 by function f1, 388 bytes (34 blocks) have not been
3084 --------------------------------------------------------------------------------
3085 curB curBk totB totBk totFdB totFdBk file:function
3086 --------------------------------------------------------------------------------
3087 528 41 770 60 242 19 mfg.c:main
3088 388 34 570 50 0 0 mfg.c:f1
3089 220 20 330 30 0 0 mfg.c:g11
3090 168 14 240 20 0 0 mfg.c:g12
3091 140 7 200 10 0 0 mfg.c:g2
3092 140 7 200 10 0 0 mfg.c:f2
3093 0 0 0 0 131 10 mfg.c:freeY
3094 0 0 0 0 111 9 mfg.c:freeX
3097 <para>The below gives a more detailed information about the callgraph
3098 and which source lines/calls have (directly or indirectly) allocated or
3099 released memory. The below shows that the 770 bytes allocated by
3100 main have been indirectly allocated by calls to f1 and f2.
3101 Similarly, we see that the 570 bytes allocated by f1 have been
3102 indirectly allocated by calls to g11 and g12. Of the 330 bytes allocated
3103 by the 30 calls to g11, 168 bytes have not been freed.
3104 The function freeY (called once by main) has released in total
3105 10 blocks and 131 bytes. </para>
3107 --------------------------------------------------------------------------------
3108 -- Auto-annotated source: /home/philippe/valgrind/littleprogs/ + mfg.c
3109 --------------------------------------------------------------------------------
3110 curB curBk totB totBk totFdB totFdBk
3112 . . . . . . static void freeY(void)
3115 . . . . . . for (i = 0; i < next_ptr; i++)
3116 . . . . . . if(i % 5 == 0 && ptrs[i] != NULL)
3117 0 0 0 0 131 10 free(ptrs[i]);
3119 . . . . . . static void f1(void)
3122 . . . . . . for (i = 0; i < 30; i++)
3123 220 20 330 30 0 0 g11();
3124 . . . . . . for (i = 0; i < 20; i++)
3125 168 14 240 20 0 0 g12();
3127 . . . . . . int main()
3129 388 34 570 50 0 0 f1();
3130 140 7 200 10 0 0 f2();
3131 0 0 0 0 111 9 freeX();
3132 0 0 0 0 131 10 freeY();
3133 . . . . . . return 0;
3137 <para>Heap memory xtrees are helping to understand how your (big)
3138 program is using the heap. A full heap memory xtree helps to pin
3139 point some code that allocates a lot of small objects : allocating
3140 such small objects might be replaced by more efficient technique,
3141 such as allocating a big block using malloc, and then diviving this
3142 block into smaller blocks in order to decrease the cpu and/or memory
3143 overhead of allocating a lot of small blocks. Such full xtree information
3144 complements e.g. what callgrind can show: callgrind can show the number
3145 of calls to a function (such as malloc) but does not indicate the volume
3146 of memory allocated (or freed).</para>
3148 <para>A full heap memory xtree also can identify the code that allocates
3149 and frees a lot of blocks : the total foot print of the program might
3150 not reflect the fact that the same memory was over and over allocated
3151 then released.</para>
3153 <para>Finally, Xtree visualisers such as kcachegrind are helping to
3154 identify big memory consumers, in order to possibly optimise the
3155 amount of memory needed by your program.</para>
3159 <sect1 id="manual-core.install" xreflabel="Building and Installing">
3160 <title>Building and Installing Valgrind</title>
3162 <para>We use the standard Unix
3163 <computeroutput>./configure</computeroutput>,
3164 <computeroutput>make</computeroutput>, <computeroutput>make
3165 install</computeroutput> mechanism. Once you have completed
3166 <computeroutput>make install</computeroutput> you may then want
3167 to run the regression tests
3168 with <computeroutput>make regtest</computeroutput>.
3171 <para>In addition to the usual
3172 <option>--prefix=/path/to/install/tree</option>, there are three
3173 options which affect how Valgrind is built:
3177 <para><option>--enable-inner</option></para>
3178 <para>This builds Valgrind with some special magic hacks which make
3179 it possible to run it on a standard build of Valgrind (what the
3180 developers call "self-hosting"). Ordinarily you should not use
3181 this option as various kinds of safety checks are disabled.
3186 <para><option>--enable-only64bit</option></para>
3187 <para><option>--enable-only32bit</option></para>
3188 <para>On 64-bit platforms (amd64-linux, ppc64-linux,
3189 amd64-darwin), Valgrind is by default built in such a way that
3190 both 32-bit and 64-bit executables can be run. Sometimes this
3191 cleverness is a problem for a variety of reasons. These two
3192 options allow for single-target builds in this situation. If you
3193 issue both, the configure script will complain. Note they are
3194 ignored on 32-bit-only platforms (x86-linux, ppc32-linux,
3195 arm-linux, x86-darwin).
3202 <para>The <computeroutput>configure</computeroutput> script tests
3203 the version of the X server currently indicated by the current
3204 <computeroutput>$DISPLAY</computeroutput>. This is a known bug.
3205 The intention was to detect the version of the current X
3206 client libraries, so that correct suppressions could be selected
3207 for them, but instead the test checks the server version. This
3208 is just plain wrong.</para>
3210 <para>If you are building a binary package of Valgrind for
3211 distribution, please read <literal>README_PACKAGERS</literal>
3212 <xref linkend="dist.readme-packagers"/>. It contains some
3213 important information.</para>
3215 <para>Apart from that, there's not much excitement here. Let us
3216 know if you have build problems.</para>
3222 <sect1 id="manual-core.problems" xreflabel="If You Have Problems">
3223 <title>If You Have Problems</title>
3225 <para>Contact us at <ulink url="&vg-url;">&vg-url;</ulink>.</para>
3227 <para>See <xref linkend="manual-core.limits"/> for the known
3228 limitations of Valgrind, and for a list of programs which are
3229 known not to work on it.</para>
3231 <para>All parts of the system make heavy use of assertions and
3232 internal self-checks. They are permanently enabled, and we have no
3233 plans to disable them. If one of them breaks, please mail us!</para>
3235 <para>If you get an assertion failure
3236 in <filename>m_mallocfree.c</filename>, this may have happened because
3237 your program wrote off the end of a heap block, or before its
3238 beginning, thus corrupting heap metadata. Valgrind hopefully will have
3239 emitted a message to that effect before dying in this way.</para>
3241 <para>Read the <xref linkend="FAQ"/> for more advice about common problems,
3242 crashes, etc.</para>
3248 <sect1 id="manual-core.limits" xreflabel="Limitations">
3249 <title>Limitations</title>
3251 <para>The following list of limitations seems long. However, most
3252 programs actually work fine.</para>
3254 <para>Valgrind will run programs on the supported platforms
3255 subject to the following constraints:</para>
3259 <para>On Linux, Valgrind determines at startup the size of the 'brk
3260 segment' using the RLIMIT_DATA rlim_cur, with a minimum of 1 MB and
3261 a maximum of 8 MB. Valgrind outputs a message each time a program
3262 tries to extend the brk segment beyond the size determined at
3263 startup. Most programs will work properly with this limit,
3264 typically by switching to the use of mmap to get more memory.
3265 If your program really needs a big brk segment, you must change
3266 the 8 MB hardcoded limit and recompile Valgrind.
3271 <para>On x86 and amd64, there is no support for 3DNow!
3272 instructions. If the translator encounters these, Valgrind will
3273 generate a SIGILL when the instruction is executed. Apart from
3274 that, on x86 and amd64, essentially all instructions are supported,
3275 up to and including AVX and AES in 64-bit mode and SSSE3 in 32-bit
3276 mode. 32-bit mode does in fact support the bare minimum SSE4
3277 instructions needed to run programs on MacOSX 10.6 on 32-bit
3283 <para>On ppc32 and ppc64, almost all integer, floating point and
3284 Altivec instructions are supported. Specifically: integer and FP
3285 insns that are mandatory for PowerPC, the "General-purpose
3286 optional" group (fsqrt, fsqrts, stfiwx), the "Graphics optional"
3287 group (fre, fres, frsqrte, frsqrtes), and the Altivec (also known
3288 as VMX) SIMD instruction set, are supported. Also, instructions
3289 from the Power ISA 2.05 specification, as present in POWER6 CPUs,
3290 are supported.</para>
3294 <para>On ARM, essentially the entire ARMv7-A instruction set
3295 is supported, in both ARM and Thumb mode. ThumbEE and Jazelle are
3296 not supported. NEON, VFPv3 and ARMv6 media support is fairly
3302 <para>If your program does its own memory management, rather than
3303 using malloc/new/free/delete, it should still work, but Memcheck's
3304 error checking won't be so effective. If you describe your
3305 program's memory management scheme using "client requests" (see
3306 <xref linkend="manual-core-adv.clientreq"/>), Memcheck can do
3307 better. Nevertheless, using malloc/new and free/delete is still
3308 the best approach.</para>
3312 <para>Valgrind's signal simulation is not as robust as it could be.
3313 Basic POSIX-compliant sigaction and sigprocmask functionality is
3314 supplied, but it's conceivable that things could go badly awry if you
3315 do weird things with signals. Workaround: don't. Programs that do
3316 non-POSIX signal tricks are in any case inherently unportable, so
3317 should be avoided if possible.</para>
3321 <para>Machine instructions, and system calls, have been implemented
3322 on demand. So it's possible, although unlikely, that a program will
3323 fall over with a message to that effect. If this happens, please
3324 report all the details printed out, so we can try and implement the
3325 missing feature.</para>
3329 <para>Memory consumption of your program is majorly increased
3330 whilst running under Valgrind's Memcheck tool. This is due to the
3331 large amount of administrative information maintained behind the
3332 scenes. Another cause is that Valgrind dynamically translates the
3333 original executable. Translated, instrumented code is 12-18 times
3334 larger than the original so you can easily end up with 150+ MB of
3335 translations when running (eg) a web browser.</para>
3339 <para>Valgrind can handle dynamically-generated code just fine. If
3340 you regenerate code over the top of old code (ie. at the same
3341 memory addresses), if the code is on the stack Valgrind will
3342 realise the code has changed, and work correctly. This is
3343 necessary to handle the trampolines GCC uses to implemented nested
3344 functions. If you regenerate code somewhere other than the stack,
3345 and you are running on an 32- or 64-bit x86 CPU, you will need to
3346 use the <option>--smc-check=all</option> option, and Valgrind will
3347 run more slowly than normal. Or you can add client requests that
3348 tell Valgrind when your program has overwritten code.
3350 <para> On other platforms (ARM, PowerPC) Valgrind observes and
3351 honours the cache invalidation hints that programs are obliged to
3352 emit to notify new code, and so self-modifying-code support should
3353 work automatically, without the need
3354 for <option>--smc-check=all</option>.</para>
3358 <para>Valgrind has the following limitations
3359 in its implementation of x86/AMD64 floating point relative to
3362 <para>Precision: There is no support for 80 bit arithmetic.
3363 Internally, Valgrind represents all such "long double" numbers in 64
3364 bits, and so there may be some differences in results. Whether or
3365 not this is critical remains to be seen. Note, the x86/amd64
3366 fldt/fstpt instructions (read/write 80-bit numbers) are correctly
3367 simulated, using conversions to/from 64 bits, so that in-memory
3368 images of 80-bit numbers look correct if anyone wants to see.</para>
3370 <para>The impression observed from many FP regression tests is that
3371 the accuracy differences aren't significant. Generally speaking, if
3372 a program relies on 80-bit precision, there may be difficulties
3373 porting it to non x86/amd64 platforms which only support 64-bit FP
3374 precision. Even on x86/amd64, the program may get different results
3375 depending on whether it is compiled to use SSE2 instructions (64-bits
3376 only), or x87 instructions (80-bit). The net effect is to make FP
3377 programs behave as if they had been run on a machine with 64-bit IEEE
3378 floats, for example PowerPC. On amd64 FP arithmetic is done by
3379 default on SSE2, so amd64 looks more like PowerPC than x86 from an FP
3380 perspective, and there are far fewer noticeable accuracy differences
3381 than with x86.</para>
3383 <para>Rounding: Valgrind does observe the 4 IEEE-mandated rounding
3384 modes (to nearest, to +infinity, to -infinity, to zero) for the
3385 following conversions: float to integer, integer to float where
3386 there is a possibility of loss of precision, and float-to-float
3387 rounding. For all other FP operations, only the IEEE default mode
3388 (round to nearest) is supported.</para>
3390 <para>Numeric exceptions in FP code: IEEE754 defines five types of
3391 numeric exception that can happen: invalid operation (sqrt of
3392 negative number, etc), division by zero, overflow, underflow,
3393 inexact (loss of precision).</para>
3395 <para>For each exception, two courses of action are defined by IEEE754:
3396 either (1) a user-defined exception handler may be called, or (2) a
3397 default action is defined, which "fixes things up" and allows the
3398 computation to proceed without throwing an exception.</para>
3400 <para>Currently Valgrind only supports the default fixup actions.
3401 Again, feedback on the importance of exception support would be
3404 <para>When Valgrind detects that the program is trying to exceed any
3405 of these limitations (setting exception handlers, rounding mode, or
3406 precision control), it can print a message giving a traceback of
3407 where this has happened, and continue execution. This behaviour used
3408 to be the default, but the messages are annoying and so showing them
3409 is now disabled by default. Use <option>--show-emwarns=yes</option> to see
3412 <para>The above limitations define precisely the IEEE754 'default'
3413 behaviour: default fixup on all exceptions, round-to-nearest
3414 operations, and 64-bit precision.</para>
3418 <para>Valgrind has the following limitations in
3419 its implementation of x86/AMD64 SSE2 FP arithmetic, relative to
3422 <para>Essentially the same: no exceptions, and limited observance of
3423 rounding mode. Also, SSE2 has control bits which make it treat
3424 denormalised numbers as zero (DAZ) and a related action, flush
3425 denormals to zero (FTZ). Both of these cause SSE2 arithmetic to be
3426 less accurate than IEEE requires. Valgrind detects, ignores, and can
3427 warn about, attempts to enable either mode.</para>
3431 <para>Valgrind has the following limitations in
3432 its implementation of ARM VFPv3 arithmetic, relative to
3435 <para>Essentially the same: no exceptions, and limited observance
3436 of rounding mode. Also, switching the VFP unit into vector mode
3437 will cause Valgrind to abort the program -- it has no way to
3438 emulate vector uses of VFP at a reasonable performance level. This
3439 is no big deal given that non-scalar uses of VFP instructions are
3440 in any case deprecated.</para>
3444 <para>Valgrind has the following limitations
3445 in its implementation of PPC32 and PPC64 floating point
3446 arithmetic, relative to IEEE754.</para>
3448 <para>Scalar (non-Altivec): Valgrind provides a bit-exact emulation of
3449 all floating point instructions, except for "fre" and "fres", which are
3450 done more precisely than required by the PowerPC architecture specification.
3451 All floating point operations observe the current rounding mode.
3454 <para>However, fpscr[FPRF] is not set after each operation. That could
3455 be done but would give measurable performance overheads, and so far
3456 no need for it has been found.</para>
3458 <para>As on x86/AMD64, IEEE754 exceptions are not supported: all floating
3459 point exceptions are handled using the default IEEE fixup actions.
3460 Valgrind detects, ignores, and can warn about, attempts to unmask
3461 the 5 IEEE FP exception kinds by writing to the floating-point status
3462 and control register (fpscr).
3465 <para>Vector (Altivec, VMX): essentially as with x86/AMD64 SSE/SSE2:
3466 no exceptions, and limited observance of rounding mode.
3467 For Altivec, FP arithmetic
3468 is done in IEEE/Java mode, which is more accurate than the Linux default
3469 setting. "More accurate" means that denormals are handled properly,
3470 rather than simply being flushed to zero.</para>
3474 <para>Programs which are known not to work are:</para>
3477 <para>emacs starts up but immediately concludes it is out of
3478 memory and aborts. It may be that Memcheck does not provide
3479 a good enough emulation of the
3480 <computeroutput>mallinfo</computeroutput> function.
3481 Emacs works fine if you build it to use
3482 the standard malloc/free routines.</para>
3489 <sect1 id="manual-core.example" xreflabel="An Example Run">
3490 <title>An Example Run</title>
3492 <para>This is the log for a run of a small program using Memcheck.
3493 The program is in fact correct, and the reported error is as the
3494 result of a potentially serious code generation bug in GNU g++
3495 (snapshot 20010527).</para>
3497 <programlisting><![CDATA[
3498 sewardj@phoenix:~/newmat10$ ~/Valgrind-6/valgrind -v ./bogon
3499 ==25832== Valgrind 0.10, a memory error detector for x86 RedHat 7.1.
3500 ==25832== Copyright (C) 2000-2001, and GNU GPL'd, by Julian Seward.
3501 ==25832== Startup, with flags:
3502 ==25832== --suppressions=/home/sewardj/Valgrind/redhat71.supp
3503 ==25832== reading syms from /lib/ld-linux.so.2
3504 ==25832== reading syms from /lib/libc.so.6
3505 ==25832== reading syms from /mnt/pima/jrs/Inst/lib/libgcc_s.so.0
3506 ==25832== reading syms from /lib/libm.so.6
3507 ==25832== reading syms from /mnt/pima/jrs/Inst/lib/libstdc++.so.3
3508 ==25832== reading syms from /home/sewardj/Valgrind/valgrind.so
3509 ==25832== reading syms from /proc/self/exe
3511 ==25832== Invalid read of size 4
3512 ==25832== at 0x8048724: BandMatrix::ReSize(int,int,int) (bogon.cpp:45)
3513 ==25832== by 0x80487AF: main (bogon.cpp:66)
3514 ==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd
3516 ==25832== ERROR SUMMARY: 1 errors from 1 contexts (suppressed: 0 from 0)
3517 ==25832== malloc/free: in use at exit: 0 bytes in 0 blocks.
3518 ==25832== malloc/free: 0 allocs, 0 frees, 0 bytes allocated.
3519 ==25832== For a detailed leak analysis, rerun with: --leak-check=yes
3520 ]]></programlisting>
3522 <para>The GCC folks fixed this about a week before GCC 3.0
3528 <sect1 id="manual-core.warnings" xreflabel="Warning Messages">
3529 <title>Warning Messages You Might See</title>
3531 <para>Some of these only appear if you run in verbose mode
3532 (enabled by <option>-v</option>):</para>
3537 <para><computeroutput>More than 100 errors detected. Subsequent
3538 errors will still be recorded, but in less detail than
3539 before.</computeroutput></para>
3541 <para>After 100 different errors have been shown, Valgrind becomes
3542 more conservative about collecting them. It then requires only the
3543 program counters in the top two stack frames to match when deciding
3544 whether or not two errors are really the same one. Prior to this
3545 point, the PCs in the top four frames are required to match. This
3546 hack has the effect of slowing down the appearance of new errors
3547 after the first 100. The 100 constant can be changed by recompiling
3552 <para><computeroutput>More than 1000 errors detected. I'm not
3553 reporting any more. Final error counts may be inaccurate. Go fix
3554 your program!</computeroutput></para>
3556 <para>After 1000 different errors have been detected, Valgrind
3557 ignores any more. It seems unlikely that collecting even more
3558 different ones would be of practical help to anybody, and it avoids
3559 the danger that Valgrind spends more and more of its time comparing
3560 new errors against an ever-growing collection. As above, the 1000
3561 number is a compile-time constant.</para>
3565 <para><computeroutput>Warning: client switching stacks?</computeroutput></para>
3567 <para>Valgrind spotted such a large change in the stack pointer
3568 that it guesses the client is switching to a different stack. At
3569 this point it makes a kludgey guess where the base of the new
3570 stack is, and sets memory permissions accordingly. At the moment
3571 "large change" is defined as a change of more that 2000000 in the
3572 value of the stack pointer register. If Valgrind guesses wrong,
3573 you may get many bogus error messages following this and/or have
3574 crashes in the stack trace recording code. You might avoid these
3575 problems by informing Valgrind about the stack bounds using
3576 VALGRIND_STACK_REGISTER client request. </para>
3581 <para><computeroutput>Warning: client attempted to close Valgrind's
3582 logfile fd <number></computeroutput></para>
3584 <para>Valgrind doesn't allow the client to close the logfile,
3585 because you'd never see any diagnostic information after that point.
3586 If you see this message, you may want to use the
3587 <option>--log-fd=<number></option> option to specify a
3588 different logfile file-descriptor number.</para>
3592 <para><computeroutput>Warning: noted but unhandled ioctl
3593 <number></computeroutput></para>
3595 <para>Valgrind observed a call to one of the vast family of
3596 <computeroutput>ioctl</computeroutput> system calls, but did not
3597 modify its memory status info (because nobody has yet written a
3598 suitable wrapper). The call will still have gone through, but you may get
3599 spurious errors after this as a result of the non-update of the
3604 <para><computeroutput>Warning: set address range perms: large range
3605 <number></computeroutput></para>
3607 <para>Diagnostic message, mostly for benefit of the Valgrind
3608 developers, to do with memory permissions.</para>