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