1VALGRIND(1) Release 3.2.3 VALGRIND(1)
2
6 valgrind - a suite of tools for debugging and profiling programs
7
9 valgrind [[valgrind] [options]] [your-program] [[your-program-options]]
10
12 Valgrind is a flexible program for debugging and profiling Linux
13 executables. It consists of a core, which provides a synthetic CPU in
14 software, and a series of "tools", each of which is a debugging or
15 profiling tool. The architecture is modular, so that new tools can be
16 created easily and without disturbing the existing structure.
17 This manual page covers only basic usage and options. For more
19 comprehensive information, please see the HTML documentation on your
20 system: /usr/share/doc/valgrind/html/index.html, or online:
21 http://www.valgrind.org/docs/manual/index.html.
22
24 Valgrind is typically invoked as follows:
25 valgrind program args
27 This runs program (with arguments args) under Valgrind using the
29 Memcheck tool. Memcheck performs a range of memory-checking functions,
30 including detecting accesses to uninitialised memory, misuse of
31 allocated memory (double frees, access after free, etc.) and detecting
32 memory leaks.
33 To use a different tool, use the --tool option:
35 valgrind --tool=toolname program args
37 The following tools are available:
39 · cachegrind is a cache simulator. It can be used to annotate every
41 line of your program with the number of instructions executed and
42 cache misses incurred.
43 · callgrind adds call graph tracing to cachegrind. It can be used to
45 get call counts and inclusive cost for each call happening in your
46 program. In addition to cachegrind, callgrind can annotate threads
47 separatly, and every instruction of disassembler output of your
48 program with the number of instructions executed and cache misses
49 incurred.
50 · helgrind spots potential race conditions in your program.
52 · lackey is a sample tool that can be used as a template for
54 generating your own tools. After the program terminates, it prints
55 out some basic statistics about the program execution.
56 · massif is a heap profiler. It measures how much heap memory your
58 program uses.
59 · memcheck is a fine-grained memory checker.
61 · none performs no function - it simply runs the program under
63 Valgrind. This is typically used for debugging and benchmarking
64 Valgrind.
65
67 These options work with all tools.
68 -h --help
70 Show help for all options, both for the core and for the
71 selected tool.
72 --help-debug
74 Same as --help, but also lists debugging options which usually
75 are only of use to Valgrind's developers.
76 --version
78 Show the version number of the Valgrind core. Tools can have
79 their own version numbers. There is a scheme in place to ensure
80 that tools only execute when the core version is one they are
81 known to work with. This was done to minimise the chances of
82 strange problems arising from tool-vs-core version
83 incompatibilities.
84 -q --quiet
86 Run silently, and only print error messages. Useful if you are
87 running regression tests or have some other automated test
88 machinery.
89 -v --verbose
91 Be more verbose. Gives extra information on various aspects of
92 your program, such as: the shared objects loaded, the
93 suppressions used, the progress of the instrumentation and
94 execution engines, and warnings about unusual behaviour.
95 Repeating the flag increases the verbosity level.
96 -d Emit information for debugging Valgrind itself. This is usually
98 only of interest to the Valgrind developers. Repeating the flag
99 produces more detailed output. If you want to send us a bug
100 report, a log of the output generated by -v -v -d -d will make
101 your report more useful.
102 --tool=<toolname> [default: memcheck]
104 Run the Valgrind tool called toolname, e.g. Memcheck, Addrcheck,
105 Cachegrind, etc.
106 --trace-children=<yes|no> [default: no]
108 When enabled, Valgrind will trace into child processes. This can
109 be confusing and isn't usually what you want, so it is disabled
110 by default.
111 --track-fds=<yes|no> [default: no]
113 When enabled, Valgrind will print out a list of open file
114 descriptors on exit. Along with each file descriptor is printed
115 a stack backtrace of where the file was opened and any details
116 relating to the file descriptor such as the file name or socket
117 details.
118 --time-stamp=<yes|no> [default: no]
120 When enabled, each message is preceded with an indication of the
121 elapsed wallclock time since startup, expressed as days, hours,
122 minutes, seconds and milliseconds.
123 --log-fd=<number> [default: 2, stderr]
125 Specifies that Valgrind should send all of its messages to the
126 specified file descriptor. The default, 2, is the standard error
127 channel (stderr). Note that this may interfere with the client's
128 own use of stderr, as Valgrind's output will be interleaved with
129 any output that the client sends to stderr.
130 --log-file=<filename>
132 Specifies that Valgrind should send all of its messages to the
133 specified file. In fact, the file name used is created by
134 concatenating the text filename, "." and the process ID, (ie.
135 <filename>.<pid>), so as to create a file per process. The
136 specified file name may not be the empty string.
137 --log-file-exactly=<filename>
139 Just like --log-file, but the suffix ".pid" is not added. If you
140 trace multiple processes with Valgrind when using this option
141 the log file may get all messed up.
142 --log-file-qualifier=<VAR>
144 When used in conjunction with --log-file, causes the log file
145 name to be qualified using the contents of the environment
146 variable $VAR. This is useful when running MPI programs. For
147 further details, see Section 2.3 "The Commentary" in the manual.
148 --log-socket=<ip-address:port-number>
150 Specifies that Valgrind should send all of its messages to the
151 specified port at the specified IP address. The port may be
152 omitted, in which case port 1500 is used. If a connection cannot
153 be made to the specified socket, Valgrind falls back to writing
154 output to the standard error (stderr). This option is intended
155 to be used in conjunction with the valgrind-listener program.
156 For further details, see Section 2.3 "The Commentary" in the
157 manual.
158
160 These options are used by all tools that can report errors, e.g.
161 Memcheck, but not Cachegrind.
162 --xml=<yes|no> [default: no]
164 When enabled, output will be in XML format. This is aimed at
165 making life easier for tools that consume Valgrind's output as
166 input, such as GUI front ends. Currently this option only works
167 with Memcheck.
168 --xml-user-comment=<string>
170 Embeds an extra user comment string at the start of the XML
171 output. Only works when --xml=yes is specified; ignored
172 otherwise.
173 --demangle=<yes|no> [default: yes]
175 Enable/disable automatic demangling (decoding) of C++ names.
176 Enabled by default. When enabled, Valgrind will attempt to
177 translate encoded C++ names back to something approaching the
178 original. The demangler handles symbols mangled by g++ versions
179 2.X, 3.X and 4.X.
180 An important fact about demangling is that function names
182 mentioned in suppressions files should be in their mangled form.
183 Valgrind does not demangle function names when searching for
184 applicable suppressions, because to do otherwise would make
185 suppressions file contents dependent on the state of Valgrind's
186 demangling machinery, and would also be slow and pointless.
187 --num-callers=<number> [default: 12]
189 By default, Valgrind shows twelve levels of function call names
190 to help you identify program locations. You can change that
191 number with this option. This can help in determining the
192 program's location in deeply-nested call chains. Note that
193 errors are commoned up using only the top four function
194 locations (the place in the current function, and that of its
195 three immediate callers). So this doesn't affect the total
196 number of errors reported.
197 The maximum value for this is 50. Note that higher settings will
199 make Valgrind run a bit more slowly and take a bit more memory,
200 but can be useful when working with programs with deeply-nested
201 call chains.
202 --error-limit=<yes|no> [default: yes]
204 When enabled, Valgrind stops reporting errors after 10,000,000
205 in total, or 1,000 different ones, have been seen. This is to
206 stop the error tracking machinery from becoming a huge
207 performance overhead in programs with many errors.
208 --error-exitcode=<number> [default: 0]
210 Specifies an alternative exit code to return if Valgrind
211 reported any errors in the run. When set to the default value
212 (zero), the return value from Valgrind will always be the return
213 value of the process being simulated. When set to a nonzero
214 value, that value is returned instead, if Valgrind detects any
215 errors. This is useful for using Valgrind as part of an
216 automated test suite, since it makes it easy to detect test
217 cases for which Valgrind has reported errors, just by inspecting
218 return codes.
219 --show-below-main=<yes|no> [default: no]
221 By default, stack traces for errors do not show any functions
222 that appear beneath main() (or similar functions such as glibc's
223 __libc_start_main(), if main() is not present in the stack
224 trace); most of the time it's uninteresting C library stuff. If
225 this option is enabled, those entries below main() will be
226 shown.
227 --suppressions=<filename> [default: $PREFIX/lib/valgrind/default.supp]
229 Specifies an extra file from which to read descriptions of
230 errors to suppress. You may use as many extra suppressions files
231 as you like.
232 --gen-suppressions=<yes|no|all> [default: no]
234 When set to yes, Valgrind will pause after every error shown and
235 print the line:
236 ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ----
238 The prompt's behaviour is the same as for the --db-attach option
240 (see below).
241 If you choose to, Valgrind will print out a suppression for this
243 error. You can then cut and paste it into a suppression file if
244 you don't want to hear about the error in the future.
245 When set to all, Valgrind will print a suppression for every
247 reported error, without querying the user.
248 This option is particularly useful with C++ programs, as it
250 prints out the suppressions with mangled names, as required.
251 Note that the suppressions printed are as specific as possible.
253 You may want to common up similar ones, eg. by adding wildcards
254 to function names. Also, sometimes two different errors are
255 suppressed by the same suppression, in which case Valgrind will
256 output the suppression more than once, but you only need to have
257 one copy in your suppression file (but having more than one
258 won't cause problems). Also, the suppression name is given as
259 <insert a suppression name here>; the name doesn't really
260 matter, it's only used with the -v option which prints out all
261 used suppression records.
262 --db-attach=<yes|no> [default: no]
264 When enabled, Valgrind will pause after every error shown and
265 print the line:
266 ---- Attach to debugger ? --- [Return/N/n/Y/y/C/c] ----
268 Pressing Ret, or N Ret or n Ret, causes Valgrind not to start a
270 debugger for this error.
271 Pressing Y Ret or y Ret causes Valgrind to start a debugger for
273 the program at this point. When you have finished with the
274 debugger, quit from it, and the program will continue. Trying to
275 continue from inside the debugger doesn't work.
276 C Ret or c Ret causes Valgrind not to start a debugger, and not
278 to ask again.
279 Note:--db-attach=yes conflicts with --trace-children=yes. You
281 can't use them together. Valgrind refuses to start up in this
282 situation.
283 May 2002: this is a historical relic which could be easily fixed
285 if it gets in your way. Mail us and complain if this is a
286 problem for you.
287 Nov 2002: if you're sending output to a logfile or to a network
289 socket, I guess this option doesn't make any sense. Caveat
290 emptor.
291 --db-command=<command> [default: gdb -nw %f %p]
293 Specify the debugger to use with the --db-attach command. The
294 default debugger is gdb. This option is a template that is
295 expanded by Valgrind at runtime. %f is replaced with the
296 executable's file name and %p is replaced by the process ID of
297 the executable.
298 This specifies how Valgrind will invoke the debugger. By default
300 it will use whatever GDB is detected at build time, which is
301 usually /usr/bin/gdb. Using this command, you can specify some
302 alternative command to invoke the debugger you want to use.
303 The command string given can include one or instances of the %p
305 and %f expansions. Each instance of %p expands to the PID of the
306 process to be debugged and each instance of %f expands to the
307 path to the executable for the process to be debugged.
308 --input-fd=<number> [default: 0, stdin]
310 When using --db-attach=yes and --gen-suppressions=yes, Valgrind
311 will stop so as to read keyboard input from you, when each error
312 occurs. By default it reads from the standard input (stdin),
313 which is problematic for programs which close stdin. This option
314 allows you to specify an alternative file descriptor from which
315 to read input.
316 --max-stackframe=<number> [default: 2000000]
318 The maximum size of a stack frame - if the stack pointer moves
319 by more than this amount then Valgrind will assume that the
320 program is switching to a different stack.
321 You may need to use this option if your program has large
323 stack-allocated arrays. Valgrind keeps track of your program's
324 stack pointer. If it changes by more than the threshold amount,
325 Valgrind assumes your program is switching to a different stack,
326 and Memcheck behaves differently than it would for a stack
327 pointer change smaller than the threshold. Usually this
328 heuristic works well. However, if your program allocates large
329 structures on the stack, this heuristic will be fooled, and
330 Memcheck will subsequently report large numbers of invalid stack
331 accesses. This option allows you to change the threshold to a
332 different value.
333 You should only consider use of this flag if Valgrind's debug
335 output directs you to do so. In that case it will tell you the
336 new threshold you should specify.
337 In general, allocating large structures on the stack is a bad
339 idea, because (1) you can easily run out of stack space,
340 especially on systems with limited memory or which expect to
341 support large numbers of threads each with a small stack, and
342 (2) because the error checking performed by Memcheck is more
343 effective for heap-allocated data than for stack-allocated data.
344 If you have to use this flag, you may wish to consider rewriting
345 your code to allocate on the heap rather than on the stack.
346
348 For tools that use their own version of malloc() (e.g. Memcheck and
349 Massif), the following options apply.
350 --alignment=<number> [default: 8]
352 By default Valgrind's malloc(), realloc(), etc, return 8-byte
353 aligned addresses. This is standard for most processors.
354 However, some programs might assume that malloc() et al return
355 16-byte or more aligned memory. The supplied value must be
356 between 8 and 4096 inclusive, and must be a power of two.
357
359 These options apply to all tools, as they affect certain obscure
360 workings of the Valgrind core. Most people won't need to use these.
361 --run-libc-freeres=<yes|no> [default: yes]
363 The GNU C library (libc.so), which is used by all programs, may
364 allocate memory for its own uses. Usually it doesn't bother to
365 free that memory when the program ends - there would be no
366 point, since the Linux kernel reclaims all process resources
367 when a process exits anyway, so it would just slow things down.
368 The glibc authors realised that this behaviour causes leak
370 checkers, such as Valgrind, to falsely report leaks in glibc,
371 when a leak check is done at exit. In order to avoid this, they
372 provided a routine called __libc_freeres specifically to make
373 glibc release all memory it has allocated. Memcheck therefore
374 tries to run __libc_freeres at exit.
375 Unfortunately, in some versions of glibc, __libc_freeres is
377 sufficiently buggy to cause segmentation faults. This is
378 particularly noticeable on Red Hat 7.1. So this flag is provided
379 in order to inhibit the run of __libc_freeres. If your program
380 seems to run fine on Valgrind, but segfaults at exit, you may
381 find that --run-libc-freeres=no fixes that, although at the cost
382 of possibly falsely reporting space leaks in libc.so.
383 --sim-hints=hint1,hint2,...
385 Pass miscellaneous hints to Valgrind which slightly modify the
386 simulated behaviour in nonstandard or dangerous ways, possibly
387 to help the simulation of strange features. By default no hints
388 are enabled. Use with caution! Currently known hints are:
389 · lax-ioctls: Be very lax about ioctl handling; the only
391 assumption is that the size is correct. Doesn't require the
392 full buffer to be initialized when writing. Without this,
393 using some device drivers with a large number of strange
394 ioctl commands becomes very tiresome.
395 · enable-inner: Enable some special magic needed when the
397 program being run is itself Valgrind.
398 --kernel-variant=variant1,variant2,...
400 Handle system calls and ioctls arising from minor variants of
401 the default kernel for this platform. This is useful for running
402 on hacked kernels or with kernel modules which support
403 nonstandard ioctls, for example. Use with caution. If you don't
404 understand what this option does then you almost certainly don't
405 need it. Currently known variants are:
406 · bproc: Support the sys_broc system call on x86. This is for
408 running on BProc, which is a minor variant of standard Linux
409 which is sometimes used for building clusters.
410 --show-emwarns=<yes|no> [default: no]
412 When enabled, Valgrind will emit warnings about its CPU
413 emulation in certain cases. These are usually not interesting.
414 --smc-check=<none|stack|all> [default: stack]
416 This option controls Valgrind's detection of self-modifying
417 code. Valgrind can do no detection, detect self-modifying code
418 on the stack, or detect self-modifying code anywhere. Note that
419 the default option will catch the vast majority of cases, as far
420 as we know. Running with all will slow Valgrind down greatly
421 (but running with none will rarely speed things up, since very
422 little code gets put on the stack for most programs).
423
425 There are also some options for debugging Valgrind itself. You
426 shouldn't need to use them in the normal run of things. If you wish to
427 see the list, use the --help-debug option.
428
430 --leak-check=<no|summary|yes|full> [default: summary]
431 When enabled, search for memory leaks when the client program
432 finishes. A memory leak means a malloc'd block, which has not
433 yet been free'd, but to which no pointer can be found. Such a
434 block can never be free'd by the program, since no pointer to it
435 exists. If set to summary, it says how many leaks occurred. If
436 set to full or yes, it gives details of each individual leak.
437 --show-reachable=<yes|no> [default: no]
439 When disabled, the memory leak detector only shows blocks for
440 which it cannot find a pointer to at all, or it can only find a
441 pointer to the middle of. These blocks are prime candidates for
442 memory leaks. When enabled, the leak detector also reports on
443 blocks which it could find a pointer to. Your program could, at
444 least in principle, have freed such blocks before exit. Contrast
445 this to blocks for which no pointer, or only an interior pointer
446 could be found: they are more likely to indicate memory leaks,
447 because you do not actually have a pointer to the start of the
448 block which you can hand to free, even if you wanted to.
449 --leak-resolution=<low|med|high> [default: low]
451 When doing leak checking, determines how willing memcheck is to
452 consider different backtraces to be the same. When set to low,
453 only the first two entries need match. When med, four entries
454 have to match. When high, all entries need to match.
455 For hardcore leak debugging, you probably want to use
457 --leak-resolution=high together with --num-callers=40 or some
458 such large number. Note however that this can give an
459 overwhelming amount of information, which is why the defaults
460 are 4 callers and low-resolution matching.
461 Note that the --leak-resolution= setting does not affect
463 memcheck's ability to find leaks. It only changes how the
464 results are presented.
465 --freelist-vol=<number> [default: 5000000]
467 When the client program releases memory using free (in C) or
468 delete (C++), that memory is not immediately made available for
469 re-allocation. Instead, it is marked inaccessible and placed in
470 a queue of freed blocks. The purpose is to defer as long as
471 possible the point at which freed-up memory comes back into
472 circulation. This increases the chance that memcheck will be
473 able to detect invalid accesses to blocks for some significant
474 period of time after they have been freed.
475 This flag specifies the maximum total size, in bytes, of the
477 blocks in the queue. The default value is five million bytes.
478 Increasing this increases the total amount of memory used by
479 memcheck but may detect invalid uses of freed blocks which would
480 otherwise go undetected.
481 --workaround-gcc296-bugs=<yes|no> [default: no]
483 When enabled, assume that reads and writes some small distance
484 below the stack pointer are due to bugs in gcc 2.96, and does
485 not report them. The "small distance" is 256 bytes by default.
486 Note that gcc 2.96 is the default compiler on some older Linux
487 distributions (RedHat 7.X) and so you may need to use this flag.
488 Do not use it if you do not have to, as it can cause real errors
489 to be overlooked. A better alternative is to use a more recent
490 gcc/g++ in which this bug is fixed.
491 --partial-loads-ok=<yes|no> [default: no]
493 Controls how memcheck handles word-sized, word-aligned loads
494 from addresses for which some bytes are addressible and others
495 are not. When yes, such loads do not elicit an address error.
496 Instead, the loaded V bytes corresponding to the illegal
497 addresses indicate Undefined, and those corresponding to legal
498 addresses are loaded from shadow memory, as usual.
499 When no, loads from partially invalid addresses are treated the
501 same as loads from completely invalid addresses: an
502 illegal-address error is issued, and the resulting V bytes
503 indicate valid data.
504 Note that code that behaves in this way is in violation of the
506 the ISO C/C++ standards, and should be considered broken. If at
507 all possible, such code should be fixed. This flag should be
508 used only as a last resort.
509 --undef-value-errors=<yes|no> [default: yes]
511 Controls whether memcheck detects dangerous uses of undefined
512 value errors. When yes, Memcheck behaves like Addrcheck, a
513 lightweight memory-checking tool that used to be part of
514 Valgrind, which didn't detect undefined value errors. Use this
515 option if you don't like seeing undefined value errors.
516
518 Manually specifies the I1/D1/L2 cache configuration, where size and
519 line_size are measured in bytes. The three items must be
520 comma-separated, but with no spaces, eg:
521 valgrind --tool=cachegrind --I1=65535,2,64
523 You can specify one, two or three of the I1/D1/L2 caches. Any level not
525 manually specified will be simulated using the configuration found in
526 the normal way (via the CPUID instruction for automagic cache
527 configuration, or failing that, via defaults).
528 --I1=<size>,<associativity>,<line size>
530 Specify the size, associativity and line size of the level 1
531 instruction cache.
532 --D1=<size>,<associativity>,<line size>
534 Specify the size, associativity and line size of the level 1
535 data cache.
536 --L2=<size>,<associativity>,<line size>
538 Specify the size, associativity and line size of the level 2
539 cache.
540
542 <xi:include></xi:include>.SH "MASSIF OPTIONS"
543 --heap=<yes|no> [default: yes]
545 When enabled, profile heap usage in detail. Without it, the
546 massif.pid.txt or massif.pid.html will be very short.
547 --heap-admin=<number> [default: 8]
549 The number of admin bytes per block to use. This can only be an
550 estimate of the average, since it may vary. The allocator used
551 by glibc requires somewhere between 4 to 15 bytes per block,
552 depending on various factors. It also requires admin space for
553 freed blocks, although massif does not count this.
554 --stacks=<yes|no> [default: yes]
556 When enabled, include stack(s) in the profile. Threaded programs
557 can have multiple stacks.
558 --depth=<number> [default: 3]
560 Depth of call chains to present in the detailed heap
561 information. Increasing it will give more information, but
562 massif will run the program more slowly, using more memory, and
563 produce a bigger massif.pid.txt or massif.pid.hp file.
564 --alloc-fn=<name>
566 Specify a function that allocates memory. This is useful for
567 functions that are wrappers to malloc(), which can fill up the
568 context information uselessly (and give very uninformative bands
569 on the graph). Functions specified will be ignored in contexts,
570 i.e. treated as though they were malloc(). This option can be
571 specified multiple times on the command line, to name multiple
572 functions.
573 --format=<text|html> [default: text]
575 Produce the detailed heap information in text or HTML format.
576 The file suffix used will be either .txt or .html.
577
579 --private-stacks=<yes|no> [default: no]
580 Assume thread stacks are used privately.
581 --show-last-access=<yes|some|no> [default: no]
583 Show location of last word access on error.
584
586 --fnname=<name> [default: _dl_runtime_resolve()]
587 Count calls to <name>.
588 --detailed-counts=<no|yes> [default: no]
590 Count loads, stores and alu ops.
591
593 /usr/share/doc/valgrind/html/index.html, and/or
594 http://www.valgrind.org/docs/manual/index.html.
595
597 This manpage has been written by Andres Roldan <aroldan@debian.org> for
598 the Debian Project, but can be used for any other distribution.
599 Updated, rearranged and expanded by Robert Walsh <rjwalsh@durables.org>
601 for the 2.4.0 release, and by other Valgrind developers subsequently.
602Release 3.2.3 01/29/2007 VALGRIND(1)