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