Note that Valgrind does trace into the child of a fork (it would be difficult not to, since fork makes an identical copy of a process), so this option is arguably badly named. However, most children of fork calls immediately call exec anyway.

%p is replaced with the current process ID. This is very useful for program that invoke multiple processes. WARNING: If you use --trace-children=yes and your program invokes multiple processes and you don't use this specifier (or the %q specifier below), the Valgrind output from all those processes will go into one file, possibly jumbled up, and possibly incomplete.

%q{FOO} is replaced with the contents of the environment variable FOO. If the {FOO} part is malformed, it causes an abort. This specifier is rarely needed, but very useful in certain circumstances (eg. when running MPI programs). The idea is that you specify a variable which will be set differently for each process in the job, for example BPROC_RANK or whatever is applicable in your MPI setup. If the named environment variable is not set, it causes an abort. Note that in some shells, the { and } characters may need to be escaped with a backslash.

%% is replaced with %.

If an % is followed by any other character, it causes an abort.

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.

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.

    ---- 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, eg. 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.

    ---- 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.

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.

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.

The glibc authors realised that this behaviour causes leak checkers, such as Valgrind, to falsely report leaks in glibc, when a leak check is done at exit. In order to avoid this, they provided a routine called __libc_freeres specifically to make glibc release all memory it has allocated. Memcheck therefore tries to run __libc_freeres at exit.

Unfortunately, in some very old versions of glibc, __libc_freeres is sufficiently buggy to cause segmentation faults. This was particularly noticeable on Red Hat 7.1. So this flag is provided in order to inhibit the run of __libc_freeres. If your program seems to run fine on Valgrind, but segfaults at exit, you may find that --run-libc-freeres=no fixes that, although at the cost of possibly falsely reporting space leaks in libc.so.

Some architectures (including ppc32 and ppc64) require programs which create code at runtime to flush the instruction cache in between code generation and first use. Valgrind observes and honours such instructions. Hence, on ppc32/Linux and ppc64/Linux, Valgrind always provides complete, transparent support for self-modifying code. It is only on x86/Linux and amd64/Linux that you need to use this flag.

For hardcore leak debugging, you probably want to use --leak-resolution=high together with --num-callers=40 or some such large number. Note however that this can give an overwhelming amount of information, which is why the defaults are 4 callers and low-resolution matching.

Note that the --leak-resolution= setting does not affect memcheck's ability to find leaks. It only changes how the results are presented.

This flag specifies the maximum total size, in bytes, of the blocks in the queue. The default value is ten million bytes. Increasing this increases the total amount of memory used by memcheck but may detect invalid uses of freed blocks which would otherwise go undetected.

You may also need to use this flag when working with gcc/g++ 3.X or 4.X on 32-bit PowerPC Linux. This is because gcc/g++ generates code which occasionally accesses below the stack pointer, particularly for floating-point to/from integer conversions. This is in violation of the 32-bit PowerPC ELF specification, which makes no provision for locations below the stack pointer to be accessible.

When no, loads from partially invalid addresses are treated the same as loads from completely invalid addresses: an illegal-address error is issued, and the resulting bytes are marked as initialised.

Note that code that behaves in this way is in violation of the the ISO C/C++ standards, and should be considered broken. If at all possible, such code should be fixed. This flag should be used only as a last resort.

Note that the resulting call graph will most probably not contain main, but will contain all the functions executed after instrumentation was switched on. Instrumentation can also programatically switched on/off. See the Callgrind include file <callgrind.h> for the macro you have to use in your source code.

For cache simulation, results will be less accurate when switching on instrumentation later in the program run, as the simulator starts with an empty cache at that moment. Switch on event collection later to cope with this error.

To only look at parts of your program, you have two possibilities:

Collection state can be toggled at entry and exit of a given function with the option --toggle-collect. If you use this flag, collection state should be switched off at the beginning. Note that the specification of --toggle-collect implicitly sets --collect-state=no.

Collection state can be toggled also by using a Valgrind Client Request in your application. For this, include valgrind/callgrind.h and specify the macro CALLGRIND_TOGGLE_COLLECT at the needed positions. This only will have any effect if run under supervision of the Callgrind tool.

Note that overloaded C++ names must be written in full. Single quotes may be necessary to prevent the shell from breaking them up. For example:

--alloc-fn='operator new(unsigned, std::nothrow_t const&)'

The full list of functions and operators that are by default considered allocation functions is as follows.

malloc
calloc
realloc
memalign
__builtin_new
__builtin_vec_new
operator new(unsigned)
operator new(unsigned long)
operator new[](unsigned)
operator new[](unsigned long)
operator new(unsigned, std::nothrow_t const&)
operator new[](unsigned, std::nothrow_t const&)
operator new(unsigned long, std::nothrow_t const&)
operator new[](unsigned long, std::nothrow_t const&)

With --happens-before=all, the following events are regarded as sources of synchronisation: thread creation/joinage, condition variable signal/broadcast/waits, and semaphore posts/waits.

With --happens-before=threads, only thread creation/joinage events are regarded as sources of synchronisation.

With --happens-before=none, no events (apart, of course, from locking) are regarded as sources of synchronisation.

Changing this setting from the default will increase your false-error rate but give little or no gain. The only advantage is that --happens-before=threads and --happens-before=none should make Helgrind less and less sensitive to the scheduling of threads, and hence the output more and more repeatable across runs.