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 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 10 | <para>This section describes the Valgrind core services, flags and |
| 11 | behaviours. That means it is relevant regardless of what particular |
| 12 | tool you are using. A point of terminology: most references to |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 13 | "Valgrind" in the rest of this section refer to the Valgrind |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 14 | core services.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 15 | |
| 16 | <sect1 id="manual-core.whatdoes" |
| 17 | xreflabel="What Valgrind does with your program"> |
| 18 | <title>What Valgrind does with your program</title> |
| 19 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 20 | <para>Valgrind is designed to be as non-intrusive as possible. It works |
| 21 | directly with existing executables. You don't need to recompile, relink, |
| 22 | or otherwise modify, the program to be checked.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 23 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 24 | <para>Simply put |
| 25 | <computeroutput>valgrind --tool=tool_name</computeroutput> |
| 26 | at the start of the command line normally used to run the program. For |
| 27 | example, if want to run the command |
| 28 | <computeroutput>ls -l</computeroutput> using the heavyweight |
| 29 | memory-checking tool Memcheck, issue the command:</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 30 | |
| 31 | <programlisting><![CDATA[ |
| 32 | valgrind --tool=memcheck ls -l]]></programlisting> |
| 33 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 34 | <para>Memcheck is the default, so if you want to use it you can |
| 35 | omit the <option>--tool</option> flag.</para> |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 36 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 37 | <para>Regardless of which tool is in use, Valgrind takes control of your |
| 38 | program before it starts. Debugging information is read from the |
| 39 | executable and associated libraries, so that error messages and other |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 40 | outputs can be phrased in terms of source code locations, when |
| 41 | appropriate.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 42 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 43 | <para>Your program is then run on a synthetic CPU provided by the |
| 44 | Valgrind core. As new code is executed for the first time, the core |
| 45 | hands the code to the selected tool. The tool adds its own |
| 46 | instrumentation code to this and hands the result back to the core, |
| 47 | which coordinates the continued execution of this instrumented |
| 48 | code.</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>The amount of instrumentation code added varies widely between |
| 51 | tools. At one end of the scale, Memcheck adds code to check every |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 52 | memory access and every value computed, |
| 53 | making it run 10-50 times slower than natively. |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 54 | At the other end of the spectrum, the ultra-trivial "none" tool |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 55 | (also referred to as Nulgrind) adds no instrumentation at all |
| 56 | and causes in total |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 57 | "only" about a 4 times slowdown.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 58 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 59 | <para>Valgrind simulates every single instruction your program executes. |
| 60 | Because of this, the active tool checks, or profiles, not only the code |
| 61 | in your application but also in all supporting dynamically-linked |
| 62 | (<computeroutput>.so</computeroutput>-format) libraries, including the |
| 63 | GNU C library, the X client libraries, Qt, if you work with KDE, and so |
| 64 | on.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 65 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 66 | <para>If you're using an error-detection tool, Valgrind may |
| 67 | detect errors in libraries, for example the GNU C or X11 |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 68 | libraries, which you have to use. You might not be interested in these |
| 69 | errors, since you probably have no control over that code. Therefore, |
| 70 | Valgrind allows you to selectively suppress errors, by recording them in |
| 71 | a suppressions file which is read when Valgrind starts up. The build |
| 72 | mechanism attempts to select suppressions which give reasonable |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 73 | behaviour for the C library |
| 74 | and X11 client library versions detected on your machine. |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 75 | To make it easier to write suppressions, you can use the |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 76 | <option>--gen-suppressions=yes</option> option. This tells Valgrind to |
| 77 | print out a suppression for each reported error, which you can then |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 78 | copy into a suppressions file.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 79 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 80 | <para>Different error-checking tools report different kinds of errors. |
| 81 | The suppression mechanism therefore allows you to say which tool or |
| 82 | tool(s) each suppression applies to.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 83 | |
| 84 | </sect1> |
| 85 | |
| 86 | |
| 87 | <sect1 id="manual-core.started" xreflabel="Getting started"> |
| 88 | <title>Getting started</title> |
| 89 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 90 | <para>First off, consider whether it might be beneficial to recompile |
| 91 | your application and supporting libraries with debugging info enabled |
| 92 | (the <option>-g</option> flag). Without debugging info, the best |
| 93 | Valgrind tools will be able to do is guess which function a particular |
| 94 | piece of code belongs to, which makes both error messages and profiling |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 95 | output nearly useless. With <option>-g</option>, you'll get |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 96 | messages which point directly to the relevant source code lines.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 97 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 98 | <para>Another flag you might like to consider, if you are working with |
| 99 | C++, is <option>-fno-inline</option>. That makes it easier to see the |
| 100 | function-call chain, which can help reduce confusion when navigating |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 101 | around large C++ apps. For example, debugging |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 102 | OpenOffice.org with Memcheck is a bit easier when using this flag. You |
| 103 | don't have to do this, but doing so helps Valgrind produce more accurate |
| 104 | and less confusing error reports. Chances are you're set up like this |
| 105 | already, if you intended to debug your program with GNU gdb, or some |
| 106 | other debugger.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 107 | |
njn | 3d92f9c | 2007-10-17 22:29:08 +0000 | [diff] [blame^] | 108 | <para>If you are planning to use Memcheck: On rare |
| 109 | occasions, compiler optimisations (at <computeroutput>-O2</computeroutput> |
| 110 | and above, and sometimes <computeroutput>-O1</computeroutput>) have been |
| 111 | observed to generate code which fools Memcheck into wrongly reporting |
| 112 | uninitialised value errors, or missing uninitialised value errors. We have |
| 113 | looked in detail into fixing this, and unfortunately the result is that |
| 114 | doing so would give a further significant slowdown in what is already a slow |
| 115 | tool. So the best solution is to turn off optimisation altogether. Since |
| 116 | this often makes things unmanagably slow, a reasonable compromise is to use |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 117 | <computeroutput>-O</computeroutput>. This gets you the majority of the |
njn | 3d92f9c | 2007-10-17 22:29:08 +0000 | [diff] [blame^] | 118 | benefits of higher optimisation levels whilst keeping relatively small the |
| 119 | chances of false positives or false negatives from Memcheck. All other |
| 120 | tools (as far as we know) are unaffected by optimisation level.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 121 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 122 | <para>Valgrind understands both the older "stabs" debugging format, used |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 123 | by gcc versions prior to 3.1, and the newer DWARF2 and DWARF3 formats |
| 124 | used by gcc |
| 125 | 3.1 and later. We continue to develop our debug-info readers, |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 126 | although the majority of effort will naturally enough go into the newer |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 127 | DWARF2/3 reader.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 128 | |
| 129 | <para>When you're ready to roll, just run your application as you |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 130 | would normally, but place |
| 131 | <computeroutput>valgrind --tool=tool_name</computeroutput> in front of |
| 132 | your usual command-line invocation. Note that you should run the real |
| 133 | (machine-code) executable here. If your application is started by, for |
| 134 | example, a shell or perl script, you'll need to modify it to invoke |
| 135 | Valgrind on the real executables. Running such scripts directly under |
| 136 | Valgrind will result in you getting error reports pertaining to |
| 137 | <computeroutput>/bin/sh</computeroutput>, |
| 138 | <computeroutput>/usr/bin/perl</computeroutput>, or whatever interpreter |
| 139 | you're using. This may not be what you want and can be confusing. You |
| 140 | can force the issue by giving the flag |
| 141 | <option>--trace-children=yes</option>, but confusion is still |
| 142 | likely.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 143 | |
| 144 | </sect1> |
| 145 | |
| 146 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 147 | <sect1 id="manual-core.comment" xreflabel="The Commentary"> |
| 148 | <title>The Commentary</title> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 149 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 150 | <para>Valgrind tools write a commentary, a stream of text, detailing |
| 151 | error reports and other significant events. All lines in the commentary |
| 152 | have following form: |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 153 | |
| 154 | <programlisting><![CDATA[ |
| 155 | ==12345== some-message-from-Valgrind]]></programlisting> |
| 156 | </para> |
| 157 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 158 | <para>The <computeroutput>12345</computeroutput> is the process ID. |
| 159 | This scheme makes it easy to distinguish program output from Valgrind |
| 160 | commentary, and also easy to differentiate commentaries from different |
| 161 | processes which have become merged together, for whatever reason.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 162 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 163 | <para>By default, Valgrind tools write only essential messages to the |
| 164 | commentary, so as to avoid flooding you with information of secondary |
| 165 | importance. If you want more information about what is happening, |
| 166 | re-run, passing the <option>-v</option> flag to Valgrind. A second |
| 167 | <option>-v</option> gives yet more detail. |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 168 | </para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 169 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 170 | <para>You can direct the commentary to three different places:</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 171 | |
| 172 | <orderedlist> |
| 173 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 174 | <listitem id="manual-core.out2fd" xreflabel="Directing output to fd"> |
| 175 | <para>The default: send it to a file descriptor, which is by default |
| 176 | 2 (stderr). So, if you give the core no options, it will write |
| 177 | commentary to the standard error stream. If you want to send it to |
| 178 | some other file descriptor, for example number 9, you can specify |
| 179 | <option>--log-fd=9</option>.</para> |
| 180 | |
| 181 | <para>This is the simplest and most common arrangement, but can |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 182 | cause problems when Valgrinding entire trees of processes which |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 183 | expect specific file descriptors, particularly stdin/stdout/stderr, |
| 184 | to be available for their own use.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 185 | </listitem> |
| 186 | |
| 187 | <listitem id="manual-core.out2file" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 188 | xreflabel="Directing output to file"> <para>A less intrusive |
| 189 | option is to write the commentary to a file, which you specify by |
| 190 | <option>--log-file=filename</option>. Note carefully that the |
| 191 | commentary is <command>not</command> written to the file you |
| 192 | specify, but instead to one called |
| 193 | <filename>filename.12345</filename>, if for example the pid of the |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 194 | traced process is 12345. This is helpful when Valgrinding a whole |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 195 | tree of processes at once, since it means that each process writes |
| 196 | to its own logfile, rather than the result being jumbled up in one |
| 197 | big logfile. If <filename>filename.12345</filename> already exists, |
| 198 | then it will name new files <filename>filename.12345.1</filename> |
| 199 | and so on.</para> |
sewardj | 603d410 | 2005-01-11 14:01:02 +0000 | [diff] [blame] | 200 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 201 | <para>If you want to specify precisely the file name to use, without |
| 202 | the trailing <computeroutput>.12345</computeroutput> part, you can |
| 203 | instead use <option>--log-file-exactly=filename</option>.</para> |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 204 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 205 | <para>You can also use the |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 206 | <option>--log-file-qualifier=<VAR></option> option to |
| 207 | incorporate into the filename the contents of environment variable |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 208 | <varname>VAR</varname>. This is rarely needed, but very useful in |
| 209 | certain circumstances (eg. when running MPI programs). In this |
| 210 | case, the trailing <computeroutput>.12345</computeroutput> part is |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 211 | replaced by (the contents of) <varname>$VAR</varname>. The idea is |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 212 | that you specify a variable which will be set differently for each |
| 213 | process in the job, for example |
| 214 | <computeroutput>BPROC_RANK</computeroutput> or whatever is |
| 215 | applicable in your MPI setup.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 216 | </listitem> |
| 217 | |
| 218 | <listitem id="manual-core.out2socket" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 219 | xreflabel="Directing output to network socket"> <para>The |
| 220 | least intrusive option is to send the commentary to a network |
| 221 | socket. The socket is specified as an IP address and port number |
| 222 | pair, like this: <option>--log-socket=192.168.0.1:12345</option> if |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 223 | you want to send the output to host IP 192.168.0.1 port 12345 |
| 224 | (note: we |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 225 | have no idea if 12345 is a port of pre-existing significance). You |
| 226 | can also omit the port number: |
| 227 | <option>--log-socket=192.168.0.1</option>, in which case a default |
| 228 | port of 1500 is used. This default is defined by the constant |
| 229 | <computeroutput>VG_CLO_DEFAULT_LOGPORT</computeroutput> in the |
| 230 | sources.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 231 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 232 | <para>Note, unfortunately, that you have to use an IP address here, |
| 233 | rather than a hostname.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 234 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 235 | <para>Writing to a network socket is pointless if you don't |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 236 | have something listening at the other end. We provide a simple |
| 237 | listener program, |
| 238 | <computeroutput>valgrind-listener</computeroutput>, which accepts |
| 239 | connections on the specified port and copies whatever it is sent to |
| 240 | stdout. Probably someone will tell us this is a horrible security |
| 241 | risk. It seems likely that people will write more sophisticated |
| 242 | listeners in the fullness of time.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 243 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 244 | <para>valgrind-listener can accept simultaneous connections from up |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 245 | to 50 Valgrinded processes. In front of each line of output it |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 246 | prints the current number of active connections in round |
| 247 | brackets.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 248 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 249 | <para>valgrind-listener accepts two command-line flags:</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 250 | <itemizedlist> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 251 | <listitem> |
| 252 | <para><option>-e</option> or <option>--exit-at-zero</option>: |
| 253 | when the number of connected processes falls back to zero, |
| 254 | exit. Without this, it will run forever, that is, until you |
| 255 | send it Control-C.</para> |
| 256 | </listitem> |
| 257 | <listitem> |
| 258 | <para><option>portnumber</option>: changes the port it listens |
| 259 | on from the default (1500). The specified port must be in the |
| 260 | range 1024 to 65535. The same restriction applies to port |
| 261 | numbers specified by a <option>--log-socket</option> to |
| 262 | Valgrind itself.</para> |
| 263 | </listitem> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 264 | </itemizedlist> |
| 265 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 266 | <para>If a Valgrinded process fails to connect to a listener, for |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 267 | whatever reason (the listener isn't running, invalid or unreachable |
| 268 | host or port, etc), Valgrind switches back to writing the commentary |
| 269 | to stderr. The same goes for any process which loses an established |
| 270 | connection to a listener. In other words, killing the listener |
| 271 | doesn't kill the processes sending data to it.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 272 | </listitem> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 273 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 274 | </orderedlist> |
| 275 | |
| 276 | <para>Here is an important point about the relationship between the |
| 277 | commentary and profiling output from tools. The commentary contains a |
| 278 | mix of messages from the Valgrind core and the selected tool. If the |
| 279 | tool reports errors, it will report them to the commentary. However, if |
| 280 | the tool does profiling, the profile data will be written to a file of |
| 281 | some kind, depending on the tool, and independent of what |
| 282 | <option>--log-*</option> options are in force. The commentary is |
| 283 | intended to be a low-bandwidth, human-readable channel. Profiling data, |
| 284 | on the other hand, is usually voluminous and not meaningful without |
| 285 | further processing, which is why we have chosen this arrangement.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 286 | |
| 287 | </sect1> |
| 288 | |
| 289 | |
| 290 | <sect1 id="manual-core.report" xreflabel="Reporting of errors"> |
| 291 | <title>Reporting of errors</title> |
| 292 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 293 | <para>When an error-checking tool |
| 294 | detects something bad happening in the program, an error |
| 295 | message is written to the commentary. Here's an example from Memcheck:</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 296 | |
| 297 | <programlisting><![CDATA[ |
| 298 | ==25832== Invalid read of size 4 |
| 299 | ==25832== at 0x8048724: BandMatrix::ReSize(int, int, int) (bogon.cpp:45) |
| 300 | ==25832== by 0x80487AF: main (bogon.cpp:66) |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 301 | ==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd]]></programlisting> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 302 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 303 | <para>This message says that the program did an illegal 4-byte read of |
| 304 | address 0xBFFFF74C, which, as far as Memcheck can tell, is not a valid |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 305 | stack address, nor corresponds to any current malloc'd or free'd |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 306 | blocks. The read is happening at line 45 of |
| 307 | <filename>bogon.cpp</filename>, called from line 66 of the same file, |
| 308 | etc. For errors associated with an identified malloc'd/free'd block, |
| 309 | for example reading free'd memory, Valgrind reports not only the |
| 310 | location where the error happened, but also where the associated block |
| 311 | was malloc'd/free'd.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 312 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 313 | <para>Valgrind remembers all error reports. When an error is detected, |
| 314 | it is compared against old reports, to see if it is a duplicate. If so, |
| 315 | the error is noted, but no further commentary is emitted. This avoids |
| 316 | you being swamped with bazillions of duplicate error reports.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 317 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 318 | <para>If you want to know how many times each error occurred, run with |
| 319 | the <option>-v</option> option. When execution finishes, all the |
| 320 | reports are printed out, along with, and sorted by, their occurrence |
| 321 | counts. This makes it easy to see which errors have occurred most |
| 322 | frequently.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 323 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 324 | <para>Errors are reported before the associated operation actually |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 325 | happens. If you're using a tool (eg. Memcheck) which does |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 326 | address checking, and your program attempts to read from address zero, |
| 327 | the tool will emit a message to this effect, and the program will then |
| 328 | duly die with a segmentation fault.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 329 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 330 | <para>In general, you should try and fix errors in the order that they |
| 331 | are reported. Not doing so can be confusing. For example, a program |
| 332 | which copies uninitialised values to several memory locations, and later |
| 333 | uses them, will generate several error messages, when run on Memcheck. |
| 334 | The first such error message may well give the most direct clue to the |
| 335 | root cause of the problem.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 336 | |
| 337 | <para>The process of detecting duplicate errors is quite an |
| 338 | expensive one and can become a significant performance overhead |
| 339 | if your program generates huge quantities of errors. To avoid |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 340 | serious problems, Valgrind will simply stop collecting |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 341 | 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] | 342 | in total have been seen. In this situation you might as well |
| 343 | stop your program and fix it, because Valgrind won't tell you |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 344 | 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] | 345 | apply after suppressed errors are removed. These limits are |
njn | c7561b9 | 2005-06-19 01:24:32 +0000 | [diff] [blame] | 346 | defined in <filename>m_errormgr.c</filename> and can be increased |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 347 | if necessary.</para> |
| 348 | |
| 349 | <para>To avoid this cutoff you can use the |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 350 | <option>--error-limit=no</option> flag. Then Valgrind will always show |
| 351 | errors, regardless of how many there are. Use this flag carefully, |
| 352 | since it may have a bad effect on performance.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 353 | |
| 354 | </sect1> |
| 355 | |
| 356 | |
| 357 | <sect1 id="manual-core.suppress" xreflabel="Suppressing errors"> |
| 358 | <title>Suppressing errors</title> |
| 359 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 360 | <para>The error-checking tools detect numerous problems in the base |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 361 | libraries, such as the GNU C library, and the X11 client libraries, |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 362 | which come pre-installed on your GNU/Linux system. You can't easily fix |
| 363 | these, but you don't want to see these errors (and yes, there are many!) |
| 364 | So Valgrind reads a list of errors to suppress at startup. A default |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 365 | suppression file is created by the |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 366 | <computeroutput>./configure</computeroutput> script when the system is |
| 367 | built.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 368 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 369 | <para>You can modify and add to the suppressions file at your leisure, |
| 370 | or, better, write your own. Multiple suppression files are allowed. |
| 371 | This is useful if part of your project contains errors you can't or |
| 372 | don't want to fix, yet you don't want to continuously be reminded of |
| 373 | them.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 374 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 375 | <formalpara><title>Note:</title> <para>By far the easiest way to add |
| 376 | suppressions is to use the <option>--gen-suppressions=yes</option> flag |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 377 | described in <xref linkend="manual-core.flags"/>.</para> |
| 378 | </formalpara> |
| 379 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 380 | <para>Each error to be suppressed is described very specifically, to |
| 381 | minimise the possibility that a suppression-directive inadvertantly |
| 382 | suppresses a bunch of similar errors which you did want to see. The |
| 383 | suppression mechanism is designed to allow precise yet flexible |
| 384 | specification of errors to suppress.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 385 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 386 | <para>If you use the <option>-v</option> flag, at the end of execution, |
| 387 | Valgrind prints out one line for each used suppression, giving its name |
| 388 | 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] | 389 | run of <computeroutput>valgrind --tool=memcheck ls -l</computeroutput>:</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 390 | |
| 391 | <programlisting><![CDATA[ |
| 392 | --27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getgrgid_r |
| 393 | --27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getpwuid_r |
| 394 | --27579-- supp: 6 strrchr/_dl_map_object_from_fd/_dl_map_object]]></programlisting> |
| 395 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 396 | <para>Multiple suppressions files are allowed. By default, Valgrind |
| 397 | uses <filename>$PREFIX/lib/valgrind/default.supp</filename>. You can |
| 398 | ask to add suppressions from another file, by specifying |
| 399 | <option>--suppressions=/path/to/file.supp</option>. |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 400 | </para> |
| 401 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 402 | <para>If you want to understand more about suppressions, look at an |
| 403 | existing suppressions file whilst reading the following documentation. |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 404 | The file <filename>glibc-2.3.supp</filename>, in the source |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 405 | distribution, provides some good examples.</para> |
| 406 | |
| 407 | <para>Each suppression has the following components:</para> |
| 408 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 409 | <itemizedlist> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 410 | |
| 411 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 412 | <para>First line: its name. This merely gives a handy name to the |
| 413 | suppression, by which it is referred to in the summary of used |
| 414 | suppressions printed out when a program finishes. It's not |
| 415 | important what the name is; any identifying string will do.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 416 | </listitem> |
| 417 | |
| 418 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 419 | <para>Second line: name of the tool(s) that the suppression is for |
| 420 | (if more than one, comma-separated), and the name of the suppression |
| 421 | itself, separated by a colon (Nb: no spaces are allowed), eg:</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 422 | <programlisting><![CDATA[ |
| 423 | tool_name1,tool_name2:suppression_name]]></programlisting> |
| 424 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 425 | <para>Recall that Valgrind is a modular system, in which |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 426 | different instrumentation tools can observe your program whilst it |
| 427 | is running. Since different tools detect different kinds of errors, |
| 428 | it is necessary to say which tool(s) the suppression is meaningful |
| 429 | to.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 430 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 431 | <para>Tools will complain, at startup, if a tool does not understand |
| 432 | any suppression directed to it. Tools ignore suppressions which are |
| 433 | not directed to them. As a result, it is quite practical to put |
| 434 | suppressions for all tools into the same suppression file.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 435 | </listitem> |
| 436 | |
| 437 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 438 | <para>Next line: a small number of suppression types have extra |
| 439 | information after the second line (eg. the <varname>Param</varname> |
| 440 | suppression for Memcheck)</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 441 | </listitem> |
| 442 | |
| 443 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 444 | <para>Remaining lines: This is the calling context for the error -- |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 445 | the chain of function calls that led to it. There can be up to 24 |
| 446 | of these lines.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 447 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 448 | <para>Locations may be either names of shared objects/executables or |
| 449 | wildcards matching function names. They begin |
| 450 | <computeroutput>obj:</computeroutput> and |
| 451 | <computeroutput>fun:</computeroutput> respectively. Function and |
| 452 | object names to match against may use the wildcard characters |
| 453 | <computeroutput>*</computeroutput> and |
| 454 | <computeroutput>?</computeroutput>.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 455 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 456 | <para><command>Important note: </command> C++ function names must be |
| 457 | <command>mangled</command>. If you are writing suppressions by |
| 458 | hand, use the <option>--demangle=no</option> option to get the |
| 459 | mangled names in your error messages.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 460 | </listitem> |
| 461 | |
| 462 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 463 | <para>Finally, the entire suppression must be between curly |
| 464 | braces. Each brace must be the first character on its own |
| 465 | line.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 466 | </listitem> |
| 467 | |
| 468 | </itemizedlist> |
| 469 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 470 | <para>A suppression only suppresses an error when the error matches all |
| 471 | the details in the suppression. Here's an example:</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 472 | |
| 473 | <programlisting><![CDATA[ |
| 474 | { |
| 475 | __gconv_transform_ascii_internal/__mbrtowc/mbtowc |
| 476 | Memcheck:Value4 |
| 477 | fun:__gconv_transform_ascii_internal |
| 478 | fun:__mbr*toc |
| 479 | fun:mbtowc |
| 480 | }]]></programlisting> |
| 481 | |
| 482 | |
| 483 | <para>What it means is: for Memcheck only, suppress a |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 484 | use-of-uninitialised-value error, when the data size is 4, when it |
| 485 | occurs in the function |
| 486 | <computeroutput>__gconv_transform_ascii_internal</computeroutput>, when |
| 487 | that is called from any function of name matching |
| 488 | <computeroutput>__mbr*toc</computeroutput>, when that is called from |
| 489 | <computeroutput>mbtowc</computeroutput>. It doesn't apply under any |
| 490 | other circumstances. The string by which this suppression is identified |
| 491 | to the user is |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 492 | <computeroutput>__gconv_transform_ascii_internal/__mbrtowc/mbtowc</computeroutput>.</para> |
| 493 | |
| 494 | <para>(See <xref linkend="mc-manual.suppfiles"/> for more details |
| 495 | on the specifics of Memcheck's suppression kinds.)</para> |
| 496 | |
| 497 | <para>Another example, again for the Memcheck tool:</para> |
| 498 | |
| 499 | <programlisting><![CDATA[ |
| 500 | { |
| 501 | libX11.so.6.2/libX11.so.6.2/libXaw.so.7.0 |
| 502 | Memcheck:Value4 |
| 503 | obj:/usr/X11R6/lib/libX11.so.6.2 |
| 504 | obj:/usr/X11R6/lib/libX11.so.6.2 |
| 505 | obj:/usr/X11R6/lib/libXaw.so.7.0 |
| 506 | }]]></programlisting> |
| 507 | |
| 508 | <para>Suppress any size 4 uninitialised-value error which occurs |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 509 | anywhere in <filename>libX11.so.6.2</filename>, when called from |
| 510 | anywhere in the same library, when called from anywhere in |
| 511 | <filename>libXaw.so.7.0</filename>. The inexact specification of |
| 512 | locations is regrettable, but is about all you can hope for, given that |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 513 | the X11 libraries shipped on the Linux distro on which this example |
| 514 | was made have had their symbol tables removed.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 515 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 516 | <para>Although the above two examples do not make this clear, you can |
| 517 | freely mix <computeroutput>obj:</computeroutput> and |
| 518 | <computeroutput>fun:</computeroutput> lines in a suppression.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 519 | |
| 520 | </sect1> |
| 521 | |
| 522 | |
| 523 | <sect1 id="manual-core.flags" |
| 524 | xreflabel="Command-line flags for the Valgrind core"> |
| 525 | <title>Command-line flags for the Valgrind core</title> |
| 526 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 527 | <para>As mentioned above, Valgrind's core accepts a common set of flags. |
| 528 | The tools also accept tool-specific flags, which are documented |
| 529 | seperately for each tool.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 530 | |
| 531 | <para>You invoke Valgrind like this:</para> |
| 532 | |
| 533 | <programlisting><![CDATA[ |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 534 | valgrind [valgrind-options] your-prog [your-prog-options]]]></programlisting> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 535 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 536 | <para>Valgrind's default settings succeed in giving reasonable behaviour |
| 537 | in most cases. We group the available options by rough |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 538 | categories.</para> |
| 539 | |
| 540 | <sect2 id="manual-core.toolopts" xreflabel="Tool-selection option"> |
| 541 | <title>Tool-selection option</title> |
| 542 | |
| 543 | <para>The single most important option.</para> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 544 | |
| 545 | <itemizedlist> |
| 546 | <listitem id="tool_name"> |
| 547 | <para><option>--tool=<name></option> [default=memcheck]</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 548 | <para>Run the Valgrind tool called <emphasis>name</emphasis>, |
njn | 1d0825f | 2006-03-27 11:37:07 +0000 | [diff] [blame] | 549 | e.g. Memcheck, Cachegrind, etc.</para> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 550 | </listitem> |
| 551 | </itemizedlist> |
| 552 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 553 | </sect2> |
| 554 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 555 | |
| 556 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 557 | <sect2 id="manual-core.basicopts" xreflabel="Basic Options"> |
| 558 | <title>Basic Options</title> |
| 559 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 560 | <!-- start of xi:include in the manpage --> |
| 561 | <para id="basic.opts.para">These options work with all tools.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 562 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 563 | <variablelist id="basic.opts.list"> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 564 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 565 | <varlistentry id="opt.help" xreflabel="--help"> |
| 566 | <term><option>-h --help</option></term> |
| 567 | <listitem> |
| 568 | <para>Show help for all options, both for the core and for the |
| 569 | selected tool.</para> |
| 570 | </listitem> |
| 571 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 572 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 573 | <varlistentry id="opt.help-debug" xreflabel="--help-debug"> |
| 574 | <term><option>--help-debug</option></term> |
| 575 | <listitem> |
| 576 | <para>Same as <option>--help</option>, but also lists debugging |
| 577 | options which usually are only of use to Valgrind's |
| 578 | developers.</para> |
| 579 | </listitem> |
| 580 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 581 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 582 | <varlistentry id="opt.version" xreflabel="--version"> |
| 583 | <term><option>--version</option></term> |
| 584 | <listitem> |
| 585 | <para>Show the version number of the Valgrind core. Tools can have |
| 586 | their own version numbers. There is a scheme in place to ensure |
| 587 | that tools only execute when the core version is one they are |
| 588 | known to work with. This was done to minimise the chances of |
| 589 | strange problems arising from tool-vs-core version |
| 590 | incompatibilities.</para> |
| 591 | </listitem> |
| 592 | </varlistentry> |
njn | 5127298 | 2005-07-25 23:18:44 +0000 | [diff] [blame] | 593 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 594 | <varlistentry id="opt.quiet" xreflabel="--quiet"> |
| 595 | <term><option>-q --quiet</option></term> |
| 596 | <listitem> |
| 597 | <para>Run silently, and only print error messages. Useful if you |
| 598 | are running regression tests or have some other automated test |
| 599 | machinery.</para> |
| 600 | </listitem> |
| 601 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 602 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 603 | <varlistentry id="opt.verbose" xreflabel="--verbose"> |
| 604 | <term><option>-v --verbose</option></term> |
| 605 | <listitem> |
| 606 | <para>Be more verbose. Gives extra information on various aspects |
| 607 | of your program, such as: the shared objects loaded, the |
| 608 | suppressions used, the progress of the instrumentation and |
| 609 | execution engines, and warnings about unusual behaviour. Repeating |
| 610 | the flag increases the verbosity level.</para> |
| 611 | </listitem> |
| 612 | </varlistentry> |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 613 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 614 | <varlistentry id="opt.d" xreflabel="-d"> |
| 615 | <term><option>-d</option></term> |
| 616 | <listitem> |
| 617 | <para>Emit information for debugging Valgrind itself. This is |
| 618 | usually only of interest to the Valgrind developers. Repeating |
| 619 | the flag produces more detailed output. If you want to send us a |
| 620 | bug report, a log of the output generated by |
| 621 | <option>-v -v -d -d</option> will make your report more |
| 622 | useful.</para> |
| 623 | </listitem> |
| 624 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 625 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 626 | <varlistentry id="opt.tool" xreflabel="--tool"> |
| 627 | <term> |
| 628 | <option><![CDATA[--tool=<toolname> [default: memcheck] ]]></option> |
| 629 | </term> |
| 630 | <listitem> |
| 631 | <para>Run the Valgrind tool called <varname>toolname</varname>, |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 632 | e.g. Memcheck, Cachegrind, etc.</para> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 633 | </listitem> |
| 634 | </varlistentry> |
njn | 5127298 | 2005-07-25 23:18:44 +0000 | [diff] [blame] | 635 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 636 | <varlistentry id="opt.trace-children" xreflabel="--trace-children"> |
| 637 | <term> |
| 638 | <option><![CDATA[--trace-children=<yes|no> [default: no] ]]></option> |
| 639 | </term> |
| 640 | <listitem> |
njn | ae44c38 | 2007-05-15 03:59:23 +0000 | [diff] [blame] | 641 | <para>When enabled, Valgrind will trace into sub-processes |
| 642 | initiated via the <varname>exec</varname> system call. This can be |
| 643 | confusing and isn't usually what you want, so it is disabled by |
| 644 | default. |
| 645 | </para> |
| 646 | <para>Note that Valgrind does trace into the child of a |
| 647 | <varname>fork</varname> (it would be difficult not too, since |
| 648 | <varname>fork</varname> makes an identical copy of a process), so this |
| 649 | option is arguably badly named. However, most children of |
| 650 | <varname>fork</varname> calls immediately call <varname>exec</varname> |
| 651 | anyway. |
| 652 | </para> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 653 | </listitem> |
| 654 | </varlistentry> |
njn | 5127298 | 2005-07-25 23:18:44 +0000 | [diff] [blame] | 655 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 656 | <varlistentry id="opt.track-fds" xreflabel="--track-fds"> |
| 657 | <term> |
| 658 | <option><![CDATA[--track-fds=<yes|no> [default: no] ]]></option> |
| 659 | </term> |
| 660 | <listitem> |
| 661 | <para>When enabled, Valgrind will print out a list of open file |
| 662 | descriptors on exit. Along with each file descriptor is printed a |
| 663 | stack backtrace of where the file was opened and any details |
| 664 | relating to the file descriptor such as the file name or socket |
| 665 | details.</para> |
| 666 | </listitem> |
| 667 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 668 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 669 | <varlistentry id="opt.time-stamp" xreflabel="--time-stamp"> |
| 670 | <term> |
| 671 | <option><![CDATA[--time-stamp=<yes|no> [default: no] ]]></option> |
| 672 | </term> |
| 673 | <listitem> |
| 674 | <para>When enabled, each message is preceded with an indication of |
| 675 | the elapsed wallclock time since startup, expressed as days, |
| 676 | hours, minutes, seconds and milliseconds.</para> |
| 677 | </listitem> |
| 678 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 679 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 680 | <varlistentry id="opt.log-fd" xreflabel="--log-fd"> |
| 681 | <term> |
| 682 | <option><![CDATA[--log-fd=<number> [default: 2, stderr] ]]></option> |
| 683 | </term> |
| 684 | <listitem> |
| 685 | <para>Specifies that Valgrind should send all of its messages to |
| 686 | the specified file descriptor. The default, 2, is the standard |
| 687 | error channel (stderr). Note that this may interfere with the |
| 688 | client's own use of stderr, as Valgrind's output will be |
| 689 | interleaved with any output that the client sends to |
| 690 | stderr.</para> |
| 691 | </listitem> |
| 692 | </varlistentry> |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 693 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 694 | <varlistentry id="opt.log-file" xreflabel="--log-file"> |
| 695 | <term> |
| 696 | <option><![CDATA[--log-file=<filename> ]]></option> |
| 697 | </term> |
| 698 | <listitem> |
| 699 | <para>Specifies that Valgrind should send all of its messages to |
| 700 | the specified file. In fact, the file name used is created by |
| 701 | concatenating the text <filename>filename</filename>, "." and the |
| 702 | process ID, (ie. <![CDATA[<filename>.<pid>]]>), so as to create a |
| 703 | file per process. The specified file name may not be the empty |
| 704 | string.</para> |
| 705 | </listitem> |
| 706 | </varlistentry> |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 707 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 708 | <varlistentry id="opt.log-file-exactly" xreflabel="--log-file-exactly"> |
| 709 | <term> |
| 710 | <option><![CDATA[--log-file-exactly=<filename> ]]></option> |
| 711 | </term> |
| 712 | <listitem> |
| 713 | <para>Just like <option>--log-file</option>, but the suffix |
njn | 498685c | 2007-09-17 23:15:35 +0000 | [diff] [blame] | 714 | <computeroutput>".pid"</computeroutput> is not added. WARNING: If you |
| 715 | use this option with <option>--trace-children=yes</option> and your |
| 716 | program invokes multiple processes, the Valgrind output from all those |
| 717 | processes will go into this one file, possibly jumbled up, and |
| 718 | possibly incomplete.</para> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 719 | </listitem> |
| 720 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 721 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 722 | <varlistentry id="opt.log-file-qualifier" xreflabel="--log-file-qualifier"> |
| 723 | <term> |
| 724 | <option><![CDATA[--log-file-qualifier=<VAR> ]]></option> |
| 725 | </term> |
| 726 | <listitem> |
| 727 | <para>When used in conjunction with <option>--log-file</option>, |
| 728 | causes the log file name to be qualified using the contents of the |
| 729 | environment variable <computeroutput>$VAR</computeroutput>. This |
| 730 | is useful when running MPI programs. For further details, see |
| 731 | <link linkend="manual-core.comment">Section 2.3 "The Commentary"</link> |
| 732 | in the manual. |
| 733 | </para> |
| 734 | </listitem> |
| 735 | </varlistentry> |
| 736 | |
| 737 | <varlistentry id="opt.log-socket" xreflabel="--log-socket"> |
| 738 | <term> |
| 739 | <option><![CDATA[--log-socket=<ip-address:port-number> ]]></option> |
| 740 | </term> |
| 741 | <listitem> |
| 742 | <para>Specifies that Valgrind should send all of its messages to |
| 743 | the specified port at the specified IP address. The port may be |
| 744 | omitted, in which case port 1500 is used. If a connection cannot |
| 745 | be made to the specified socket, Valgrind falls back to writing |
| 746 | output to the standard error (stderr). This option is intended to |
| 747 | be used in conjunction with the |
| 748 | <computeroutput>valgrind-listener</computeroutput> program. For |
| 749 | further details, see |
| 750 | <link linkend="manual-core.comment">Section 2.3 "The Commentary"</link> |
| 751 | in the manual.</para> |
| 752 | </listitem> |
| 753 | </varlistentry> |
| 754 | |
| 755 | </variablelist> |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 756 | <!-- end of xi:include in the manpage --> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 757 | |
| 758 | </sect2> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 759 | |
| 760 | |
| 761 | <sect2 id="manual-core.erropts" xreflabel="Error-related Options"> |
| 762 | <title>Error-related options</title> |
| 763 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 764 | <!-- start of xi:include in the manpage --> |
| 765 | <para id="error-related.opts.para">These options are used by all tools |
| 766 | that can report errors, e.g. Memcheck, but not Cachegrind.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 767 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 768 | <variablelist id="error-related.opts.list"> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 769 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 770 | <varlistentry id="opt.xml" xreflabel="--xml"> |
| 771 | <term> |
| 772 | <option><![CDATA[--xml=<yes|no> [default: no] ]]></option> |
| 773 | </term> |
| 774 | <listitem> |
| 775 | <para>When enabled, output will be in XML format. This is aimed |
| 776 | at making life easier for tools that consume Valgrind's output as |
| 777 | input, such as GUI front ends. Currently this option only works |
njn | ca54af3 | 2006-04-16 10:25:43 +0000 | [diff] [blame] | 778 | with Memcheck.</para> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 779 | </listitem> |
| 780 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 781 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 782 | <varlistentry id="opt.xml-user-comment" xreflabel="--xml-user-comment"> |
| 783 | <term> |
| 784 | <option><![CDATA[--xml-user-comment=<string> ]]></option> |
| 785 | </term> |
| 786 | <listitem> |
| 787 | <para>Embeds an extra user comment string at the start of the XML |
| 788 | output. Only works when <option>--xml=yes</option> is specified; |
| 789 | ignored otherwise.</para> |
| 790 | </listitem> |
| 791 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 792 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 793 | <varlistentry id="opt.demangle" xreflabel="--demangle"> |
| 794 | <term> |
| 795 | <option><![CDATA[--demangle=<yes|no> [default: yes] ]]></option> |
| 796 | </term> |
| 797 | <listitem> |
| 798 | <para>Enable/disable automatic demangling (decoding) of C++ names. |
| 799 | Enabled by default. When enabled, Valgrind will attempt to |
| 800 | translate encoded C++ names back to something approaching the |
| 801 | original. The demangler handles symbols mangled by g++ versions |
| 802 | 2.X, 3.X and 4.X.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 803 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 804 | <para>An important fact about demangling is that function names |
| 805 | mentioned in suppressions files should be in their mangled form. |
| 806 | Valgrind does not demangle function names when searching for |
| 807 | applicable suppressions, because to do otherwise would make |
| 808 | suppressions file contents dependent on the state of Valgrind's |
| 809 | demangling machinery, and would also be slow and pointless.</para> |
| 810 | </listitem> |
| 811 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 812 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 813 | <varlistentry id="opt.num-callers" xreflabel="--num-callers"> |
| 814 | <term> |
| 815 | <option><![CDATA[--num-callers=<number> [default: 12] ]]></option> |
| 816 | </term> |
| 817 | <listitem> |
| 818 | <para>By default, Valgrind shows twelve levels of function call |
| 819 | names to help you identify program locations. You can change that |
| 820 | number with this option. This can help in determining the |
| 821 | program's location in deeply-nested call chains. Note that errors |
| 822 | are commoned up using only the top four function locations (the |
| 823 | place in the current function, and that of its three immediate |
| 824 | callers). So this doesn't affect the total number of errors |
| 825 | reported.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 826 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 827 | <para>The maximum value for this is 50. Note that higher settings |
| 828 | will make Valgrind run a bit more slowly and take a bit more |
| 829 | memory, but can be useful when working with programs with |
| 830 | deeply-nested call chains.</para> |
| 831 | </listitem> |
| 832 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 833 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 834 | <varlistentry id="opt.error-limit" xreflabel="--error-limit"> |
| 835 | <term> |
| 836 | <option><![CDATA[--error-limit=<yes|no> [default: yes] ]]></option> |
| 837 | </term> |
| 838 | <listitem> |
sewardj | 5850108 | 2006-05-12 23:35:10 +0000 | [diff] [blame] | 839 | <para>When enabled, Valgrind stops reporting errors after 10,000,000 |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 840 | in total, or 1,000 different ones, have been seen. This is to |
| 841 | stop the error tracking machinery from becoming a huge performance |
| 842 | overhead in programs with many errors.</para> |
| 843 | </listitem> |
| 844 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 845 | |
sewardj | b977908 | 2006-05-12 23:50:15 +0000 | [diff] [blame] | 846 | <varlistentry id="opt.error-exitcode" xreflabel="--error-exitcode"> |
| 847 | <term> |
| 848 | <option><![CDATA[--error-exitcode=<number> [default: 0] ]]></option> |
| 849 | </term> |
| 850 | <listitem> |
| 851 | <para>Specifies an alternative exit code to return if Valgrind |
| 852 | reported any errors in the run. When set to the default value |
| 853 | (zero), the return value from Valgrind will always be the return |
| 854 | value of the process being simulated. When set to a nonzero value, |
| 855 | that value is returned instead, if Valgrind detects any errors. |
| 856 | This is useful for using Valgrind as part of an automated test |
| 857 | suite, since it makes it easy to detect test cases for which |
| 858 | Valgrind has reported errors, just by inspecting return codes.</para> |
| 859 | </listitem> |
| 860 | </varlistentry> |
| 861 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 862 | <varlistentry id="opt.stack-traces" xreflabel="--show-below-main"> |
| 863 | <term> |
| 864 | <option><![CDATA[--show-below-main=<yes|no> [default: no] ]]></option> |
| 865 | </term> |
| 866 | <listitem> |
| 867 | <para>By default, stack traces for errors do not show any |
| 868 | functions that appear beneath <function>main()</function> |
| 869 | (or similar functions such as glibc's |
| 870 | <function>__libc_start_main()</function>, if |
| 871 | <function>main()</function> is not present in the stack trace); |
| 872 | most of the time it's uninteresting C library stuff. If this |
| 873 | option is enabled, those entries below <function>main()</function> |
| 874 | will be shown.</para> |
| 875 | </listitem> |
| 876 | </varlistentry> |
sewardj | d153fae | 2005-01-10 17:24:47 +0000 | [diff] [blame] | 877 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 878 | <varlistentry id="opt.suppressions" xreflabel="--suppressions"> |
| 879 | <term> |
| 880 | <option><![CDATA[--suppressions=<filename> [default: $PREFIX/lib/valgrind/default.supp] ]]></option> |
| 881 | </term> |
| 882 | <listitem> |
| 883 | <para>Specifies an extra file from which to read descriptions of |
| 884 | errors to suppress. You may use as many extra suppressions files |
| 885 | as you like.</para> |
| 886 | </listitem> |
| 887 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 888 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 889 | <varlistentry id="opt.gen-suppressions" xreflabel="--gen-supressions"> |
| 890 | <term> |
| 891 | <option><![CDATA[--gen-suppressions=<yes|no|all> [default: no] ]]></option> |
| 892 | </term> |
| 893 | <listitem> |
| 894 | <para>When set to <varname>yes</varname>, Valgrind will pause |
| 895 | after every error shown and print the line: |
| 896 | <literallayout> ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ----</literallayout> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 897 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 898 | The prompt's behaviour is the same as for the |
| 899 | <option>--db-attach</option> option (see below).</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 900 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 901 | <para>If you choose to, Valgrind will print out a suppression for |
| 902 | this error. You can then cut and paste it into a suppression file |
| 903 | 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] | 904 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 905 | <para>When set to <varname>all</varname>, Valgrind will print a |
| 906 | suppression for every reported error, without querying the |
| 907 | user.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 908 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 909 | <para>This option is particularly useful with C++ programs, as it |
| 910 | prints out the suppressions with mangled names, as |
| 911 | required.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 912 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 913 | <para>Note that the suppressions printed are as specific as |
| 914 | possible. You may want to common up similar ones, eg. by adding |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 915 | wildcards to function names. Sometimes two different errors |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 916 | are suppressed by the same suppression, in which case Valgrind |
| 917 | will output the suppression more than once, but you only need to |
| 918 | have one copy in your suppression file (but having more than one |
| 919 | won't cause problems). Also, the suppression name is given as |
| 920 | <computeroutput><insert a suppression name |
| 921 | here></computeroutput>; the name doesn't really matter, it's |
| 922 | only used with the <option>-v</option> option which prints out all |
| 923 | used suppression records.</para> |
| 924 | </listitem> |
| 925 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 926 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 927 | <varlistentry id="opt.db-attach" xreflabel="--db-attach"> |
| 928 | <term> |
| 929 | <option><![CDATA[--db-attach=<yes|no> [default: no] ]]></option> |
| 930 | </term> |
| 931 | <listitem> |
| 932 | <para>When enabled, Valgrind will pause after every error shown |
| 933 | and print the line: |
| 934 | <literallayout> ---- Attach to debugger ? --- [Return/N/n/Y/y/C/c] ----</literallayout> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 935 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 936 | Pressing <varname>Ret</varname>, or <varname>N Ret</varname> or |
| 937 | <varname>n Ret</varname>, causes Valgrind not to start a debugger |
| 938 | for this error.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 939 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 940 | <para>Pressing <varname>Y Ret</varname> or |
| 941 | <varname>y Ret</varname> causes Valgrind to start a debugger for |
| 942 | the program at this point. When you have finished with the |
| 943 | debugger, quit from it, and the program will continue. Trying to |
| 944 | continue from inside the debugger doesn't work.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 945 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 946 | <para><varname>C Ret</varname> or <varname>c Ret</varname> causes |
| 947 | Valgrind not to start a debugger, and not to ask again.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 948 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 949 | <para><command>Note:</command> <option>--db-attach=yes</option> |
| 950 | conflicts with <option>--trace-children=yes</option>. You can't |
| 951 | use them together. Valgrind refuses to start up in this |
| 952 | situation.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 953 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 954 | <para>May 2002: this is a historical relic which could be easily |
| 955 | fixed if it gets in your way. Mail us and complain if this is a |
| 956 | problem for you.</para> |
| 957 | <para>Nov 2002: if you're sending output to a logfile or to a |
| 958 | network socket, I guess this option doesn't make any sense. |
| 959 | Caveat emptor.</para> |
| 960 | </listitem> |
| 961 | </varlistentry> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 962 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 963 | <varlistentry id="opt.db-command" xreflabel="--db-command"> |
| 964 | <term> |
| 965 | <option><![CDATA[--db-command=<command> [default: gdb -nw %f %p] ]]></option> |
| 966 | </term> |
| 967 | <listitem> |
| 968 | <para>Specify the debugger to use with the |
| 969 | <option>--db-attach</option> command. The default debugger is |
| 970 | gdb. This option is a template that is expanded by Valgrind at |
| 971 | runtime. <literal>%f</literal> is replaced with the executable's |
| 972 | file name and <literal>%p</literal> is replaced by the process ID |
| 973 | of the executable.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 974 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 975 | <para>This specifies how Valgrind will invoke the debugger. By |
| 976 | default it will use whatever GDB is detected at build time, which |
| 977 | is usually <computeroutput>/usr/bin/gdb</computeroutput>. Using |
| 978 | this command, you can specify some alternative command to invoke |
| 979 | the debugger you want to use.</para> |
njn | 5127298 | 2005-07-25 23:18:44 +0000 | [diff] [blame] | 980 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 981 | <para>The command string given can include one or instances of the |
| 982 | <literal>%p</literal> and <literal>%f</literal> expansions. Each |
| 983 | instance of <literal>%p</literal> expands to the PID of the |
| 984 | process to be debugged and each instance of <literal>%f</literal> |
| 985 | expands to the path to the executable for the process to be |
| 986 | debugged.</para> |
| 987 | </listitem> |
| 988 | </varlistentry> |
| 989 | |
| 990 | <varlistentry id="opt.input-fd" xreflabel="--input-fd"> |
| 991 | <term> |
| 992 | <option><![CDATA[--input-fd=<number> [default: 0, stdin] ]]></option> |
| 993 | </term> |
| 994 | <listitem> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 995 | <para>When using <option>--db-attach=yes</option> or |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 996 | <option>--gen-suppressions=yes</option>, Valgrind will stop so as |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 997 | to read keyboard input from you when each error occurs. By |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 998 | default it reads from the standard input (stdin), which is |
| 999 | problematic for programs which close stdin. This option allows |
| 1000 | you to specify an alternative file descriptor from which to read |
| 1001 | input.</para> |
| 1002 | </listitem> |
| 1003 | </varlistentry> |
| 1004 | |
| 1005 | <varlistentry id="opt.max-stackframe" xreflabel="--max-stackframe"> |
| 1006 | <term> |
| 1007 | <option><![CDATA[--max-stackframe=<number> [default: 2000000] ]]></option> |
| 1008 | </term> |
| 1009 | <listitem> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1010 | <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] | 1011 | more than this amount then Valgrind will assume that |
| 1012 | the program is switching to a different stack.</para> |
| 1013 | |
| 1014 | <para>You may need to use this option if your program has large |
| 1015 | stack-allocated arrays. Valgrind keeps track of your program's |
| 1016 | stack pointer. If it changes by more than the threshold amount, |
| 1017 | Valgrind assumes your program is switching to a different stack, |
| 1018 | and Memcheck behaves differently than it would for a stack pointer |
| 1019 | change smaller than the threshold. Usually this heuristic works |
| 1020 | well. However, if your program allocates large structures on the |
| 1021 | stack, this heuristic will be fooled, and Memcheck will |
| 1022 | subsequently report large numbers of invalid stack accesses. This |
| 1023 | option allows you to change the threshold to a different |
| 1024 | value.</para> |
| 1025 | |
| 1026 | <para>You should only consider use of this flag if Valgrind's |
| 1027 | debug output directs you to do so. In that case it will tell you |
| 1028 | the new threshold you should specify.</para> |
| 1029 | |
| 1030 | <para>In general, allocating large structures on the stack is a |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1031 | bad idea, because you can easily run out of stack space, |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1032 | especially on systems with limited memory or which expect to |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1033 | support large numbers of threads each with a small stack, and also |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1034 | because the error checking performed by Memcheck is more effective |
| 1035 | for heap-allocated data than for stack-allocated data. If you |
| 1036 | have to use this flag, you may wish to consider rewriting your |
| 1037 | code to allocate on the heap rather than on the stack.</para> |
| 1038 | </listitem> |
| 1039 | </varlistentry> |
| 1040 | |
| 1041 | </variablelist> |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 1042 | <!-- end of xi:include in the manpage --> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1043 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1044 | </sect2> |
| 1045 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1046 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1047 | <sect2 id="manual-core.mallocopts" xreflabel="malloc()-related Options"> |
| 1048 | <title><computeroutput>malloc()</computeroutput>-related Options</title> |
| 1049 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 1050 | <!-- start of xi:include in the manpage --> |
| 1051 | <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] | 1052 | <computeroutput>malloc()</computeroutput> (e.g. Memcheck and |
njn | 1d0825f | 2006-03-27 11:37:07 +0000 | [diff] [blame] | 1053 | Massif), the following options apply.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1054 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 1055 | <variablelist id="malloc-related.opts.list"> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1056 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1057 | <varlistentry id="opt.alignment" xreflabel="--alignment"> |
| 1058 | <term> |
| 1059 | <option><![CDATA[--alignment=<number> [default: 8] ]]></option> |
| 1060 | </term> |
| 1061 | <listitem> |
| 1062 | <para>By default Valgrind's <function>malloc()</function>, |
| 1063 | <function>realloc()</function>, etc, return 8-byte aligned |
| 1064 | addresses. This is standard for most processors. However, some |
| 1065 | programs might assume that <function>malloc()</function> et al |
| 1066 | return 16-byte or more aligned memory. The supplied value must be |
| 1067 | between 8 and 4096 inclusive, and must be a power of two.</para> |
njn | 5127298 | 2005-07-25 23:18:44 +0000 | [diff] [blame] | 1068 | </listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1069 | </varlistentry> |
njn | 5127298 | 2005-07-25 23:18:44 +0000 | [diff] [blame] | 1070 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1071 | </variablelist> |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 1072 | <!-- end of xi:include in the manpage --> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1073 | |
| 1074 | </sect2> |
| 1075 | |
| 1076 | |
| 1077 | <sect2 id="manual-core.rareopts" xreflabel="Uncommon Options"> |
| 1078 | <title>Uncommon Options</title> |
| 1079 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 1080 | <!-- start of xi:include in the manpage --> |
| 1081 | <para id="uncommon.opts.para">These options apply to all tools, as they |
| 1082 | affect certain obscure workings of the Valgrind core. Most people won't |
| 1083 | need to use these.</para> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1084 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 1085 | <variablelist id="uncommon.opts.list"> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1086 | |
| 1087 | <varlistentry id="opt.run-libc-freeres" xreflabel="--run-libc-freeres"> |
| 1088 | <term> |
| 1089 | <option><![CDATA[--run-libc-freeres=<yes|no> [default: yes] ]]></option> |
| 1090 | </term> |
| 1091 | <listitem> |
| 1092 | <para>The GNU C library (<function>libc.so</function>), which is |
| 1093 | used by all programs, may allocate memory for its own uses. |
| 1094 | Usually it doesn't bother to free that memory when the program |
| 1095 | ends - there would be no point, since the Linux kernel reclaims |
| 1096 | all process resources when a process exits anyway, so it would |
| 1097 | just slow things down.</para> |
| 1098 | |
| 1099 | <para>The glibc authors realised that this behaviour causes leak |
| 1100 | checkers, such as Valgrind, to falsely report leaks in glibc, when |
| 1101 | a leak check is done at exit. In order to avoid this, they |
| 1102 | provided a routine called <function>__libc_freeres</function> |
| 1103 | specifically to make glibc release all memory it has allocated. |
njn | 1d0825f | 2006-03-27 11:37:07 +0000 | [diff] [blame] | 1104 | Memcheck therefore tries to run |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1105 | <function>__libc_freeres</function> at exit.</para> |
| 1106 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1107 | <para>Unfortunately, in some very old versions of glibc, |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1108 | <function>__libc_freeres</function> is sufficiently buggy to cause |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1109 | segmentation faults. This was particularly noticeable on Red Hat |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1110 | 7.1. So this flag is provided in order to inhibit the run of |
| 1111 | <function>__libc_freeres</function>. If your program seems to run |
| 1112 | fine on Valgrind, but segfaults at exit, you may find that |
| 1113 | <option>--run-libc-freeres=no</option> fixes that, although at the |
| 1114 | cost of possibly falsely reporting space leaks in |
| 1115 | <filename>libc.so</filename>.</para> |
| 1116 | </listitem> |
| 1117 | </varlistentry> |
| 1118 | |
| 1119 | <varlistentry id="opt.sim-hints" xreflabel="--sim-hints"> |
| 1120 | <term> |
| 1121 | <option><![CDATA[--sim-hints=hint1,hint2,... ]]></option> |
| 1122 | </term> |
| 1123 | <listitem> |
| 1124 | <para>Pass miscellaneous hints to Valgrind which slightly modify |
| 1125 | the simulated behaviour in nonstandard or dangerous ways, possibly |
| 1126 | to help the simulation of strange features. By default no hints |
| 1127 | are enabled. Use with caution! Currently known hints are:</para> |
| 1128 | <itemizedlist> |
| 1129 | <listitem> |
| 1130 | <para><option>lax-ioctls: </option> Be very lax about ioctl |
| 1131 | handling; the only assumption is that the size is |
| 1132 | correct. Doesn't require the full buffer to be initialized |
| 1133 | when writing. Without this, using some device drivers with a |
| 1134 | large number of strange ioctl commands becomes very |
| 1135 | tiresome.</para> |
| 1136 | </listitem> |
| 1137 | <listitem> |
| 1138 | <para><option>enable-inner: </option> Enable some special |
| 1139 | magic needed when the program being run is itself |
| 1140 | Valgrind.</para> |
| 1141 | </listitem> |
| 1142 | </itemizedlist> |
| 1143 | </listitem> |
| 1144 | </varlistentry> |
| 1145 | |
| 1146 | <varlistentry id="opt.kernel-variant" xreflabel="--kernel-variant"> |
| 1147 | <term> |
| 1148 | <option>--kernel-variant=variant1,variant2,...</option> |
| 1149 | </term> |
| 1150 | <listitem> |
| 1151 | <para>Handle system calls and ioctls arising from minor variants |
| 1152 | of the default kernel for this platform. This is useful for |
| 1153 | running on hacked kernels or with kernel modules which support |
| 1154 | nonstandard ioctls, for example. Use with caution. If you don't |
| 1155 | understand what this option does then you almost certainly don't |
| 1156 | need it. Currently known variants are:</para> |
| 1157 | <itemizedlist> |
| 1158 | <listitem> |
| 1159 | <para><option>bproc: </option> Support the sys_broc system |
| 1160 | call on x86. This is for running on BProc, which is a minor |
| 1161 | variant of standard Linux which is sometimes used for building |
| 1162 | clusters.</para> |
| 1163 | </listitem> |
| 1164 | </itemizedlist> |
| 1165 | </listitem> |
| 1166 | </varlistentry> |
| 1167 | |
| 1168 | <varlistentry id="opt.show-emwarns" xreflabel="--show-emwarns"> |
| 1169 | <term> |
| 1170 | <option><![CDATA[--show-emwarns=<yes|no> [default: no] ]]></option> |
| 1171 | </term> |
| 1172 | <listitem> |
| 1173 | <para>When enabled, Valgrind will emit warnings about its CPU |
| 1174 | emulation in certain cases. These are usually not |
| 1175 | interesting.</para> |
| 1176 | </listitem> |
| 1177 | </varlistentry> |
| 1178 | |
| 1179 | <varlistentry id="opt.smc-check" xreflabel="--smc-check"> |
| 1180 | <term> |
| 1181 | <option><![CDATA[--smc-check=<none|stack|all> [default: stack] ]]></option> |
| 1182 | </term> |
| 1183 | <listitem> |
| 1184 | <para>This option controls Valgrind's detection of self-modifying |
| 1185 | code. Valgrind can do no detection, detect self-modifying code on |
| 1186 | the stack, or detect self-modifying code anywhere. Note that the |
| 1187 | default option will catch the vast majority of cases, as far as we |
| 1188 | know. Running with <varname>all</varname> will slow Valgrind down |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1189 | greatly. Running with <varname>none</varname> will rarely |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1190 | speed things up, since very little code gets put on the stack for |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1191 | most programs.</para> |
| 1192 | |
| 1193 | <para>Some architectures (including ppc32 and ppc64) require |
| 1194 | programs which create code at runtime to flush the instruction |
| 1195 | cache in between code generation and first use. Valgrind |
| 1196 | observes and honours such instructions. Hence, on ppc32/Linux |
| 1197 | and ppc64/Linux, Valgrind always provides complete, transparent |
| 1198 | support for self-modifying code. It is only on x86/Linux |
| 1199 | and amd64/Linux that you need to use this flag.</para> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1200 | </listitem> |
| 1201 | </varlistentry> |
| 1202 | |
| 1203 | </variablelist> |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 1204 | <!-- end of xi:include in the manpage --> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1205 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1206 | </sect2> |
| 1207 | |
| 1208 | |
| 1209 | <sect2 id="manual-core.debugopts" xreflabel="Debugging Valgrind Options"> |
| 1210 | <title>Debugging Valgrind Options</title> |
| 1211 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 1212 | <!-- start of xi:include in the manpage --> |
| 1213 | <para id="debug.opts.para">There are also some options for debugging |
| 1214 | Valgrind itself. You shouldn't need to use them in the normal run of |
| 1215 | things. If you wish to see the list, use the |
| 1216 | <option>--help-debug</option> option.</para> |
| 1217 | <!-- end of xi:include in the manpage --> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1218 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1219 | </sect2> |
| 1220 | |
| 1221 | |
| 1222 | <sect2 id="manual-core.defopts" xreflabel="Setting default options"> |
| 1223 | <title>Setting default Options</title> |
| 1224 | |
| 1225 | <para>Note that Valgrind also reads options from three places:</para> |
| 1226 | |
| 1227 | <orderedlist> |
| 1228 | <listitem> |
| 1229 | <para>The file <computeroutput>~/.valgrindrc</computeroutput></para> |
| 1230 | </listitem> |
| 1231 | |
| 1232 | <listitem> |
| 1233 | <para>The environment variable |
| 1234 | <computeroutput>$VALGRIND_OPTS</computeroutput></para> |
| 1235 | </listitem> |
| 1236 | |
| 1237 | <listitem> |
| 1238 | <para>The file <computeroutput>./.valgrindrc</computeroutput></para> |
| 1239 | </listitem> |
| 1240 | </orderedlist> |
| 1241 | |
| 1242 | <para>These are processed in the given order, before the |
| 1243 | command-line options. Options processed later override those |
| 1244 | processed earlier; for example, options in |
| 1245 | <computeroutput>./.valgrindrc</computeroutput> will take |
| 1246 | precedence over those in |
| 1247 | <computeroutput>~/.valgrindrc</computeroutput>. The first two |
| 1248 | are particularly useful for setting the default tool to |
| 1249 | use.</para> |
| 1250 | |
| 1251 | <para>Any tool-specific options put in |
| 1252 | <computeroutput>$VALGRIND_OPTS</computeroutput> or the |
| 1253 | <computeroutput>.valgrindrc</computeroutput> files should be |
| 1254 | prefixed with the tool name and a colon. For example, if you |
| 1255 | want Memcheck to always do leak checking, you can put the |
| 1256 | following entry in <literal>~/.valgrindrc</literal>:</para> |
| 1257 | |
| 1258 | <programlisting><![CDATA[ |
| 1259 | --memcheck:leak-check=yes]]></programlisting> |
| 1260 | |
| 1261 | <para>This will be ignored if any tool other than Memcheck is |
| 1262 | run. Without the <computeroutput>memcheck:</computeroutput> |
| 1263 | part, this will cause problems if you select other tools that |
| 1264 | don't understand |
| 1265 | <computeroutput>--leak-check=yes</computeroutput>.</para> |
| 1266 | |
| 1267 | </sect2> |
| 1268 | |
| 1269 | </sect1> |
| 1270 | |
| 1271 | |
| 1272 | <sect1 id="manual-core.clientreq" |
| 1273 | xreflabel="The Client Request mechanism"> |
| 1274 | <title>The Client Request mechanism</title> |
| 1275 | |
| 1276 | <para>Valgrind has a trapdoor mechanism via which the client |
| 1277 | program can pass all manner of requests and queries to Valgrind |
| 1278 | and the current tool. Internally, this is used extensively to |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 1279 | make malloc, free, etc, work, although you don't see that.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1280 | |
| 1281 | <para>For your convenience, a subset of these so-called client |
| 1282 | requests is provided to allow you to tell Valgrind facts about |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 1283 | the behaviour of your program, and also to make queries. |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1284 | In particular, your program can tell Valgrind about changes in |
| 1285 | memory range permissions that Valgrind would not otherwise know |
| 1286 | about, and so allows clients to get Valgrind to do arbitrary |
| 1287 | custom checks.</para> |
| 1288 | |
| 1289 | <para>Clients need to include a header file to make this work. |
| 1290 | Which header file depends on which client requests you use. Some |
| 1291 | client requests are handled by the core, and are defined in the |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1292 | header file <filename>valgrind/valgrind.h</filename>. Tool-specific |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1293 | header files are named after the tool, e.g. |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1294 | <filename>valgrind/memcheck.h</filename>. All header files can be found |
| 1295 | in the <literal>include/valgrind</literal> directory of wherever Valgrind |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1296 | was installed.</para> |
| 1297 | |
| 1298 | <para>The macros in these header files have the magical property |
| 1299 | that they generate code in-line which Valgrind can spot. |
| 1300 | However, the code does nothing when not run on Valgrind, so you |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1301 | are not forced to run your program under Valgrind just because you |
| 1302 | use the macros in this file. Also, you are not required to link your |
| 1303 | program with any extra supporting libraries.</para> |
| 1304 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1305 | <para>The code added to your binary has negligible performance impact: |
| 1306 | on x86, amd64, ppc32 and ppc64, the overhead is 6 simple integer instructions |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 1307 | and is probably undetectable except in tight loops. |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1308 | However, if you really wish to compile out the client requests, you can |
| 1309 | compile with <computeroutput>-DNVALGRIND</computeroutput> (analogous to |
| 1310 | <computeroutput>-DNDEBUG</computeroutput>'s effect on |
| 1311 | <computeroutput>assert()</computeroutput>). |
| 1312 | </para> |
| 1313 | |
| 1314 | <para>You are encouraged to copy the <filename>valgrind/*.h</filename> headers |
| 1315 | into your project's include directory, so your program doesn't have a |
| 1316 | compile-time dependency on Valgrind being installed. The Valgrind headers, |
njn | 7fd15d6 | 2006-03-31 12:05:04 +0000 | [diff] [blame] | 1317 | unlike most of the rest of the code, are under a BSD-style license so you may |
| 1318 | include them without worrying about license incompatibility.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1319 | |
| 1320 | <para>Here is a brief description of the macros available in |
| 1321 | <filename>valgrind.h</filename>, which work with more than one |
| 1322 | tool (see the tool-specific documentation for explanations of the |
| 1323 | tool-specific macros).</para> |
| 1324 | |
| 1325 | <variablelist> |
| 1326 | |
| 1327 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1328 | <term><command><computeroutput>RUNNING_ON_VALGRIND</computeroutput></command>:</term> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1329 | <listitem> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1330 | <para>Returns 1 if running on Valgrind, 0 if running on the |
| 1331 | real CPU. If you are running Valgrind on itself, returns the |
| 1332 | number of layers of Valgrind emulation you're running on. |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1333 | </para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1334 | </listitem> |
| 1335 | </varlistentry> |
| 1336 | |
| 1337 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1338 | <term><command><computeroutput>VALGRIND_DISCARD_TRANSLATIONS</computeroutput>:</command></term> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1339 | <listitem> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1340 | <para>Discards translations of code in the specified address |
| 1341 | range. Useful if you are debugging a JIT compiler or some other |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1342 | dynamic code generation system. After this call, attempts to |
| 1343 | execute code in the invalidated address range will cause |
| 1344 | Valgrind to make new translations of that code, which is |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 1345 | probably the semantics you want. Note that code invalidations |
| 1346 | are expensive because finding all the relevant translations |
| 1347 | quickly is very difficult. So try not to call it often. |
| 1348 | Note that you can be clever about |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1349 | this: you only need to call it when an area which previously |
| 1350 | contained code is overwritten with new code. You can choose |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 1351 | to write code into fresh memory, and just call this |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1352 | occasionally to discard large chunks of old code all at |
| 1353 | once.</para> |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 1354 | <para> |
| 1355 | Alternatively, for transparent self-modifying-code support, |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1356 | use<computeroutput>--smc-check=all</computeroutput>, or run |
| 1357 | on ppc32/Linux or ppc64/Linux. |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 1358 | </para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1359 | </listitem> |
| 1360 | </varlistentry> |
| 1361 | |
| 1362 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1363 | <term><command><computeroutput>VALGRIND_COUNT_ERRORS</computeroutput>:</command></term> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1364 | <listitem> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1365 | <para>Returns the number of errors found so far by Valgrind. Can be |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1366 | useful in test harness code when combined with the |
| 1367 | <option>--log-fd=-1</option> option; this runs Valgrind silently, |
| 1368 | but the client program can detect when errors occur. Only useful |
| 1369 | for tools that report errors, e.g. it's useful for Memcheck, but for |
| 1370 | Cachegrind it will always return zero because Cachegrind doesn't |
| 1371 | report errors.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1372 | </listitem> |
| 1373 | </varlistentry> |
| 1374 | |
| 1375 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1376 | <term><command><computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput>:</command></term> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1377 | <listitem> |
| 1378 | <para>If your program manages its own memory instead of using |
| 1379 | the standard <computeroutput>malloc()</computeroutput> / |
| 1380 | <computeroutput>new</computeroutput> / |
| 1381 | <computeroutput>new[]</computeroutput>, tools that track |
| 1382 | information about heap blocks will not do nearly as good a |
| 1383 | job. For example, Memcheck won't detect nearly as many |
| 1384 | errors, and the error messages won't be as informative. To |
| 1385 | improve this situation, use this macro just after your custom |
| 1386 | allocator allocates some new memory. See the comments in |
| 1387 | <filename>valgrind.h</filename> for information on how to use |
| 1388 | it.</para> |
| 1389 | </listitem> |
| 1390 | </varlistentry> |
| 1391 | |
| 1392 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1393 | <term><command><computeroutput>VALGRIND_FREELIKE_BLOCK</computeroutput>:</command></term> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1394 | <listitem> |
| 1395 | <para>This should be used in conjunction with |
| 1396 | <computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput>. |
| 1397 | Again, see <filename>memcheck/memcheck.h</filename> for |
| 1398 | information on how to use it.</para> |
| 1399 | </listitem> |
| 1400 | </varlistentry> |
| 1401 | |
| 1402 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1403 | <term><command><computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput>:</command></term> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1404 | <listitem> |
| 1405 | <para>This is similar to |
| 1406 | <computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput>, |
| 1407 | but is tailored towards code that uses memory pools. See the |
| 1408 | comments in <filename>valgrind.h</filename> for information |
| 1409 | on how to use it.</para> |
| 1410 | </listitem> |
| 1411 | </varlistentry> |
| 1412 | |
| 1413 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1414 | <term><command><computeroutput>VALGRIND_DESTROY_MEMPOOL</computeroutput>:</command></term> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1415 | <listitem> |
| 1416 | <para>This should be used in conjunction with |
| 1417 | <computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput> |
| 1418 | Again, see the comments in <filename>valgrind.h</filename> for |
| 1419 | information on how to use it.</para> |
| 1420 | </listitem> |
| 1421 | </varlistentry> |
| 1422 | |
| 1423 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1424 | <term><command><computeroutput>VALGRIND_MEMPOOL_ALLOC</computeroutput>:</command></term> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1425 | <listitem> |
| 1426 | <para>This should be used in conjunction with |
| 1427 | <computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput> |
| 1428 | Again, see the comments in <filename>valgrind.h</filename> for |
| 1429 | information on how to use it.</para> |
| 1430 | </listitem> |
| 1431 | </varlistentry> |
| 1432 | |
| 1433 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1434 | <term><command><computeroutput>VALGRIND_MEMPOOL_FREE</computeroutput>:</command></term> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1435 | <listitem> |
| 1436 | <para>This should be used in conjunction with |
| 1437 | <computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput> |
| 1438 | Again, see the comments in <filename>valgrind.h</filename> for |
| 1439 | information on how to use it.</para> |
| 1440 | </listitem> |
| 1441 | </varlistentry> |
| 1442 | |
| 1443 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1444 | <term><command><computeroutput>VALGRIND_NON_SIMD_CALL[0123]</computeroutput>:</command></term> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1445 | <listitem> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1446 | <para>Executes a function of 0, 1, 2 or 3 args in the client |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1447 | program on the <emphasis>real</emphasis> CPU, not the virtual |
| 1448 | CPU that Valgrind normally runs code on. These are used in |
| 1449 | various ways internally to Valgrind. They might be useful to |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1450 | client programs.</para> |
| 1451 | |
| 1452 | <para><command>Warning:</command> Only use these if you |
| 1453 | <emphasis>really</emphasis> know what you are doing.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1454 | </listitem> |
| 1455 | </varlistentry> |
| 1456 | |
| 1457 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1458 | <term><command><computeroutput>VALGRIND_PRINTF(format, ...)</computeroutput>:</command></term> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1459 | <listitem> |
| 1460 | <para>printf a message to the log file when running under |
| 1461 | Valgrind. Nothing is output if not running under Valgrind. |
| 1462 | Returns the number of characters output.</para> |
| 1463 | </listitem> |
| 1464 | </varlistentry> |
| 1465 | |
| 1466 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1467 | <term><command><computeroutput>VALGRIND_PRINTF_BACKTRACE(format, ...)</computeroutput>:</command></term> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1468 | <listitem> |
| 1469 | <para>printf a message to the log file along with a stack |
| 1470 | backtrace when running under Valgrind. Nothing is output if |
| 1471 | not running under Valgrind. Returns the number of characters |
| 1472 | output.</para> |
| 1473 | </listitem> |
| 1474 | </varlistentry> |
| 1475 | |
rjwalsh | 0140af5 | 2005-06-04 20:42:33 +0000 | [diff] [blame] | 1476 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1477 | <term><command><computeroutput>VALGRIND_STACK_REGISTER(start, end)</computeroutput>:</command></term> |
rjwalsh | 0140af5 | 2005-06-04 20:42:33 +0000 | [diff] [blame] | 1478 | <listitem> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1479 | <para>Registers a new stack. Informs Valgrind that the memory range |
rjwalsh | 0140af5 | 2005-06-04 20:42:33 +0000 | [diff] [blame] | 1480 | between start and end is a unique stack. Returns a stack identifier |
| 1481 | that can be used with other |
| 1482 | <computeroutput>VALGRIND_STACK_*</computeroutput> calls.</para> |
| 1483 | <para>Valgrind will use this information to determine if a change to |
| 1484 | the stack pointer is an item pushed onto the stack or a change over |
| 1485 | to a new stack. Use this if you're using a user-level thread package |
| 1486 | and are noticing spurious errors from Valgrind about uninitialized |
| 1487 | memory reads.</para> |
| 1488 | </listitem> |
| 1489 | </varlistentry> |
| 1490 | |
| 1491 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1492 | <term><command><computeroutput>VALGRIND_STACK_DEREGISTER(id)</computeroutput>:</command></term> |
rjwalsh | 0140af5 | 2005-06-04 20:42:33 +0000 | [diff] [blame] | 1493 | <listitem> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1494 | <para>Deregisters a previously registered stack. Informs |
rjwalsh | 0140af5 | 2005-06-04 20:42:33 +0000 | [diff] [blame] | 1495 | Valgrind that previously registered memory range with stack id |
| 1496 | <computeroutput>id</computeroutput> is no longer a stack.</para> |
| 1497 | </listitem> |
| 1498 | </varlistentry> |
| 1499 | |
| 1500 | <varlistentry> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 1501 | <term><command><computeroutput>VALGRIND_STACK_CHANGE(id, start, end)</computeroutput>:</command></term> |
rjwalsh | 0140af5 | 2005-06-04 20:42:33 +0000 | [diff] [blame] | 1502 | <listitem> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1503 | <para>Changes a previously registered stack. Informs |
rjwalsh | 0140af5 | 2005-06-04 20:42:33 +0000 | [diff] [blame] | 1504 | Valgrind that the previously registerer stack with stack id |
| 1505 | <computeroutput>id</computeroutput> has changed it's start and end |
| 1506 | values. Use this if your user-level thread package implements |
| 1507 | stack growth.</para> |
| 1508 | </listitem> |
| 1509 | </varlistentry> |
| 1510 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1511 | </variablelist> |
| 1512 | |
| 1513 | <para>Note that <filename>valgrind.h</filename> is included by |
| 1514 | all the tool-specific header files (such as |
| 1515 | <filename>memcheck.h</filename>), so you don't need to include it |
| 1516 | in your client if you include a tool-specific header.</para> |
| 1517 | |
| 1518 | </sect1> |
| 1519 | |
| 1520 | |
| 1521 | |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1522 | <sect1 id="manual-core.pthreads" xreflabel="Support for Threads"> |
| 1523 | <title>Support for Threads</title> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1524 | |
| 1525 | <para>Valgrind supports programs which use POSIX pthreads. |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1526 | Getting this to work was technically challenging but it now works |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1527 | well enough for significant threaded applications to work.</para> |
| 1528 | |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 1529 | <para>The main thing to point out is that although Valgrind works |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1530 | with the standard Linux threads library (eg. NPTL or LinuxThreads), it |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 1531 | serialises execution so that only one thread is running at a time. This |
| 1532 | approach avoids the horrible implementation problems of implementing a |
| 1533 | truly multiprocessor version of Valgrind, but it does mean that threaded |
| 1534 | apps run only on one CPU, even if you have a multiprocessor |
| 1535 | machine.</para> |
| 1536 | |
| 1537 | <para>Valgrind schedules your program's threads in a round-robin fashion, |
| 1538 | with all threads having equal priority. It switches threads |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1539 | every 100000 basic blocks (on x86, typically around 600000 |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 1540 | instructions), which means you'll get a much finer interleaving |
| 1541 | of thread executions than when run natively. This in itself may |
| 1542 | cause your program to behave differently if you have some kind of |
| 1543 | concurrency, critical race, locking, or similar, bugs.</para> |
| 1544 | |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1545 | <para>Your program will use the native |
| 1546 | <computeroutput>libpthread</computeroutput>, but not all of its facilities |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 1547 | will work. In particular, synchonisation of processes via shared-memory |
| 1548 | segments will not work. This relies on special atomic instruction sequences |
| 1549 | which Valgrind does not emulate in a way which works between processes. |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1550 | Unfortunately there's no way for Valgrind to warn when this is happening, |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1551 | and such calls will mostly work. Only when there's a race will |
| 1552 | it fail. |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1553 | </para> |
| 1554 | |
| 1555 | <para>Valgrind also supports direct use of the |
| 1556 | <computeroutput>clone()</computeroutput> system call, |
| 1557 | <computeroutput>futex()</computeroutput> and so on. |
| 1558 | <computeroutput>clone()</computeroutput> is supported where either |
| 1559 | everything is shared (a thread) or nothing is shared (fork-like); partial |
| 1560 | sharing will fail. Again, any use of atomic instruction sequences in shared |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 1561 | memory between processes will not work reliably. |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1562 | </para> |
| 1563 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1564 | |
| 1565 | </sect1> |
| 1566 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1567 | <sect1 id="manual-core.signals" xreflabel="Handling of Signals"> |
| 1568 | <title>Handling of Signals</title> |
| 1569 | |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1570 | <para>Valgrind has a fairly complete signal implementation. It should be |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1571 | able to cope with any POSIX-compliant use of signals.</para> |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1572 | |
| 1573 | <para>If you're using signals in clever ways (for example, catching |
| 1574 | SIGSEGV, modifying page state and restarting the instruction), you're |
| 1575 | probably relying on precise exceptions. In this case, you will need |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 1576 | to use <computeroutput>--vex-iropt-precise-memory-exns=yes</computeroutput>. |
| 1577 | </para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1578 | |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1579 | <para>If your program dies as a result of a fatal core-dumping signal, |
| 1580 | Valgrind will generate its own core file |
njn | 14c9add | 2005-11-18 17:36:01 +0000 | [diff] [blame] | 1581 | (<computeroutput>vgcore.NNNNN</computeroutput>) containing your program's |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1582 | state. You may use this core file for post-mortem debugging with gdb or |
| 1583 | similar. (Note: it will not generate a core if your core dump size limit is |
njn | 14c9add | 2005-11-18 17:36:01 +0000 | [diff] [blame] | 1584 | 0.) At the time of writing the core dumps do not include all the floating |
| 1585 | point register information.</para> |
| 1586 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1587 | <para>In the unlikely event that Valgrind itself crashes, the operating system |
njn | 14c9add | 2005-11-18 17:36:01 +0000 | [diff] [blame] | 1588 | will create a core dump in the usual way.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1589 | |
| 1590 | </sect1> |
| 1591 | |
| 1592 | |
| 1593 | |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1594 | <sect1 id="manual-core.wrapping" xreflabel="Function Wrapping"> |
| 1595 | <title>Function wrapping</title> |
| 1596 | |
| 1597 | <para> |
| 1598 | Valgrind versions 3.2.0 and above and can do function wrapping on all |
| 1599 | supported targets. In function wrapping, calls to some specified |
| 1600 | function are intercepted and rerouted to a different, user-supplied |
| 1601 | function. This can do whatever it likes, typically examining the |
| 1602 | arguments, calling onwards to the original, and possibly examining the |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1603 | result. Any number of functions may be wrapped.</para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1604 | |
| 1605 | <para> |
| 1606 | Function wrapping is useful for instrumenting an API in some way. For |
| 1607 | example, wrapping functions in the POSIX pthreads API makes it |
| 1608 | possible to notify Valgrind of thread status changes, and wrapping |
| 1609 | functions in the MPI (message-passing) API allows notifying Valgrind |
| 1610 | of memory status changes associated with message arrival/departure. |
| 1611 | Such information is usually passed to Valgrind by using client |
| 1612 | requests in the wrapper functions, although that is not of relevance |
| 1613 | here.</para> |
| 1614 | |
| 1615 | <sect2 id="manual-core.wrapping.example" xreflabel="A Simple Example"> |
| 1616 | <title>A Simple Example</title> |
| 1617 | |
| 1618 | <para>Supposing we want to wrap some function</para> |
| 1619 | |
| 1620 | <programlisting><![CDATA[ |
| 1621 | int foo ( int x, int y ) { return x + y; }]]></programlisting> |
| 1622 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1623 | <para>A wrapper is a function of identical type, but with a special name |
| 1624 | which identifies it as the wrapper for <computeroutput>foo</computeroutput>. |
| 1625 | Wrappers need to include |
| 1626 | supporting macros from <computeroutput>valgrind.h</computeroutput>. |
| 1627 | Here is a simple wrapper which prints the arguments and return value:</para> |
| 1628 | |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1629 | <programlisting><![CDATA[ |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1630 | #include <stdio.h> |
| 1631 | #include "valgrind.h" |
| 1632 | int I_WRAP_SONAME_FNNAME_ZU(NONE,foo)( int x, int y ) |
| 1633 | { |
| 1634 | int result; |
| 1635 | OrigFn fn; |
| 1636 | VALGRIND_GET_ORIG_FN(fn); |
| 1637 | printf("foo's wrapper: args %d %d\n", x, y); |
| 1638 | CALL_FN_W_WW(result, fn, x,y); |
| 1639 | printf("foo's wrapper: result %d\n", result); |
| 1640 | return result; |
| 1641 | } |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1642 | ]]></programlisting> |
| 1643 | |
| 1644 | <para>To become active, the wrapper merely needs to be present in a text |
| 1645 | section somewhere in the same process' address space as the function |
| 1646 | it wraps, and for its ELF symbol name to be visible to Valgrind. In |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1647 | practice, this means either compiling to a |
| 1648 | <computeroutput>.o</computeroutput> and linking it in, or |
| 1649 | compiling to a <computeroutput>.so</computeroutput> and |
| 1650 | <computeroutput>LD_PRELOAD</computeroutput>ing it in. The latter is more |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1651 | convenient in that it doesn't require relinking.</para> |
| 1652 | |
| 1653 | <para>All wrappers have approximately the above form. There are three |
| 1654 | crucial macros:</para> |
| 1655 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1656 | <para><computeroutput>I_WRAP_SONAME_FNNAME_ZU</computeroutput>: |
| 1657 | this generates the real name of the wrapper. |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1658 | This is an encoded name which Valgrind notices when reading symbol |
| 1659 | table information. What it says is: I am the wrapper for any function |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1660 | named <computeroutput>foo</computeroutput> which is found in |
| 1661 | an ELF shared object with an empty |
| 1662 | ("<computeroutput>NONE</computeroutput>") soname field. The specification |
| 1663 | mechanism is powerful in |
| 1664 | that wildcards are allowed for both sonames and function names. |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1665 | The details are discussed below.</para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1666 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1667 | <para><computeroutput>VALGRIND_GET_ORIG_FN</computeroutput>: |
| 1668 | once in the the wrapper, the first priority is |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1669 | to get hold of the address of the original (and any other supporting |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1670 | information needed). This is stored in a value of opaque |
| 1671 | type <computeroutput>OrigFn</computeroutput>. |
| 1672 | The information is acquired using |
| 1673 | <computeroutput>VALGRIND_GET_ORIG_FN</computeroutput>. It is crucial |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1674 | to make this macro call before calling any other wrapped function |
| 1675 | in the same thread.</para> |
| 1676 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1677 | <para><computeroutput>CALL_FN_W_WW</computeroutput>: eventually we will |
| 1678 | want to call the function being |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1679 | wrapped. Calling it directly does not work, since that just gets us |
| 1680 | back to the wrapper and tends to kill the program in short order by |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1681 | stack overflow. Instead, the result lvalue, |
| 1682 | <computeroutput>OrigFn</computeroutput> and arguments are |
| 1683 | handed to one of a family of macros of the form |
| 1684 | <computeroutput>CALL_FN_*</computeroutput>. These |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1685 | cause Valgrind to call the original and avoid recursion back to the |
| 1686 | wrapper.</para> |
| 1687 | </sect2> |
| 1688 | |
| 1689 | <sect2 id="manual-core.wrapping.specs" xreflabel="Wrapping Specifications"> |
| 1690 | <title>Wrapping Specifications</title> |
| 1691 | |
| 1692 | <para>This scheme has the advantage of being self-contained. A library of |
| 1693 | wrappers can be compiled to object code in the normal way, and does |
| 1694 | not rely on an external script telling Valgrind which wrappers pertain |
| 1695 | to which originals.</para> |
| 1696 | |
| 1697 | <para>Each wrapper has a name which, in the most general case says: I am the |
| 1698 | wrapper for any function whose name matches FNPATT and whose ELF |
| 1699 | "soname" matches SOPATT. Both FNPATT and SOPATT may contain wildcards |
| 1700 | (asterisks) and other characters (spaces, dots, @, etc) which are not |
| 1701 | generally regarded as valid C identifier names.</para> |
| 1702 | |
| 1703 | <para>This flexibility is needed to write robust wrappers for POSIX pthread |
| 1704 | functions, where typically we are not completely sure of either the |
| 1705 | function name or the soname, or alternatively we want to wrap a whole |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1706 | set of functions at once.</para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1707 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1708 | <para>For example, <computeroutput>pthread_create</computeroutput> |
| 1709 | in GNU libpthread is usually a |
| 1710 | versioned symbol - one whose name ends in, eg, |
| 1711 | <computeroutput>@GLIBC_2.3</computeroutput>. Hence we |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1712 | are not sure what its real name is. We also want to cover any soname |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1713 | of the form <computeroutput>libpthread.so*</computeroutput>. |
| 1714 | So the header of the wrapper will be</para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1715 | |
| 1716 | <programlisting><![CDATA[ |
| 1717 | int I_WRAP_SONAME_FNNAME_ZZ(libpthreadZdsoZd0,pthreadZucreateZAZa) |
| 1718 | ( ... formals ... ) |
| 1719 | { ... body ... } |
| 1720 | ]]></programlisting> |
| 1721 | |
| 1722 | <para>In order to write unusual characters as valid C function names, a |
| 1723 | Z-encoding scheme is used. Names are written literally, except that |
| 1724 | a capital Z acts as an escape character, with the following encoding:</para> |
| 1725 | |
| 1726 | <programlisting><![CDATA[ |
| 1727 | Za encodes * |
| 1728 | Zp + |
| 1729 | Zc : |
| 1730 | Zd . |
| 1731 | Zu _ |
| 1732 | Zh - |
| 1733 | Zs (space) |
| 1734 | ZA @ |
| 1735 | ZZ Z |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1736 | ZL ( # only in valgrind 3.3.0 and later |
| 1737 | ZR ) # only in valgrind 3.3.0 and later |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1738 | ]]></programlisting> |
| 1739 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1740 | <para>Hence <computeroutput>libpthreadZdsoZd0</computeroutput> is an |
| 1741 | encoding of the soname <computeroutput>libpthread.so.0</computeroutput> |
| 1742 | and <computeroutput>pthreadZucreateZAZa</computeroutput> is an encoding |
| 1743 | of the function name <computeroutput>pthread_create@*</computeroutput>. |
| 1744 | </para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1745 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1746 | <para>The macro <computeroutput>I_WRAP_SONAME_FNNAME_ZZ</computeroutput> |
| 1747 | constructs a wrapper name in which |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1748 | both the soname (first component) and function name (second component) |
| 1749 | are Z-encoded. Encoding the function name can be tiresome and is |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1750 | often unnecessary, so a second macro, |
| 1751 | <computeroutput>I_WRAP_SONAME_FNNAME_ZU</computeroutput>, can be |
| 1752 | used instead. The <computeroutput>_ZU</computeroutput> variant is |
| 1753 | also useful for writing wrappers for |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1754 | C++ functions, in which the function name is usually already mangled |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1755 | using some other convention in which Z plays an important role. Having |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1756 | to encode a second time quickly becomes confusing.</para> |
| 1757 | |
| 1758 | <para>Since the function name field may contain wildcards, it can be |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1759 | anything, including just <computeroutput>*</computeroutput>. |
| 1760 | The same is true for the soname. |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1761 | However, some ELF objects - specifically, main executables - do not |
| 1762 | have sonames. Any object lacking a soname is treated as if its soname |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1763 | was <computeroutput>NONE</computeroutput>, which is why the original |
| 1764 | example above had a name |
| 1765 | <computeroutput>I_WRAP_SONAME_FNNAME_ZU(NONE,foo)</computeroutput>.</para> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1766 | |
| 1767 | <para>Note that the soname of an ELF object is not the same as its |
| 1768 | file name, although it is often similar. You can find the soname of |
| 1769 | an object <computeroutput>libfoo.so</computeroutput> using the command |
| 1770 | <computeroutput>readelf -a libfoo.so | grep soname</computeroutput>.</para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1771 | </sect2> |
| 1772 | |
| 1773 | <sect2 id="manual-core.wrapping.semantics" xreflabel="Wrapping Semantics"> |
| 1774 | <title>Wrapping Semantics</title> |
| 1775 | |
| 1776 | <para>The ability for a wrapper to replace an infinite family of functions |
| 1777 | is powerful but brings complications in situations where ELF objects |
| 1778 | appear and disappear (are dlopen'd and dlclose'd) on the fly. |
| 1779 | Valgrind tries to maintain sensible behaviour in such situations.</para> |
| 1780 | |
| 1781 | <para>For example, suppose a process has dlopened (an ELF object with |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1782 | soname) <computeroutput>object1.so</computeroutput>, which contains |
| 1783 | <computeroutput>function1</computeroutput>. It starts to use |
| 1784 | <computeroutput>function1</computeroutput> immediately.</para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1785 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1786 | <para>After a while it dlopens <computeroutput>wrappers.so</computeroutput>, |
| 1787 | which contains a wrapper |
| 1788 | for <computeroutput>function1</computeroutput> in (soname) |
| 1789 | <computeroutput>object1.so</computeroutput>. All subsequent calls to |
| 1790 | <computeroutput>function1</computeroutput> are rerouted to the wrapper.</para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1791 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1792 | <para>If <computeroutput>wrappers.so</computeroutput> is |
| 1793 | later dlclose'd, calls to <computeroutput>function1</computeroutput> are |
| 1794 | naturally routed back to the original.</para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1795 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1796 | <para>Alternatively, if <computeroutput>object1.so</computeroutput> |
| 1797 | is dlclose'd but wrappers.so remains, |
| 1798 | then the wrapper exported by <computeroutput>wrapper.so</computeroutput> |
| 1799 | becomes inactive, since there |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1800 | is no way to get to it - there is no original to call any more. However, |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1801 | Valgrind remembers that the wrapper is still present. If |
| 1802 | <computeroutput>object1.so</computeroutput> is |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1803 | eventually dlopen'd again, the wrapper will become active again.</para> |
| 1804 | |
| 1805 | <para>In short, valgrind inspects all code loading/unloading events to |
| 1806 | ensure that the set of currently active wrappers remains consistent.</para> |
| 1807 | |
| 1808 | <para>A second possible problem is that of conflicting wrappers. It is |
| 1809 | easily possible to load two or more wrappers, both of which claim |
| 1810 | to be wrappers for some third function. In such cases Valgrind will |
| 1811 | complain about conflicting wrappers when the second one appears, and |
| 1812 | will honour only the first one.</para> |
| 1813 | </sect2> |
| 1814 | |
| 1815 | <sect2 id="manual-core.wrapping.debugging" xreflabel="Debugging"> |
| 1816 | <title>Debugging</title> |
| 1817 | |
| 1818 | <para>Figuring out what's going on given the dynamic nature of wrapping |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1819 | can be difficult. The |
| 1820 | <computeroutput>--trace-redir=yes</computeroutput> flag makes |
| 1821 | this possible |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1822 | by showing the complete state of the redirection subsystem after |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1823 | every |
| 1824 | <computeroutput>mmap</computeroutput>/<computeroutput>munmap</computeroutput> |
| 1825 | event affecting code (text).</para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1826 | |
| 1827 | <para>There are two central concepts:</para> |
| 1828 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1829 | <itemizedlist> |
| 1830 | |
| 1831 | <listitem><para>A "redirection specification" is a binding of |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1832 | a (soname pattern, fnname pattern) pair to a code address. |
| 1833 | These bindings are created by writing functions with names |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1834 | made with the |
| 1835 | <computeroutput>I_WRAP_SONAME_FNNAME_{ZZ,_ZU}</computeroutput> |
| 1836 | macros.</para></listitem> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1837 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1838 | <listitem><para>An "active redirection" is code-address to |
| 1839 | code-address binding currently in effect.</para></listitem> |
| 1840 | |
| 1841 | </itemizedlist> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1842 | |
| 1843 | <para>The state of the wrapping-and-redirection subsystem comprises a set of |
| 1844 | specifications and a set of active bindings. The specifications are |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1845 | acquired/discarded by watching all |
| 1846 | <computeroutput>mmap</computeroutput>/<computeroutput>munmap</computeroutput> |
| 1847 | events on code (text) |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1848 | sections. The active binding set is (conceptually) recomputed from |
| 1849 | the specifications, and all known symbol names, following any change |
| 1850 | to the specification set.</para> |
| 1851 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1852 | <para><computeroutput>--trace-redir=yes</computeroutput> shows the contents |
| 1853 | of both sets following any such event.</para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1854 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1855 | <para><computeroutput>-v</computeroutput> prints a line of text each |
| 1856 | time an active specification is used for the first time.</para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1857 | |
| 1858 | <para>Hence for maximum debugging effectiveness you will need to use both |
| 1859 | flags.</para> |
| 1860 | |
| 1861 | <para>One final comment. The function-wrapping facility is closely |
| 1862 | tied to Valgrind's ability to replace (redirect) specified |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1863 | functions, for example to redirect calls to |
| 1864 | <computeroutput>malloc</computeroutput> to its |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1865 | own implementation. Indeed, a replacement function can be |
| 1866 | regarded as a wrapper function which does not call the original. |
| 1867 | However, to make the implementation more robust, the two kinds |
| 1868 | of interception (wrapping vs replacement) are treated differently. |
| 1869 | </para> |
| 1870 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1871 | <para><computeroutput>--trace-redir=yes</computeroutput> shows |
| 1872 | specifications and bindings for both |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1873 | replacement and wrapper functions. To differentiate the |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1874 | two, replacement bindings are printed using |
| 1875 | <computeroutput>R-></computeroutput> whereas |
| 1876 | wraps are printed using <computeroutput>W-></computeroutput>. |
| 1877 | </para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1878 | </sect2> |
| 1879 | |
| 1880 | |
| 1881 | <sect2 id="manual-core.wrapping.limitations-cf" |
| 1882 | xreflabel="Limitations - control flow"> |
| 1883 | <title>Limitations - control flow</title> |
| 1884 | |
| 1885 | <para>For the most part, the function wrapping implementation is robust. |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1886 | The only important caveat is: in a wrapper, get hold of |
| 1887 | the <computeroutput>OrigFn</computeroutput> information using |
| 1888 | <computeroutput>VALGRIND_GET_ORIG_FN</computeroutput> before calling any |
| 1889 | other wrapped function. Once you have the |
| 1890 | <computeroutput>OrigFn</computeroutput>, arbitrary |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1891 | calls between, recursion between, and longjumps out of wrappers |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1892 | should work correctly. There is never any interaction between wrapped |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1893 | functions and merely replaced functions |
| 1894 | (eg <computeroutput>malloc</computeroutput>), so you can call |
| 1895 | <computeroutput>malloc</computeroutput> etc safely from within wrappers. |
| 1896 | </para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1897 | |
| 1898 | <para>The above comments are true for {x86,amd64,ppc32}-linux. On |
| 1899 | ppc64-linux function wrapping is more fragile due to the (arguably |
| 1900 | poorly designed) ppc64-linux ABI. This mandates the use of a shadow |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1901 | stack which tracks entries/exits of both wrapper and replacement |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1902 | functions. This gives two limitations: firstly, longjumping out of |
| 1903 | wrappers will rapidly lead to disaster, since the shadow stack will |
| 1904 | not get correctly cleared. Secondly, since the shadow stack has |
| 1905 | finite size, recursion between wrapper/replacement functions is only |
| 1906 | possible to a limited depth, beyond which Valgrind has to abort the |
| 1907 | run. This depth is currently 16 calls.</para> |
| 1908 | |
| 1909 | <para>For all platforms ({x86,amd64,ppc32,ppc64}-linux) all the above |
| 1910 | comments apply on a per-thread basis. In other words, wrapping is |
| 1911 | thread-safe: each thread must individually observe the above |
| 1912 | restrictions, but there is no need for any kind of inter-thread |
| 1913 | cooperation.</para> |
| 1914 | </sect2> |
| 1915 | |
| 1916 | |
| 1917 | <sect2 id="manual-core.wrapping.limitations-sigs" |
| 1918 | xreflabel="Limitations - original function signatures"> |
| 1919 | <title>Limitations - original function signatures</title> |
| 1920 | |
| 1921 | <para>As shown in the above example, to call the original you must use a |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1922 | macro of the form <computeroutput>CALL_FN_*</computeroutput>. |
| 1923 | For technical reasons it is impossible |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1924 | to create a single macro to deal with all argument types and numbers, |
| 1925 | so a family of macros covering the most common cases is supplied. In |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1926 | what follows, 'W' denotes a machine-word-typed value (a pointer or a |
| 1927 | C <computeroutput>long</computeroutput>), |
| 1928 | and 'v' denotes C's <computeroutput>void</computeroutput> type. |
| 1929 | The currently available macros are:</para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1930 | |
| 1931 | <programlisting><![CDATA[ |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1932 | CALL_FN_v_v -- call an original of type void fn ( void ) |
| 1933 | CALL_FN_W_v -- call an original of type long fn ( void ) |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1934 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1935 | CALL_FN_v_W -- void fn ( long ) |
| 1936 | CALL_FN_W_W -- long fn ( long ) |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1937 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1938 | CALL_FN_v_WW -- void fn ( long, long ) |
| 1939 | CALL_FN_W_WW -- long fn ( long, long ) |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1940 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1941 | CALL_FN_v_WWW -- void fn ( long, long, long ) |
| 1942 | CALL_FN_W_WWW -- long fn ( long, long, long ) |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1943 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1944 | CALL_FN_W_WWWW -- long fn ( long, long, long, long ) |
| 1945 | CALL_FN_W_5W -- long fn ( long, long, long, long, long ) |
| 1946 | CALL_FN_W_6W -- long fn ( long, long, long, long, long, long ) |
| 1947 | and so on, up to |
| 1948 | CALL_FN_W_12W |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1949 | ]]></programlisting> |
| 1950 | |
| 1951 | <para>The set of supported types can be expanded as needed. It is |
| 1952 | regrettable that this limitation exists. Function wrapping has proven |
| 1953 | difficult to implement, with a certain apparently unavoidable level of |
| 1954 | ickyness. After several implementation attempts, the present |
| 1955 | arrangement appears to be the least-worst tradeoff. At least it works |
| 1956 | reliably in the presence of dynamic linking and dynamic code |
| 1957 | loading/unloading.</para> |
| 1958 | |
| 1959 | <para>You should not attempt to wrap a function of one type signature with a |
| 1960 | wrapper of a different type signature. Such trickery will surely lead |
| 1961 | to crashes or strange behaviour. This is not of course a limitation |
| 1962 | of the function wrapping implementation, merely a reflection of the |
| 1963 | fact that it gives you sweeping powers to shoot yourself in the foot |
| 1964 | if you are not careful. Imagine the instant havoc you could wreak by |
| 1965 | writing a wrapper which matched any function name in any soname - in |
| 1966 | effect, one which claimed to be a wrapper for all functions in the |
| 1967 | process.</para> |
| 1968 | </sect2> |
| 1969 | |
| 1970 | <sect2 id="manual-core.wrapping.examples" xreflabel="Examples"> |
| 1971 | <title>Examples</title> |
| 1972 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1973 | <para>In the source tree, |
| 1974 | <computeroutput>memcheck/tests/wrap[1-8].c</computeroutput> provide a series of |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1975 | examples, ranging from very simple to quite advanced.</para> |
| 1976 | |
sewardj | f5fa3bd | 2006-03-14 00:56:29 +0000 | [diff] [blame] | 1977 | <para><computeroutput>auxprogs/libmpiwrap.c</computeroutput> is an example |
| 1978 | of wrapping a big, complex API (the MPI-2 interface). This file defines |
| 1979 | almost 300 different wrappers.</para> |
sewardj | f5a491c | 2006-03-13 13:40:57 +0000 | [diff] [blame] | 1980 | </sect2> |
| 1981 | |
| 1982 | </sect1> |
| 1983 | |
| 1984 | |
| 1985 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1986 | <sect1 id="manual-core.install" xreflabel="Building and Installing"> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1987 | <title>Building and Installing Valgrind</title> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1988 | |
| 1989 | <para>We use the standard Unix |
| 1990 | <computeroutput>./configure</computeroutput>, |
| 1991 | <computeroutput>make</computeroutput>, <computeroutput>make |
| 1992 | install</computeroutput> mechanism, and we have attempted to |
| 1993 | ensure that it works on machines with kernel 2.4 or 2.6 and glibc |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 1994 | 2.2.X to 2.5.X. Once you have completed |
| 1995 | <computeroutput>make install</computeroutput> you may then want |
| 1996 | to run the regression tests |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 1997 | with <computeroutput>make regtest</computeroutput>. |
| 1998 | </para> |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 1999 | |
sewardj | 86e992f | 2006-01-28 18:39:09 +0000 | [diff] [blame] | 2000 | <para>There are five options (in addition to the usual |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2001 | <option>--prefix=</option> which affect how Valgrind is built: |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 2002 | <itemizedlist> |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 2003 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2004 | <listitem> |
| 2005 | <para><option>--enable-inner</option></para> |
| 2006 | <para>This builds Valgrind with some special magic hacks which make |
| 2007 | it possible to run it on a standard build of Valgrind (what the |
| 2008 | developers call "self-hosting"). Ordinarily you should not use |
| 2009 | this flag as various kinds of safety checks are disabled. |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 2010 | </para> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2011 | </listitem> |
| 2012 | |
| 2013 | <listitem> |
| 2014 | <para><option>--enable-tls</option></para> |
| 2015 | <para>TLS (Thread Local Storage) is a relatively new mechanism which |
sewardj | 86e992f | 2006-01-28 18:39:09 +0000 | [diff] [blame] | 2016 | requires compiler, linker and kernel support. Valgrind tries to |
| 2017 | automatically test if TLS is supported and if so enables this option. |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2018 | Sometimes it cannot test for TLS, so this option allows you to |
| 2019 | override the automatic test.</para> |
| 2020 | </listitem> |
| 2021 | |
| 2022 | <listitem> |
| 2023 | <para><option>--with-vex=</option></para> |
| 2024 | <para>Specifies the path to the underlying VEX dynamic-translation |
| 2025 | library. By default this is taken to be in the VEX directory off |
| 2026 | the root of the source tree. |
| 2027 | </para> |
| 2028 | </listitem> |
sewardj | 86e992f | 2006-01-28 18:39:09 +0000 | [diff] [blame] | 2029 | |
| 2030 | <listitem> |
| 2031 | <para><option>--enable-only64bit</option></para> |
| 2032 | <para><option>--enable-only32bit</option></para> |
| 2033 | <para>On 64-bit |
| 2034 | platforms (amd64-linux, ppc64-linux), Valgrind is by default built |
| 2035 | in such a way that both 32-bit and 64-bit executables can be run. |
| 2036 | Sometimes this cleverness is a problem for a variety of reasons. |
| 2037 | These two flags allow for single-target builds in this situation. |
| 2038 | If you issue both, the configure script will complain. Note they |
| 2039 | are ignored on 32-bit-only platforms (x86-linux, ppc32-linux). |
| 2040 | </para> |
| 2041 | </listitem> |
| 2042 | |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 2043 | </itemizedlist> |
| 2044 | </para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2045 | |
| 2046 | <para>The <computeroutput>configure</computeroutput> script tests |
| 2047 | the version of the X server currently indicated by the current |
| 2048 | <computeroutput>$DISPLAY</computeroutput>. This is a known bug. |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 2049 | The intention was to detect the version of the current X |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2050 | client libraries, so that correct suppressions could be selected |
| 2051 | for them, but instead the test checks the server version. This |
| 2052 | is just plain wrong.</para> |
| 2053 | |
| 2054 | <para>If you are building a binary package of Valgrind for |
| 2055 | distribution, please read <literal>README_PACKAGERS</literal> |
| 2056 | <xref linkend="dist.readme-packagers"/>. It contains some |
| 2057 | important information.</para> |
| 2058 | |
| 2059 | <para>Apart from that, there's not much excitement here. Let us |
| 2060 | know if you have build problems.</para> |
| 2061 | |
| 2062 | </sect1> |
| 2063 | |
| 2064 | |
| 2065 | |
| 2066 | <sect1 id="manual-core.problems" xreflabel="If You Have Problems"> |
| 2067 | <title>If You Have Problems</title> |
| 2068 | |
de | 252c614 | 2005-11-27 04:10:00 +0000 | [diff] [blame] | 2069 | <para>Contact us at <ulink url="&vg-url;">&vg-url;</ulink>.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2070 | |
| 2071 | <para>See <xref linkend="manual-core.limits"/> for the known |
| 2072 | limitations of Valgrind, and for a list of programs which are |
| 2073 | known not to work on it.</para> |
| 2074 | |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 2075 | <para>All parts of the system make heavy use of assertions and |
| 2076 | internal self-checks. They are permanently enabled, and we have no |
| 2077 | plans to disable them. If one of them breaks, please mail us!</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2078 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 2079 | <para>If you get an assertion failure |
| 2080 | in <filename>m_mallocfree.c</filename>, this may have happened because |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2081 | your program wrote off the end of a malloc'd block, or before its |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 2082 | beginning. Valgrind hopefully will have emitted a proper message to that |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2083 | effect before dying in this way. This is a known problem which |
| 2084 | we should fix.</para> |
| 2085 | |
de | 252c614 | 2005-11-27 04:10:00 +0000 | [diff] [blame] | 2086 | <para>Read the <xref linkend="FAQ"/> for more advice about common problems, |
| 2087 | crashes, etc.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2088 | |
| 2089 | </sect1> |
| 2090 | |
| 2091 | |
| 2092 | |
| 2093 | <sect1 id="manual-core.limits" xreflabel="Limitations"> |
| 2094 | <title>Limitations</title> |
| 2095 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2096 | <para>The following list of limitations seems long. However, most |
| 2097 | programs actually work fine.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2098 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2099 | <para>Valgrind will run Linux ELF binaries, on a kernel 2.4.X or 2.6.X |
sewardj | 7e894fd | 2006-02-13 05:15:27 +0000 | [diff] [blame] | 2100 | system, on the x86, amd64, ppc32 and ppc64 architectures, subject to the |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2101 | following constraints:</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2102 | |
| 2103 | <itemizedlist> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2104 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2105 | <para>On x86 and amd64, there is no support for 3DNow! instructions. |
| 2106 | If the translator encounters these, Valgrind will generate a SIGILL |
| 2107 | when the instruction is executed. Apart from that, on x86 and amd64, |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 2108 | essentially all instructions are supported, up to and including SSE3. |
| 2109 | </para> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2110 | |
sewardj | 7e894fd | 2006-02-13 05:15:27 +0000 | [diff] [blame] | 2111 | <para>On ppc32 and ppc64, almost all integer, floating point and Altivec |
| 2112 | instructions are supported. Specifically: integer and FP insns that are |
| 2113 | mandatory for PowerPC, the "General-purpose optional" group (fsqrt, fsqrts, |
| 2114 | stfiwx), the "Graphics optional" group (fre, fres, frsqrte, frsqrtes), and |
| 2115 | the Altivec (also known as VMX) SIMD instruction set, are supported.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2116 | </listitem> |
| 2117 | |
| 2118 | <listitem> |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 2119 | <para>Atomic instruction sequences are not properly supported, in the |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2120 | sense that their atomicity is not preserved. This will affect any |
| 2121 | use of synchronization via memory shared between processes. They |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 2122 | will appear to work, but fail sporadically.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2123 | </listitem> |
| 2124 | |
| 2125 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2126 | <para>If your program does its own memory management, rather than |
| 2127 | using malloc/new/free/delete, it should still work, but Valgrind's |
| 2128 | error checking won't be so effective. If you describe your program's |
| 2129 | memory management scheme using "client requests" |
| 2130 | (see <xref linkend="manual-core.clientreq"/>), Memcheck can do |
| 2131 | better. Nevertheless, using malloc/new and free/delete is still the |
| 2132 | best approach.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2133 | </listitem> |
| 2134 | |
| 2135 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2136 | <para>Valgrind's signal simulation is not as robust as it could be. |
| 2137 | Basic POSIX-compliant sigaction and sigprocmask functionality is |
| 2138 | supplied, but it's conceivable that things could go badly awry if you |
| 2139 | do weird things with signals. Workaround: don't. Programs that do |
| 2140 | non-POSIX signal tricks are in any case inherently unportable, so |
| 2141 | should be avoided if possible.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2142 | </listitem> |
| 2143 | |
| 2144 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2145 | <para>Machine instructions, and system calls, have been implemented |
| 2146 | on demand. So it's possible, although unlikely, that a program will |
| 2147 | fall over with a message to that effect. If this happens, please |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 2148 | report all the details printed out, so we can try and implement the |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2149 | missing feature.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2150 | </listitem> |
| 2151 | |
| 2152 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2153 | <para>Memory consumption of your program is majorly increased whilst |
| 2154 | running under Valgrind. This is due to the large amount of |
| 2155 | administrative information maintained behind the scenes. Another |
| 2156 | cause is that Valgrind dynamically translates the original |
| 2157 | executable. Translated, instrumented code is 12-18 times larger than |
| 2158 | the original so you can easily end up with 50+ MB of translations |
| 2159 | when running (eg) a web browser.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2160 | </listitem> |
| 2161 | |
| 2162 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2163 | <para>Valgrind can handle dynamically-generated code just fine. If |
| 2164 | you regenerate code over the top of old code (ie. at the same memory |
| 2165 | addresses), if the code is on the stack Valgrind will realise the |
| 2166 | code has changed, and work correctly. This is necessary to handle |
| 2167 | the trampolines GCC uses to implemented nested functions. If you |
| 2168 | regenerate code somewhere other than the stack, you will need to use |
| 2169 | the <option>--smc-check=all</option> flag, and Valgrind will run more |
| 2170 | slowly than normal.</para> |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 2171 | </listitem> |
| 2172 | |
| 2173 | <listitem> |
| 2174 | <para>As of version 3.0.0, Valgrind has the following limitations |
sewardj | 1aaadbd | 2005-11-18 21:19:46 +0000 | [diff] [blame] | 2175 | in its implementation of x86/AMD64 floating point relative to |
sewardj | 7e894fd | 2006-02-13 05:15:27 +0000 | [diff] [blame] | 2176 | IEEE754.</para> |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 2177 | |
| 2178 | <para>Precision: There is no support for 80 bit arithmetic. |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2179 | Internally, Valgrind represents all such "long double" numbers in 64 |
| 2180 | bits, and so there may be some differences in results. Whether or |
| 2181 | not this is critical remains to be seen. Note, the x86/amd64 |
| 2182 | fldt/fstpt instructions (read/write 80-bit numbers) are correctly |
| 2183 | simulated, using conversions to/from 64 bits, so that in-memory |
| 2184 | images of 80-bit numbers look correct if anyone wants to see.</para> |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 2185 | |
| 2186 | <para>The impression observed from many FP regression tests is that |
| 2187 | the accuracy differences aren't significant. Generally speaking, if |
| 2188 | a program relies on 80-bit precision, there may be difficulties |
| 2189 | porting it to non x86/amd64 platforms which only support 64-bit FP |
| 2190 | precision. Even on x86/amd64, the program may get different results |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2191 | depending on whether it is compiled to use SSE2 instructions (64-bits |
| 2192 | only), or x87 instructions (80-bit). The net effect is to make FP |
| 2193 | programs behave as if they had been run on a machine with 64-bit IEEE |
| 2194 | floats, for example PowerPC. On amd64 FP arithmetic is done by |
| 2195 | default on SSE2, so amd64 looks more like PowerPC than x86 from an FP |
| 2196 | perspective, and there are far fewer noticable accuracy differences |
| 2197 | than with x86.</para> |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 2198 | |
| 2199 | <para>Rounding: Valgrind does observe the 4 IEEE-mandated rounding |
| 2200 | modes (to nearest, to +infinity, to -infinity, to zero) for the |
| 2201 | following conversions: float to integer, integer to float where |
| 2202 | there is a possibility of loss of precision, and float-to-float |
| 2203 | rounding. For all other FP operations, only the IEEE default mode |
| 2204 | (round to nearest) is supported.</para> |
| 2205 | |
| 2206 | <para>Numeric exceptions in FP code: IEEE754 defines five types of |
| 2207 | numeric exception that can happen: invalid operation (sqrt of |
| 2208 | negative number, etc), division by zero, overflow, underflow, |
| 2209 | inexact (loss of precision).</para> |
| 2210 | |
| 2211 | <para>For each exception, two courses of action are defined by 754: |
| 2212 | either (1) a user-defined exception handler may be called, or (2) a |
| 2213 | default action is defined, which "fixes things up" and allows the |
| 2214 | computation to proceed without throwing an exception.</para> |
| 2215 | |
| 2216 | <para>Currently Valgrind only supports the default fixup actions. |
| 2217 | Again, feedback on the importance of exception support would be |
| 2218 | appreciated.</para> |
| 2219 | |
| 2220 | <para>When Valgrind detects that the program is trying to exceed any |
| 2221 | of these limitations (setting exception handlers, rounding mode, or |
| 2222 | precision control), it can print a message giving a traceback of |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2223 | where this has happened, and continue execution. This behaviour used |
| 2224 | to be the default, but the messages are annoying and so showing them |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 2225 | is now disabled by default. Use <option>--show-emwarns=yes</option> to see |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 2226 | them.</para> |
| 2227 | |
| 2228 | <para>The above limitations define precisely the IEEE754 'default' |
| 2229 | behaviour: default fixup on all exceptions, round-to-nearest |
| 2230 | operations, and 64-bit precision.</para> |
| 2231 | </listitem> |
| 2232 | |
| 2233 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2234 | <para>As of version 3.0.0, Valgrind has the following limitations in |
sewardj | 7e894fd | 2006-02-13 05:15:27 +0000 | [diff] [blame] | 2235 | its implementation of x86/AMD64 SSE2 FP arithmetic, relative to |
| 2236 | IEEE754.</para> |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 2237 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2238 | <para>Essentially the same: no exceptions, and limited observance of |
| 2239 | rounding mode. Also, SSE2 has control bits which make it treat |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 2240 | denormalised numbers as zero (DAZ) and a related action, flush |
| 2241 | denormals to zero (FTZ). Both of these cause SSE2 arithmetic to be |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2242 | less accurate than IEEE requires. Valgrind detects, ignores, and can |
| 2243 | warn about, attempts to enable either mode.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2244 | </listitem> |
| 2245 | |
sewardj | 1aaadbd | 2005-11-18 21:19:46 +0000 | [diff] [blame] | 2246 | <listitem> |
sewardj | 7e894fd | 2006-02-13 05:15:27 +0000 | [diff] [blame] | 2247 | <para>As of version 3.2.0, Valgrind has the following limitations |
| 2248 | in its implementation of PPC32 and PPC64 floating point |
| 2249 | arithmetic, relative to IEEE754.</para> |
sewardj | 1aaadbd | 2005-11-18 21:19:46 +0000 | [diff] [blame] | 2250 | |
sewardj | 7e894fd | 2006-02-13 05:15:27 +0000 | [diff] [blame] | 2251 | <para>Scalar (non-Altivec): Valgrind provides a bit-exact emulation of |
| 2252 | all floating point instructions, except for "fre" and "fres", which are |
| 2253 | done more precisely than required by the PowerPC architecture specification. |
| 2254 | All floating point operations observe the current rounding mode. |
| 2255 | </para> |
| 2256 | |
| 2257 | <para>However, fpscr[FPRF] is not set after each operation. That could |
| 2258 | be done but would give measurable performance overheads, and so far |
| 2259 | no need for it has been found.</para> |
| 2260 | |
| 2261 | <para>As on x86/AMD64, IEEE754 exceptions are not supported: all floating |
| 2262 | point exceptions are handled using the default IEEE fixup actions. |
| 2263 | Valgrind detects, ignores, and can warn about, attempts to unmask |
| 2264 | the 5 IEEE FP exception kinds by writing to the floating-point status |
| 2265 | and control register (fpscr). |
| 2266 | </para> |
| 2267 | |
| 2268 | <para>Vector (Altivec, VMX): essentially as with x86/AMD64 SSE/SSE2: |
| 2269 | no exceptions, and limited observance of rounding mode. |
| 2270 | For Altivec, FP arithmetic |
sewardj | 1aaadbd | 2005-11-18 21:19:46 +0000 | [diff] [blame] | 2271 | is done in IEEE/Java mode, which is more accurate than the Linux default |
| 2272 | setting. "More accurate" means that denormals are handled properly, |
sewardj | 7e894fd | 2006-02-13 05:15:27 +0000 | [diff] [blame] | 2273 | rather than simply being flushed to zero.</para> |
sewardj | 1aaadbd | 2005-11-18 21:19:46 +0000 | [diff] [blame] | 2274 | </listitem> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2275 | </itemizedlist> |
| 2276 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2277 | <para>Programs which are known not to work are:</para> |
| 2278 | <itemizedlist> |
| 2279 | <listitem> |
| 2280 | <para>emacs starts up but immediately concludes it is out of |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 2281 | memory and aborts. It may be that Memcheck does not provide |
| 2282 | a good enough emulation of the |
| 2283 | <computeroutput>mallinfo</computeroutput> function. |
| 2284 | Emacs works fine if you build it to use |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2285 | the standard malloc/free routines.</para> |
| 2286 | </listitem> |
| 2287 | </itemizedlist> |
| 2288 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2289 | </sect1> |
| 2290 | |
| 2291 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2292 | <sect1 id="manual-core.example" xreflabel="An Example Run"> |
| 2293 | <title>An Example Run</title> |
| 2294 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 2295 | <para>This is the log for a run of a small program using Memcheck. |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2296 | The program is in fact correct, and the reported error is as the |
| 2297 | result of a potentially serious code generation bug in GNU g++ |
| 2298 | (snapshot 20010527).</para> |
| 2299 | |
| 2300 | <programlisting><![CDATA[ |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 2301 | sewardj@phoenix:~/newmat10$ ~/Valgrind-6/valgrind -v ./bogon |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2302 | ==25832== Valgrind 0.10, a memory error detector for x86 RedHat 7.1. |
| 2303 | ==25832== Copyright (C) 2000-2001, and GNU GPL'd, by Julian Seward. |
| 2304 | ==25832== Startup, with flags: |
| 2305 | ==25832== --suppressions=/home/sewardj/Valgrind/redhat71.supp |
| 2306 | ==25832== reading syms from /lib/ld-linux.so.2 |
| 2307 | ==25832== reading syms from /lib/libc.so.6 |
| 2308 | ==25832== reading syms from /mnt/pima/jrs/Inst/lib/libgcc_s.so.0 |
| 2309 | ==25832== reading syms from /lib/libm.so.6 |
| 2310 | ==25832== reading syms from /mnt/pima/jrs/Inst/lib/libstdc++.so.3 |
| 2311 | ==25832== reading syms from /home/sewardj/Valgrind/valgrind.so |
| 2312 | ==25832== reading syms from /proc/self/exe |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2313 | ==25832== |
| 2314 | ==25832== Invalid read of size 4 |
| 2315 | ==25832== at 0x8048724: _ZN10BandMatrix6ReSizeEiii (bogon.cpp:45) |
| 2316 | ==25832== by 0x80487AF: main (bogon.cpp:66) |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 2317 | ==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2318 | ==25832== |
| 2319 | ==25832== ERROR SUMMARY: 1 errors from 1 contexts (suppressed: 0 from 0) |
| 2320 | ==25832== malloc/free: in use at exit: 0 bytes in 0 blocks. |
| 2321 | ==25832== malloc/free: 0 allocs, 0 frees, 0 bytes allocated. |
| 2322 | ==25832== For a detailed leak analysis, rerun with: --leak-check=yes |
| 2323 | ==25832== |
| 2324 | ==25832== exiting, did 1881 basic blocks, 0 misses. |
| 2325 | ==25832== 223 translations, 3626 bytes in, 56801 bytes out.]]></programlisting> |
| 2326 | |
| 2327 | <para>The GCC folks fixed this about a week before gcc-3.0 |
| 2328 | shipped.</para> |
| 2329 | |
| 2330 | </sect1> |
| 2331 | |
| 2332 | |
| 2333 | <sect1 id="manual-core.warnings" xreflabel="Warning Messages"> |
| 2334 | <title>Warning Messages You Might See</title> |
| 2335 | |
| 2336 | <para>Most of these only appear if you run in verbose mode |
| 2337 | (enabled by <computeroutput>-v</computeroutput>):</para> |
| 2338 | |
| 2339 | <itemizedlist> |
| 2340 | |
| 2341 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2342 | <para><computeroutput>More than 100 errors detected. Subsequent |
| 2343 | errors will still be recorded, but in less detail than |
| 2344 | before.</computeroutput></para> |
| 2345 | |
| 2346 | <para>After 100 different errors have been shown, Valgrind becomes |
| 2347 | more conservative about collecting them. It then requires only the |
| 2348 | program counters in the top two stack frames to match when deciding |
| 2349 | whether or not two errors are really the same one. Prior to this |
| 2350 | point, the PCs in the top four frames are required to match. This |
| 2351 | hack has the effect of slowing down the appearance of new errors |
| 2352 | after the first 100. The 100 constant can be changed by recompiling |
| 2353 | Valgrind.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2354 | </listitem> |
| 2355 | |
| 2356 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2357 | <para><computeroutput>More than 1000 errors detected. I'm not |
| 2358 | reporting any more. Final error counts may be inaccurate. Go fix |
| 2359 | your program!</computeroutput></para> |
| 2360 | |
| 2361 | <para>After 1000 different errors have been detected, Valgrind |
| 2362 | ignores any more. It seems unlikely that collecting even more |
| 2363 | different ones would be of practical help to anybody, and it avoids |
| 2364 | the danger that Valgrind spends more and more of its time comparing |
| 2365 | new errors against an ever-growing collection. As above, the 1000 |
| 2366 | number is a compile-time constant.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2367 | </listitem> |
| 2368 | |
| 2369 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2370 | <para><computeroutput>Warning: client switching stacks?</computeroutput></para> |
| 2371 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 2372 | <para>Valgrind spotted such a large change in the stack pointer |
| 2373 | that it guesses the client is switching to |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2374 | a different stack. At this point it makes a kludgey guess where the |
| 2375 | base of the new stack is, and sets memory permissions accordingly. |
| 2376 | You may get many bogus error messages following this, if Valgrind |
| 2377 | guesses wrong. At the moment "large change" is defined as a change |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 2378 | of more that 2000000 in the value of the |
| 2379 | stack pointer register.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2380 | </listitem> |
| 2381 | |
| 2382 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2383 | <para><computeroutput>Warning: client attempted to close Valgrind's |
| 2384 | logfile fd <number></computeroutput></para> |
| 2385 | |
| 2386 | <para>Valgrind doesn't allow the client to close the logfile, |
| 2387 | because you'd never see any diagnostic information after that point. |
| 2388 | If you see this message, you may want to use the |
| 2389 | <option>--log-fd=<number></option> option to specify a |
| 2390 | different logfile file-descriptor number.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2391 | </listitem> |
| 2392 | |
| 2393 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2394 | <para><computeroutput>Warning: noted but unhandled ioctl |
| 2395 | <number></computeroutput></para> |
| 2396 | |
| 2397 | <para>Valgrind observed a call to one of the vast family of |
| 2398 | <computeroutput>ioctl</computeroutput> system calls, but did not |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 2399 | modify its memory status info (because nobody has yet written a |
| 2400 | suitable wrapper). The call will still have gone through, but you may get |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2401 | spurious errors after this as a result of the non-update of the |
| 2402 | memory info.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2403 | </listitem> |
| 2404 | |
| 2405 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 2406 | <para><computeroutput>Warning: set address range perms: large range |
| 2407 | <number></computeroutput></para> |
| 2408 | |
| 2409 | <para>Diagnostic message, mostly for benefit of the Valgrind |
| 2410 | developers, to do with memory permissions.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2411 | </listitem> |
| 2412 | |
| 2413 | </itemizedlist> |
| 2414 | |
| 2415 | </sect1> |
de | 9bec93c | 2005-11-25 05:36:48 +0000 | [diff] [blame] | 2416 | |
sewardj | a737e65 | 2006-03-19 18:19:11 +0000 | [diff] [blame] | 2417 | |
| 2418 | <sect1 id="manual-core.mpiwrap" xreflabel="MPI Wrappers"> |
| 2419 | <title>Debugging MPI Parallel Programs with Valgrind</title> |
| 2420 | |
| 2421 | <para> Valgrind supports debugging of distributed-memory applications |
| 2422 | which use the MPI message passing standard. This support consists of a |
| 2423 | library of wrapper functions for the |
| 2424 | <computeroutput>PMPI_*</computeroutput> interface. When incorporated |
| 2425 | into the application's address space, either by direct linking or by |
| 2426 | <computeroutput>LD_PRELOAD</computeroutput>, the wrappers intercept |
| 2427 | calls to <computeroutput>PMPI_Send</computeroutput>, |
| 2428 | <computeroutput>PMPI_Recv</computeroutput>, etc. They then |
| 2429 | use client requests to inform Valgrind of memory state changes caused |
| 2430 | by the function being wrapped. This reduces the number of false |
| 2431 | positives that Memcheck otherwise typically reports for MPI |
| 2432 | applications.</para> |
| 2433 | |
| 2434 | <para>The wrappers also take the opportunity to carefully check |
| 2435 | size and definedness of buffers passed as arguments to MPI functions, hence |
| 2436 | detecting errors such as passing undefined data to |
| 2437 | <computeroutput>PMPI_Send</computeroutput>, or receiving data into a |
| 2438 | buffer which is too small.</para> |
| 2439 | |
njn | 7fd15d6 | 2006-03-31 12:05:04 +0000 | [diff] [blame] | 2440 | <para>Unlike most of the rest of Valgrind, the wrapper library is subject to a |
sewardj | 7d08465 | 2006-03-20 00:54:54 +0000 | [diff] [blame] | 2441 | BSD-style license, so you can link it into any code base you like. |
| 2442 | See the top of <computeroutput>auxprogs/libmpiwrap.c</computeroutput> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 2443 | for license details.</para> |
sewardj | 7d08465 | 2006-03-20 00:54:54 +0000 | [diff] [blame] | 2444 | |
sewardj | a737e65 | 2006-03-19 18:19:11 +0000 | [diff] [blame] | 2445 | |
| 2446 | <sect2 id="manual-core.mpiwrap.build" xreflabel="Building MPI Wrappers"> |
| 2447 | <title>Building and installing the wrappers</title> |
| 2448 | |
| 2449 | <para> The wrapper library will be built automatically if possible. |
| 2450 | Valgrind's configure script will look for a suitable |
| 2451 | <computeroutput>mpicc</computeroutput> to build it with. This must be |
| 2452 | the same <computeroutput>mpicc</computeroutput> you use to build the |
| 2453 | MPI application you want to debug. By default, Valgrind tries |
| 2454 | <computeroutput>mpicc</computeroutput>, but you can specify a |
| 2455 | different one by using the configure-time flag |
| 2456 | <computeroutput>--with-mpicc=</computeroutput>. Currently the |
| 2457 | wrappers are only buildable with |
| 2458 | <computeroutput>mpicc</computeroutput>s which are based on GNU |
| 2459 | <computeroutput>gcc</computeroutput> or Intel's |
| 2460 | <computeroutput>icc</computeroutput>.</para> |
| 2461 | |
| 2462 | <para>Check that the configure script prints a line like this:</para> |
| 2463 | |
| 2464 | <programlisting><![CDATA[ |
| 2465 | checking for usable MPI2-compliant mpicc and mpi.h... yes, mpicc |
| 2466 | ]]></programlisting> |
| 2467 | |
| 2468 | <para>If it says <computeroutput>... no</computeroutput>, your |
| 2469 | <computeroutput>mpicc</computeroutput> has failed to compile and link |
| 2470 | a test MPI2 program.</para> |
| 2471 | |
| 2472 | <para>If the configure test succeeds, continue in the usual way with |
| 2473 | <computeroutput>make</computeroutput> and <computeroutput>make |
| 2474 | install</computeroutput>. The final install tree should then contain |
| 2475 | <computeroutput>libmpiwrap.so</computeroutput>. |
| 2476 | </para> |
| 2477 | |
| 2478 | <para>Compile up a test MPI program (eg, MPI hello-world) and try |
| 2479 | this:</para> |
| 2480 | |
| 2481 | <programlisting><![CDATA[ |
| 2482 | LD_PRELOAD=$prefix/lib/valgrind/<platform>/libmpiwrap.so \ |
| 2483 | mpirun [args] $prefix/bin/valgrind ./hello |
| 2484 | ]]></programlisting> |
| 2485 | |
| 2486 | <para>You should see something similar to the following</para> |
| 2487 | |
| 2488 | <programlisting><![CDATA[ |
| 2489 | valgrind MPI wrappers 31901: Active for pid 31901 |
| 2490 | valgrind MPI wrappers 31901: Try MPIWRAP_DEBUG=help for possible options |
| 2491 | ]]></programlisting> |
| 2492 | |
| 2493 | <para>repeated for every process in the group. If you do not see |
| 2494 | these, there is an build/installation problem of some kind.</para> |
| 2495 | |
| 2496 | <para> The MPI functions to be wrapped are assumed to be in an ELF |
| 2497 | shared object with soname matching |
| 2498 | <computeroutput>libmpi.so*</computeroutput>. This is known to be |
| 2499 | correct at least for Open MPI and Quadrics MPI, and can easily be |
| 2500 | changed if required.</para> |
| 2501 | </sect2> |
| 2502 | |
| 2503 | |
| 2504 | <sect2 id="manual-core.mpiwrap.gettingstarted" |
| 2505 | xreflabel="Getting started with MPI Wrappers"> |
| 2506 | <title>Getting started</title> |
| 2507 | |
| 2508 | <para>Compile your MPI application as usual, taking care to link it |
| 2509 | using the same <computeroutput>mpicc</computeroutput> that your |
| 2510 | Valgrind build was configured with.</para> |
| 2511 | |
| 2512 | <para> |
| 2513 | Use the following basic scheme to run your application on Valgrind with |
| 2514 | the wrappers engaged:</para> |
| 2515 | |
| 2516 | <programlisting><![CDATA[ |
| 2517 | MPIWRAP_DEBUG=[wrapper-args] \ |
| 2518 | LD_PRELOAD=$prefix/lib/valgrind/<platform>/libmpiwrap.so \ |
| 2519 | mpirun [mpirun-args] \ |
| 2520 | $prefix/bin/valgrind [valgrind-args] \ |
| 2521 | [application] [app-args] |
| 2522 | ]]></programlisting> |
| 2523 | |
| 2524 | <para>As an alternative to |
| 2525 | <computeroutput>LD_PRELOAD</computeroutput>ing |
| 2526 | <computeroutput>libmpiwrap.so</computeroutput>, you can simply link it |
| 2527 | to your application if desired. This should not disturb native |
| 2528 | behaviour of your application in any way.</para> |
| 2529 | </sect2> |
| 2530 | |
| 2531 | |
| 2532 | <sect2 id="manual-core.mpiwrap.controlling" |
| 2533 | xreflabel="Controlling the MPI Wrappers"> |
| 2534 | <title>Controlling the wrapper library</title> |
| 2535 | |
| 2536 | <para>Environment variable |
| 2537 | <computeroutput>MPIWRAP_DEBUG</computeroutput> is consulted at |
| 2538 | startup. The default behaviour is to print a starting banner</para> |
| 2539 | |
| 2540 | <programlisting><![CDATA[ |
| 2541 | valgrind MPI wrappers 16386: Active for pid 16386 |
| 2542 | valgrind MPI wrappers 16386: Try MPIWRAP_DEBUG=help for possible options |
| 2543 | ]]></programlisting> |
| 2544 | |
| 2545 | <para> and then be relatively quiet.</para> |
| 2546 | |
| 2547 | <para>You can give a list of comma-separated options in |
| 2548 | <computeroutput>MPIWRAP_DEBUG</computeroutput>. These are</para> |
| 2549 | |
| 2550 | <itemizedlist> |
| 2551 | <listitem> |
| 2552 | <para><computeroutput>verbose</computeroutput>: |
| 2553 | show entries/exits of all wrappers. Also show extra |
| 2554 | debugging info, such as the status of outstanding |
| 2555 | <computeroutput>MPI_Request</computeroutput>s resulting |
| 2556 | from uncompleted <computeroutput>MPI_Irecv</computeroutput>s.</para> |
| 2557 | </listitem> |
| 2558 | <listitem> |
| 2559 | <para><computeroutput>quiet</computeroutput>: |
| 2560 | opposite of <computeroutput>verbose</computeroutput>, only print |
| 2561 | anything when the wrappers want |
| 2562 | to report a detected programming error, or in case of catastrophic |
| 2563 | failure of the wrappers.</para> |
| 2564 | </listitem> |
| 2565 | <listitem> |
| 2566 | <para><computeroutput>warn</computeroutput>: |
| 2567 | by default, functions which lack proper wrappers |
| 2568 | are not commented on, just silently |
| 2569 | ignored. This causes a warning to be printed for each unwrapped |
| 2570 | function used, up to a maximum of three warnings per function.</para> |
| 2571 | </listitem> |
| 2572 | <listitem> |
| 2573 | <para><computeroutput>strict</computeroutput>: |
| 2574 | print an error message and abort the program if |
| 2575 | a function lacking a wrapper is used.</para> |
| 2576 | </listitem> |
| 2577 | </itemizedlist> |
| 2578 | |
| 2579 | <para> If you want to use Valgrind's XML output facility |
| 2580 | (<computeroutput>--xml=yes</computeroutput>), you should pass |
| 2581 | <computeroutput>quiet</computeroutput> in |
| 2582 | <computeroutput>MPIWRAP_DEBUG</computeroutput> so as to get rid of any |
| 2583 | extraneous printing from the wrappers.</para> |
| 2584 | |
| 2585 | </sect2> |
| 2586 | |
| 2587 | |
| 2588 | <sect2 id="manual-core.mpiwrap.limitations" |
| 2589 | xreflabel="Abilities and Limitations of MPI Wrappers"> |
| 2590 | <title>Abilities and limitations</title> |
| 2591 | |
| 2592 | <sect3> |
| 2593 | <title>Functions</title> |
| 2594 | |
| 2595 | <para>All MPI2 functions except |
| 2596 | <computeroutput>MPI_Wtick</computeroutput>, |
| 2597 | <computeroutput>MPI_Wtime</computeroutput> and |
| 2598 | <computeroutput>MPI_Pcontrol</computeroutput> have wrappers. The |
| 2599 | first two are not wrapped because they return a |
| 2600 | <computeroutput>double</computeroutput>, and Valgrind's |
| 2601 | function-wrap mechanism cannot handle that (it could easily enough be |
| 2602 | extended to). <computeroutput>MPI_Pcontrol</computeroutput> cannot be |
| 2603 | wrapped as it has variable arity: |
| 2604 | <computeroutput>int MPI_Pcontrol(const int level, ...)</computeroutput></para> |
| 2605 | |
| 2606 | <para>Most functions are wrapped with a default wrapper which does |
| 2607 | nothing except complain or abort if it is called, depending on |
| 2608 | settings in <computeroutput>MPIWRAP_DEBUG</computeroutput> listed |
| 2609 | above. The following functions have "real", do-something-useful |
| 2610 | wrappers:</para> |
| 2611 | |
| 2612 | <programlisting><![CDATA[ |
| 2613 | PMPI_Send PMPI_Bsend PMPI_Ssend PMPI_Rsend |
| 2614 | |
| 2615 | PMPI_Recv PMPI_Get_count |
| 2616 | |
| 2617 | PMPI_Isend PMPI_Ibsend PMPI_Issend PMPI_Irsend |
| 2618 | |
| 2619 | PMPI_Irecv |
| 2620 | PMPI_Wait PMPI_Waitall |
| 2621 | PMPI_Test PMPI_Testall |
| 2622 | |
| 2623 | PMPI_Iprobe PMPI_Probe |
| 2624 | |
| 2625 | PMPI_Cancel |
| 2626 | |
| 2627 | PMPI_Sendrecv |
| 2628 | |
| 2629 | PMPI_Type_commit PMPI_Type_free |
| 2630 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 2631 | PMPI_Pack PMPI_Unpack |
| 2632 | |
sewardj | a737e65 | 2006-03-19 18:19:11 +0000 | [diff] [blame] | 2633 | PMPI_Bcast PMPI_Gather PMPI_Scatter PMPI_Alltoall |
| 2634 | PMPI_Reduce PMPI_Allreduce PMPI_Op_create |
| 2635 | |
| 2636 | PMPI_Comm_create PMPI_Comm_dup PMPI_Comm_free PMPI_Comm_rank PMPI_Comm_size |
| 2637 | |
| 2638 | PMPI_Error_string |
| 2639 | PMPI_Init PMPI_Initialized PMPI_Finalize |
| 2640 | ]]></programlisting> |
| 2641 | |
| 2642 | <para> A few functions such as |
| 2643 | <computeroutput>PMPI_Address</computeroutput> are listed as |
| 2644 | <computeroutput>HAS_NO_WRAPPER</computeroutput>. They have no wrapper |
| 2645 | at all as there is nothing worth checking, and giving a no-op wrapper |
| 2646 | would reduce performance for no reason.</para> |
| 2647 | |
| 2648 | <para> Note that the wrapper library itself can itself generate large |
| 2649 | numbers of calls to the MPI implementation, especially when walking |
| 2650 | complex types. The most common functions called are |
| 2651 | <computeroutput>PMPI_Extent</computeroutput>, |
| 2652 | <computeroutput>PMPI_Type_get_envelope</computeroutput>, |
| 2653 | <computeroutput>PMPI_Type_get_contents</computeroutput>, and |
| 2654 | <computeroutput>PMPI_Type_free</computeroutput>. </para> |
| 2655 | </sect3> |
| 2656 | |
| 2657 | <sect3> |
| 2658 | <title>Types</title> |
| 2659 | |
| 2660 | <para> MPI-1.1 structured types are supported, and walked exactly. |
| 2661 | The currently supported combiners are |
| 2662 | <computeroutput>MPI_COMBINER_NAMED</computeroutput>, |
| 2663 | <computeroutput>MPI_COMBINER_CONTIGUOUS</computeroutput>, |
| 2664 | <computeroutput>MPI_COMBINER_VECTOR</computeroutput>, |
| 2665 | <computeroutput>MPI_COMBINER_HVECTOR</computeroutput> |
| 2666 | <computeroutput>MPI_COMBINER_INDEXED</computeroutput>, |
| 2667 | <computeroutput>MPI_COMBINER_HINDEXED</computeroutput> and |
| 2668 | <computeroutput>MPI_COMBINER_STRUCT</computeroutput>. This should |
| 2669 | cover all MPI-1.1 types. The mechanism (function |
| 2670 | <computeroutput>walk_type</computeroutput>) should extend easily to |
| 2671 | cover MPI2 combiners.</para> |
| 2672 | |
| 2673 | <para>MPI defines some named structured types |
| 2674 | (<computeroutput>MPI_FLOAT_INT</computeroutput>, |
| 2675 | <computeroutput>MPI_DOUBLE_INT</computeroutput>, |
| 2676 | <computeroutput>MPI_LONG_INT</computeroutput>, |
| 2677 | <computeroutput>MPI_2INT</computeroutput>, |
| 2678 | <computeroutput>MPI_SHORT_INT</computeroutput>, |
| 2679 | <computeroutput>MPI_LONG_DOUBLE_INT</computeroutput>) which are pairs |
| 2680 | of some basic type and a C <computeroutput>int</computeroutput>. |
| 2681 | Unfortunately the MPI specification makes it impossible to look inside |
| 2682 | these types and see where the fields are. Therefore these wrappers |
| 2683 | assume the types are laid out as <computeroutput>struct { float val; |
| 2684 | int loc; }</computeroutput> (for |
| 2685 | <computeroutput>MPI_FLOAT_INT</computeroutput>), etc, and act |
| 2686 | accordingly. This appears to be correct at least for Open MPI 1.0.2 |
| 2687 | and for Quadrics MPI.</para> |
| 2688 | |
| 2689 | <para>If <computeroutput>strict</computeroutput> is an option specified |
| 2690 | in <computeroutput>MPIWRAP_DEBUG</computeroutput>, the application |
| 2691 | will abort if an unhandled type is encountered. Otherwise, the |
| 2692 | application will print a warning message and continue.</para> |
| 2693 | |
| 2694 | <para>Some effort is made to mark/check memory ranges corresponding to |
| 2695 | arrays of values in a single pass. This is important for performance |
| 2696 | since asking Valgrind to mark/check any range, no matter how small, |
| 2697 | carries quite a large constant cost. This optimisation is applied to |
| 2698 | arrays of primitive types (<computeroutput>double</computeroutput>, |
| 2699 | <computeroutput>float</computeroutput>, |
| 2700 | <computeroutput>int</computeroutput>, |
| 2701 | <computeroutput>long</computeroutput>, <computeroutput>long |
| 2702 | long</computeroutput>, <computeroutput>short</computeroutput>, |
| 2703 | <computeroutput>char</computeroutput>, and <computeroutput>long |
| 2704 | double</computeroutput> on platforms where <computeroutput>sizeof(long |
| 2705 | double) == 8</computeroutput>). For arrays of all other types, the |
| 2706 | wrappers handle each element individually and so there can be a very |
| 2707 | large performance cost.</para> |
| 2708 | |
| 2709 | </sect3> |
| 2710 | |
| 2711 | </sect2> |
| 2712 | |
| 2713 | |
| 2714 | <sect2 id="manual-core.mpiwrap.writingwrappers" |
| 2715 | xreflabel="Writing new MPI Wrappers"> |
| 2716 | <title>Writing new wrappers</title> |
| 2717 | |
| 2718 | <para> |
| 2719 | For the most part the wrappers are straightforward. The only |
| 2720 | significant complexity arises with nonblocking receives.</para> |
| 2721 | |
| 2722 | <para>The issue is that <computeroutput>MPI_Irecv</computeroutput> |
| 2723 | states the recv buffer and returns immediately, giving a handle |
| 2724 | (<computeroutput>MPI_Request</computeroutput>) for the transaction. |
| 2725 | Later the user will have to poll for completion with |
| 2726 | <computeroutput>MPI_Wait</computeroutput> etc, and when the |
| 2727 | transaction completes successfully, the wrappers have to paint the |
| 2728 | recv buffer. But the recv buffer details are not presented to |
| 2729 | <computeroutput>MPI_Wait</computeroutput> -- only the handle is. The |
| 2730 | library therefore maintains a shadow table which associates |
| 2731 | uncompleted <computeroutput>MPI_Request</computeroutput>s with the |
| 2732 | corresponding buffer address/count/type. When an operation completes, |
| 2733 | the table is searched for the associated address/count/type info, and |
| 2734 | memory is marked accordingly.</para> |
| 2735 | |
| 2736 | <para>Access to the table is guarded by a (POSIX pthreads) lock, so as |
| 2737 | to make the library thread-safe.</para> |
| 2738 | |
| 2739 | <para>The table is allocated with |
| 2740 | <computeroutput>malloc</computeroutput> and never |
| 2741 | <computeroutput>free</computeroutput>d, so it will show up in leak |
| 2742 | checks.</para> |
| 2743 | |
| 2744 | <para>Writing new wrappers should be fairly easy. The source file is |
| 2745 | <computeroutput>auxprogs/libmpiwrap.c</computeroutput>. If possible, |
| 2746 | find an existing wrapper for a function of similar behaviour to the |
| 2747 | one you want to wrap, and use it as a starting point. The wrappers |
| 2748 | are organised in sections in the same order as the MPI 1.1 spec, to |
| 2749 | aid navigation. When adding a wrapper, remember to comment out the |
| 2750 | definition of the default wrapper in the long list of defaults at the |
| 2751 | bottom of the file (do not remove it, just comment it out).</para> |
| 2752 | </sect2> |
| 2753 | |
| 2754 | <sect2 id="manual-core.mpiwrap.whattoexpect" |
| 2755 | xreflabel="What to expect with MPI Wrappers"> |
| 2756 | <title>What to expect when using the wrappers</title> |
| 2757 | |
| 2758 | <para>The wrappers should reduce Memcheck's false-error rate on MPI |
| 2759 | applications. Because the wrapping is done at the MPI interface, |
| 2760 | there will still potentially be a large number of errors reported in |
| 2761 | the MPI implementation below the interface. The best you can do is |
| 2762 | try to suppress them.</para> |
| 2763 | |
| 2764 | <para>You may also find that the input-side (buffer |
| 2765 | length/definedness) checks find errors in your MPI use, for example |
| 2766 | passing too short a buffer to |
| 2767 | <computeroutput>MPI_Recv</computeroutput>.</para> |
| 2768 | |
| 2769 | <para>Functions which are not wrapped may increase the false |
| 2770 | error rate. A possible approach is to run with |
| 2771 | <computeroutput>MPI_DEBUG</computeroutput> containing |
| 2772 | <computeroutput>warn</computeroutput>. This will show you functions |
| 2773 | which lack proper wrappers but which are nevertheless used. You can |
| 2774 | then write wrappers for them. |
| 2775 | </para> |
| 2776 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 2777 | <para>A known source of potential false errors are the |
| 2778 | <computeroutput>PMPI_Reduce</computeroutput> family of functions, when |
| 2779 | using a custom (user-defined) reduction function. In a reduction |
| 2780 | operation, each node notionally sends data to a "central point" which |
| 2781 | uses the specified reduction function to merge the data items into a |
| 2782 | single item. Hence, in general, data is passed between nodes and fed |
| 2783 | to the reduction function, but the wrapper library cannot mark the |
| 2784 | transferred data as initialised before it is handed to the reduction |
| 2785 | function, because all that happens "inside" the |
| 2786 | <computeroutput>PMPI_Reduce</computeroutput> call. As a result you |
| 2787 | may see false positives reported in your reduction function.</para> |
| 2788 | |
sewardj | a737e65 | 2006-03-19 18:19:11 +0000 | [diff] [blame] | 2789 | </sect2> |
| 2790 | |
| 2791 | </sect1> |
| 2792 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 2793 | </chapter> |