de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 1 | <?xml version="1.0"?> <!-- -*- sgml -*- --> |
| 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| 3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| 4 | [ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]> |
| 5 | |
| 6 | |
| 7 | <refentry id="valgrind"> |
| 8 | |
| 9 | <refmeta> |
| 10 | <refentrytitle>VALGRIND</refentrytitle> |
| 11 | <manvolnum>1</manvolnum> |
| 12 | <refmiscinfo>Release &rel-version;</refmiscinfo> |
| 13 | </refmeta> |
| 14 | |
| 15 | <refnamediv> |
| 16 | <refname>valgrind</refname> |
| 17 | <refpurpose>a suite of tools for debugging and profiling programs</refpurpose> |
| 18 | </refnamediv> |
| 19 | |
| 20 | <refsynopsisdiv> |
| 21 | <cmdsynopsis> |
| 22 | <command>valgrind</command> |
| 23 | <arg> |
| 24 | <arg><replaceable>valgrind</replaceable></arg> |
| 25 | <arg><replaceable>options</replaceable></arg> |
| 26 | </arg> |
| 27 | <arg><replaceable>your-program</replaceable></arg> |
| 28 | <arg> |
| 29 | <arg><replaceable>your-program-options</replaceable></arg> |
| 30 | </arg> |
| 31 | </cmdsynopsis> |
| 32 | </refsynopsisdiv> |
| 33 | |
| 34 | |
| 35 | <refsect1 id="description"> |
| 36 | <title>Description</title> |
| 37 | |
| 38 | <para><command>Valgrind</command> is a flexible program for debugging |
| 39 | and profiling Linux executables. It consists of a core, which provides |
| 40 | a synthetic CPU in software, and a series of "tools", each of which is a |
| 41 | debugging or profiling tool. The architecture is modular, so that new |
| 42 | tools can be created easily and without disturbing the existing |
| 43 | structure.</para> |
| 44 | |
| 45 | <para>This manual page covers only basic usage and options. For more |
| 46 | comprehensive information, please see the HTML documentation on your |
| 47 | system: <filename>&vg-doc-path;</filename>, or online: |
| 48 | <filename>&vg-bookset;</filename>.</para> |
| 49 | |
| 50 | </refsect1> |
| 51 | |
| 52 | |
| 53 | <refsect1 id="invocation"> |
| 54 | <title>Invocation</title> |
| 55 | |
| 56 | <para><command>Valgrind</command> is typically invoked as follows: |
| 57 | <literallayout> valgrind program args</literallayout> |
| 58 | |
| 59 | This runs <command>program</command> (with arguments |
| 60 | <command>args</command>) under Valgrind using the Memcheck tool. |
| 61 | Memcheck performs a range of memory-checking functions, including |
| 62 | detecting accesses to uninitialised memory, misuse of allocated memory |
| 63 | (double frees, access after free, etc.) and detecting memory |
| 64 | leaks.</para> |
| 65 | |
| 66 | <para>To use a different tool, use the <option>--tool</option> option: |
| 67 | <literallayout> valgrind --tool=toolname program args</literallayout></para> |
| 68 | |
| 69 | <para>The following tools are available:</para> |
| 70 | |
| 71 | <itemizedlist> |
| 72 | |
| 73 | <listitem> |
| 74 | <para><option>cachegrind</option> is a cache simulator. It can be |
| 75 | used to annotate every line of your program with the number of |
| 76 | instructions executed and cache misses incurred.</para> |
| 77 | </listitem> |
| 78 | |
| 79 | <listitem> |
| 80 | <para><option>helgrind</option> spots potential race conditions in |
| 81 | your program.</para> |
| 82 | </listitem> |
| 83 | |
| 84 | <listitem> |
| 85 | <para><option>lackey</option> is a sample tool that can be used as a |
| 86 | template for generating your own tools. After the program |
| 87 | terminates, it prints out some basic statistics about the program |
| 88 | execution.</para> |
| 89 | </listitem> |
| 90 | |
| 91 | <listitem> |
| 92 | <para><option>massif</option> is a heap profiler. It measures how |
| 93 | much heap memory your program uses.</para> |
| 94 | </listitem> |
| 95 | |
| 96 | <listitem> |
| 97 | <para><option>memcheck</option> is a fine-grained memory checker.</para> |
| 98 | </listitem> |
| 99 | |
| 100 | <listitem> |
| 101 | <para><option>none</option> performs no function - it simply runs |
| 102 | the program under Valgrind. This is typically used for debugging |
| 103 | and benchmarking Valgrind.</para> |
| 104 | </listitem> |
| 105 | |
| 106 | </itemizedlist> |
| 107 | |
| 108 | </refsect1> |
| 109 | |
| 110 | |
| 111 | |
| 112 | <refsect1 id="basic-options"> |
| 113 | <title>Basic Options</title> |
| 114 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 115 | <xi:include href="manual-core.xml" xpointer="basic.opts.para" |
| 116 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 117 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 118 | <xi:include href="manual-core.xml" xpointer="basic.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 119 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 120 | |
| 121 | </refsect1> |
| 122 | |
| 123 | |
| 124 | |
| 125 | <refsect1 id="error-related-options"> |
| 126 | <title>Error-Related Options</title> |
| 127 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 128 | <xi:include href="manual-core.xml" xpointer="error-related.opts.para" |
| 129 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 130 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 131 | <xi:include href="manual-core.xml" xpointer="error-related.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 132 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 133 | |
| 134 | </refsect1> |
| 135 | |
| 136 | |
| 137 | |
| 138 | <refsect1 id="malloc-related-options"> |
| 139 | <title>malloc()-related Options</title> |
| 140 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 141 | <xi:include href="manual-core.xml" xpointer="malloc-related.opts.para" |
| 142 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 143 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 144 | <xi:include href="manual-core.xml" xpointer="malloc-related.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 145 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 146 | |
| 147 | </refsect1> |
| 148 | |
| 149 | |
| 150 | |
| 151 | <refsect1 id="uncommon-options"> |
| 152 | <title>Uncommon Options</title> |
| 153 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 154 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 155 | <xi:include href="manual-core.xml" xpointer="uncommon.opts.para" |
| 156 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 157 | |
| 158 | <xi:include href="manual-core.xml" xpointer="uncommon.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 159 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 160 | |
| 161 | </refsect1> |
| 162 | |
| 163 | |
| 164 | |
| 165 | <refsect1 id="debugging-valgrind-options"> |
| 166 | <title>Debugging Valgrind Options</title> |
| 167 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 168 | <xi:include href="manual-core.xml" xpointer="debug.opts.para" |
| 169 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 170 | |
| 171 | </refsect1> |
| 172 | |
| 173 | |
| 174 | |
| 175 | <refsect1 id="memcheck-options"> |
| 176 | <title>Memcheck Options</title> |
| 177 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 178 | <xi:include href="../../memcheck/docs/mc-manual.xml" |
| 179 | xpointer="mc.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 180 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 181 | |
| 182 | </refsect1> |
| 183 | |
| 184 | |
| 185 | |
| 186 | <refsect1 id="cachegrind-options"> |
| 187 | <title>Cachegrind Options</title> |
| 188 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 189 | <xi:include href="../../cachegrind/docs/cg-manual.xml" |
| 190 | xpointer="cg.opts.para" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 191 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 192 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 193 | <xi:include href="../../cachegrind/docs/cg-manual.xml" |
| 194 | xpointer="cg.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 195 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 196 | |
| 197 | </refsect1> |
| 198 | |
| 199 | |
| 200 | |
| 201 | <refsect1 id="massif-options"> |
| 202 | <title>Massif Options</title> |
| 203 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 204 | <xi:include href="../../massif/docs/ms-manual.xml" |
| 205 | xpointer="ms.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 206 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 207 | |
| 208 | </refsect1> |
| 209 | |
| 210 | |
| 211 | |
| 212 | <refsect1 id="helgrind-options"> |
| 213 | <title>Helgrind Options</title> |
| 214 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 215 | <xi:include href="../../helgrind/docs/hg-manual.xml" |
| 216 | xpointer="hg.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 217 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 218 | |
| 219 | </refsect1> |
| 220 | |
| 221 | |
| 222 | |
| 223 | <refsect1 id="lackey-options"> |
| 224 | <title>Lackey Options</title> |
| 225 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame^] | 226 | <xi:include href="../../lackey/docs/lk-manual.xml" |
| 227 | xpointer="lk.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 228 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 229 | |
| 230 | </refsect1> |
| 231 | |
| 232 | |
| 233 | |
| 234 | <refsect1 id="see_also"> |
| 235 | <title>See Also</title> |
| 236 | |
| 237 | <para> |
| 238 | <filename>&vg-doc-path;</filename>, |
| 239 | and/or |
| 240 | <filename>&vg-bookset;</filename>. |
| 241 | </para> |
| 242 | |
| 243 | </refsect1> |
| 244 | |
| 245 | |
| 246 | <refsect1 id="author"> |
| 247 | <title>Author</title> |
| 248 | |
| 249 | <para>This manpage has been written by Andres Roldan <aroldan@debian.org> |
| 250 | for the Debian Project, but can be used for any other distribution.</para> |
| 251 | |
| 252 | <para>Updated, rearranged and expanded by Robert Walsh |
| 253 | <rjwalsh@durables.org> for the 2.4.0 release, and by other |
| 254 | Valgrind developers subsequently.</para> |
| 255 | |
| 256 | </refsect1> |
| 257 | |
| 258 | |
| 259 | </refentry> |
| 260 | |