Valgrind 3.3 - Advanced Debugging and Profiling for GNU/Linux applications by J. Seward, N. Nethercote, J. Weidendorfer and the Valgrind Development Team Paperback (6"x9"), 164 pages ISBN 0954612051 RRP £12.95 ($19.95) Get a printed copy>>>

Valgrind 3.3 Buy the book here >>> $19.95

3.6.3 Error-related options

These options are used by all tools that can report errors, e.g. Memcheck, but not Cachegrind.

• --xml=<yes|no> [default: no] When enabled, output will be in XML format. This is aimed at making life easier for tools that consume Valgrind's output as input, such as GUI front ends. Currently this option only works with Memcheck.
• --xml-user-comment=<string> Embeds an extra user comment string at the start of the XML output. Only works when --xml=yes is specified; ignored otherwise.
• --demangle=<yes|no> [default: yes] Enable/disable automatic demangling (decoding) of C++ names. Enabled by default. When enabled, Valgrind will attempt to translate encoded C++ names back to something approaching the original. The demangler handles symbols mangled by g++ versions 2.X, 3.X and 4.X. An important fact about demangling is that function names mentioned in suppressions files should be in their mangled form. Valgrind does not demangle function names when searching for applicable suppressions, because to do otherwise would make suppressions file contents dependent on the state of Valgrind's demangling machinery, and would also be slow and pointless.
• --num-callers=<number> [default: 12] By default, Valgrind shows twelve levels of function call names to help you identify program locations. You can change that number with this option. This can help in determining the program's location in deeply-nested call chains. Note that errors are commoned up using only the top four function locations (the place in the current function, and that of its three immediate callers). So this doesn't affect the total number of errors reported. The maximum value for this is 50. Note that higher settings will make Valgrind run a bit more slowly and take a bit more memory, but can be useful when working with programs with deeply-nested call chains.
• --error-limit=<yes|no> [default: yes] When enabled, Valgrind stops reporting errors after 10,000,000 in total, or 1,000 different ones, have been seen. This is to stop the error tracking machinery from becoming a huge performance overhead in programs with many errors.
• --error-exitcode=<number> [default: 0] Specifies an alternative exit code to return if Valgrind reported any errors in the run. When set to the default value (zero), the return value from Valgrind will always be the return value of the process being simulated. When set to a nonzero value, that value is returned instead, if Valgrind detects any errors. This is useful for using Valgrind as part of an automated test suite, since it makes it easy to detect test cases for which Valgrind has reported errors, just by inspecting return codes.
• --show-below-main=<yes|no> [default: no] By default, stack traces for errors do not show any functions that appear beneath main() (or similar functions such as glibc's __libc_start_main(), if main() is not present in the stack trace); most of the time it's uninteresting C library stuff. If this option is enabled, those entries below main() will be shown.
• --suppressions=<filename>
[default: $PREFIX/lib/valgrind/default.supp] Specifies an extra file from which to read descriptions of errors to suppress. You may use as many extra suppressions files as you like.
• --gen-suppressions=<yes|no|all> [default: no] When set to yes, Valgrind will pause after every error shown and print the line:

  ---- Print suppression ? -- [Return/N/n/Y/y/C/c] 
  

  The prompt's behaviour is the same as for the --db-attach option (see below). If you choose to, Valgrind will print out a suppression for this error. You can then cut and paste it into a suppression file if you don't want to hear about the error in the future. When set to all, Valgrind will print a suppression for every reported error, without querying the user. This option is particularly useful with C++ programs, as it prints out the suppressions with mangled names, as required. Note that the suppressions printed are as specific as possible. You may want to common up similar ones, e.g. by adding wildcards to function names. Sometimes two different errors are suppressed by the same suppression, in which case Valgrind will output the suppression more than once, but you only need to have one copy in your suppression file (but having more than one won't cause problems). Also, the suppression name is given as ‘<insert a suppression name here>’; the name doesn't really matter, it's only used with the -v option which prints out all used suppression records.
• --db-attach=<yes|no> [default: no] When enabled, Valgrind will pause after every error shown and print the line:

  ---- Attach to debugger ? -- [Return/N/n/Y/y/C/c] 
  

  Pressing Ret, or N Ret or n Ret, causes Valgrind not to start a debugger for this error. Pressing Y Ret or y Ret causes Valgrind to start a debugger for the program at this point. When you have finished with the debugger, quit from it, and the program will continue. Trying to continue from inside the debugger doesn't work. C Ret or c Ret causes Valgrind not to start a debugger, and not to ask again. Note: --db-attach=yes conflicts with --trace-children=yes. You can't use them together. Valgrind refuses to start up in this situation. May 2002: this is a historical relic which could be easily fixed if it gets in your way. Mail us and complain if this is a problem for you. Nov 2002: if you're sending output to a logfile or to a network socket, I guess this option doesn't make any sense. Caveat emptor.
• --db-command=<command> [default: gdb -nw %f %p] Specify the debugger to use with the --db-attach command. The default debugger is gdb. This option is a template that is expanded by Valgrind at runtime. ‘%f’ is replaced with the executable's file name and ‘%p’ is replaced by the process ID of the executable. This specifies how Valgrind will invoke the debugger. By default it will use whatever GDB is detected at build time, which is usually ‘/usr/bin/gdb’. Using this command, you can specify some alternative command to invoke the debugger you want to use. The command string given can include one or instances of the ‘%p’ and ‘%f’ expansions. Each instance of ‘%p’ expands to the PID of the process to be debugged and each instance of ‘%f’ expands to the path to the executable for the process to be debugged. Since ‘<command>’ is likely to contain spaces, you will need to put this entire flag in quotes to ensure it is correctly handled by the shell.
• --input-fd=<number> [default: 0, stdin] When using --db-attach=yes or --gen-suppressions=yes, Valgrind will stop so as to read keyboard input from you when each error occurs. By default it reads from the standard input (stdin), which is problematic for programs which close stdin. This option allows you to specify an alternative file descriptor from which to read input.
• --max-stackframe=<number> [default: 2000000] The maximum size of a stack frame. If the stack pointer moves by more than this amount then Valgrind will assume that the program is switching to a different stack. You may need to use this option if your program has large stack-allocated arrays. Valgrind keeps track of your program's stack pointer. If it changes by more than the threshold amount, Valgrind assumes your program is switching to a different stack, and Memcheck behaves differently than it would for a stack pointer change smaller than the threshold. Usually this heuristic works well. However, if your program allocates large structures on the stack, this heuristic will be fooled, and Memcheck will subsequently report large numbers of invalid stack accesses. This option allows you to change the threshold to a different value. You should only consider use of this flag if Valgrind's debug output directs you to do so. In that case it will tell you the new threshold you should specify. In general, allocating large structures on the stack is a bad idea, because you can easily run out of stack space, especially on systems with limited memory or which expect to support large numbers of threads each with a small stack, and also because the error checking performed by Memcheck is more effective for heap-allocated data than for stack-allocated data. If you have to use this flag, you may wish to consider rewriting your code to allocate on the heap rather than on the stack.