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> |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame^] | 80 | <para><option>callgrind</option> adds call graph tracing to cachegrind. It can be |
| 81 | used to get call counts and inclusive cost for each call happening in your |
| 82 | program. In addition to cachegrind, callgrind can annotate threads separatly, |
| 83 | and every instruction of disassembler output of your program with the number of |
| 84 | instructions executed and cache misses incurred.</para> |
| 85 | </listitem> |
| 86 | |
| 87 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 88 | <para><option>helgrind</option> spots potential race conditions in |
| 89 | your program.</para> |
| 90 | </listitem> |
| 91 | |
| 92 | <listitem> |
| 93 | <para><option>lackey</option> is a sample tool that can be used as a |
| 94 | template for generating your own tools. After the program |
| 95 | terminates, it prints out some basic statistics about the program |
| 96 | execution.</para> |
| 97 | </listitem> |
| 98 | |
| 99 | <listitem> |
| 100 | <para><option>massif</option> is a heap profiler. It measures how |
| 101 | much heap memory your program uses.</para> |
| 102 | </listitem> |
| 103 | |
| 104 | <listitem> |
| 105 | <para><option>memcheck</option> is a fine-grained memory checker.</para> |
| 106 | </listitem> |
| 107 | |
| 108 | <listitem> |
| 109 | <para><option>none</option> performs no function - it simply runs |
| 110 | the program under Valgrind. This is typically used for debugging |
| 111 | and benchmarking Valgrind.</para> |
| 112 | </listitem> |
| 113 | |
| 114 | </itemizedlist> |
| 115 | |
| 116 | </refsect1> |
| 117 | |
| 118 | |
| 119 | |
| 120 | <refsect1 id="basic-options"> |
| 121 | <title>Basic Options</title> |
| 122 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 123 | <xi:include href="manual-core.xml" xpointer="basic.opts.para" |
| 124 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 125 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 126 | <xi:include href="manual-core.xml" xpointer="basic.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 127 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 128 | |
| 129 | </refsect1> |
| 130 | |
| 131 | |
| 132 | |
| 133 | <refsect1 id="error-related-options"> |
| 134 | <title>Error-Related Options</title> |
| 135 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 136 | <xi:include href="manual-core.xml" xpointer="error-related.opts.para" |
| 137 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 138 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 139 | <xi:include href="manual-core.xml" xpointer="error-related.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 140 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 141 | |
| 142 | </refsect1> |
| 143 | |
| 144 | |
| 145 | |
| 146 | <refsect1 id="malloc-related-options"> |
| 147 | <title>malloc()-related Options</title> |
| 148 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 149 | <xi:include href="manual-core.xml" xpointer="malloc-related.opts.para" |
| 150 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 151 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 152 | <xi:include href="manual-core.xml" xpointer="malloc-related.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 153 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 154 | |
| 155 | </refsect1> |
| 156 | |
| 157 | |
| 158 | |
| 159 | <refsect1 id="uncommon-options"> |
| 160 | <title>Uncommon Options</title> |
| 161 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 162 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 163 | <xi:include href="manual-core.xml" xpointer="uncommon.opts.para" |
| 164 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 165 | |
| 166 | <xi:include href="manual-core.xml" xpointer="uncommon.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 167 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 168 | |
| 169 | </refsect1> |
| 170 | |
| 171 | |
| 172 | |
| 173 | <refsect1 id="debugging-valgrind-options"> |
| 174 | <title>Debugging Valgrind Options</title> |
| 175 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 176 | <xi:include href="manual-core.xml" xpointer="debug.opts.para" |
| 177 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 178 | |
| 179 | </refsect1> |
| 180 | |
| 181 | |
| 182 | |
| 183 | <refsect1 id="memcheck-options"> |
| 184 | <title>Memcheck Options</title> |
| 185 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 186 | <xi:include href="../../memcheck/docs/mc-manual.xml" |
| 187 | xpointer="mc.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 188 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 189 | |
| 190 | </refsect1> |
| 191 | |
| 192 | |
| 193 | |
| 194 | <refsect1 id="cachegrind-options"> |
| 195 | <title>Cachegrind Options</title> |
| 196 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 197 | <xi:include href="../../cachegrind/docs/cg-manual.xml" |
| 198 | xpointer="cg.opts.para" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 199 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 200 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 201 | <xi:include href="../../cachegrind/docs/cg-manual.xml" |
| 202 | xpointer="cg.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 203 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 204 | |
| 205 | </refsect1> |
| 206 | |
| 207 | |
| 208 | |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame^] | 209 | <refsect1 id="callgrind-options"> |
| 210 | <title>Callgrind Options</title> |
| 211 | |
| 212 | <xi:include href="../../callgrind/docs/cl-manual.xml" |
| 213 | xpointer="cl.opts.list" |
| 214 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 215 | |
| 216 | </refsect1> |
| 217 | |
| 218 | |
| 219 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 220 | <refsect1 id="massif-options"> |
| 221 | <title>Massif Options</title> |
| 222 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 223 | <xi:include href="../../massif/docs/ms-manual.xml" |
| 224 | xpointer="ms.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 225 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 226 | |
| 227 | </refsect1> |
| 228 | |
| 229 | |
| 230 | |
| 231 | <refsect1 id="helgrind-options"> |
| 232 | <title>Helgrind Options</title> |
| 233 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 234 | <xi:include href="../../helgrind/docs/hg-manual.xml" |
| 235 | xpointer="hg.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 236 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 237 | |
| 238 | </refsect1> |
| 239 | |
| 240 | |
| 241 | |
| 242 | <refsect1 id="lackey-options"> |
| 243 | <title>Lackey Options</title> |
| 244 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 245 | <xi:include href="../../lackey/docs/lk-manual.xml" |
| 246 | xpointer="lk.opts.list" |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 247 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 248 | |
| 249 | </refsect1> |
| 250 | |
| 251 | |
| 252 | |
| 253 | <refsect1 id="see_also"> |
| 254 | <title>See Also</title> |
| 255 | |
| 256 | <para> |
| 257 | <filename>&vg-doc-path;</filename>, |
| 258 | and/or |
| 259 | <filename>&vg-bookset;</filename>. |
| 260 | </para> |
| 261 | |
| 262 | </refsect1> |
| 263 | |
| 264 | |
| 265 | <refsect1 id="author"> |
| 266 | <title>Author</title> |
| 267 | |
| 268 | <para>This manpage has been written by Andres Roldan <aroldan@debian.org> |
| 269 | for the Debian Project, but can be used for any other distribution.</para> |
| 270 | |
| 271 | <para>Updated, rearranged and expanded by Robert Walsh |
| 272 | <rjwalsh@durables.org> for the 2.4.0 release, and by other |
| 273 | Valgrind developers subsequently.</para> |
| 274 | |
| 275 | </refsect1> |
| 276 | |
| 277 | |
| 278 | </refentry> |
| 279 | |