---

   valgrind    ( 1 )

---

BASIC OPTIONS

These options work with all tools.

-h --help Show help for all options, both for the core and for the selected tool. If the option is repeated it is equivalent to giving --help-debug.

--help-debug Same as --help, but also lists debugging options which usually are only of use to Valgrind's developers.

--version Show the version number of the Valgrind core. Tools can have their own version numbers. There is a scheme in place to ensure that tools only execute when the core version is one they are known to work with. This was done to minimise the chances of strange problems arising from tool-vs-core version incompatibilities.

-q, --quiet Run silently, and only print error messages. Useful if you are running regression tests or have some other automated test machinery.

-v, --verbose Be more verbose. Gives extra information on various aspects of your program, such as: the shared objects loaded, the suppressions used, the progress of the instrumentation and execution engines, and warnings about unusual behaviour. Repeating the option increases the verbosity level.

--trace-children=<yes|no> [default: no] When enabled, Valgrind will trace into sub-processes initiated via the exec system call. This is necessary for multi-process programs.

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.

--trace-children-skip=patt1,patt2,... This option only has an effect when --trace-children=yes is specified. It allows for some children to be skipped. The option takes a comma separated list of patterns for the names of child executables that Valgrind should not trace into. Patterns may include the metacharacters ? and *, which have the usual meaning.

This can be useful for pruning uninteresting branches from a tree of processes being run on Valgrind. But you should be careful when using it. When Valgrind skips tracing into an executable, it doesn't just skip tracing that executable, it also skips tracing any of that executable's child processes. In other words, the flag doesn't merely cause tracing to stop at the specified executables -- it skips tracing of entire process subtrees rooted at any of the specified executables.

--trace-children-skip-by-arg=patt1,patt2,... This is the same as --trace-children-skip, with one difference: the decision as to whether to trace into a child process is made by examining the arguments to the child process, rather than the name of its executable.

--child-silent-after-fork=<yes|no> [default: no] When enabled, Valgrind will not show any debugging or logging output for the child process resulting from a fork call. This can make the output less confusing (although more misleading) when dealing with processes that create children. It is particularly useful in conjunction with --trace-children=. Use of this option is also strongly recommended if you are requesting XML output (--xml=yes), since otherwise the XML from child and parent may become mixed up, which usually makes it useless.

--vgdb=<no|yes|full> [default: yes] Valgrind will provide "gdbserver" functionality when --vgdb=yes or --vgdb=full is specified. This allows an external GNU GDB debugger to control and debug your program when it runs on Valgrind. --vgdb=full incurs significant performance overheads, but provides more precise breakpoints and watchpoints. See Debugging your program using Valgrind's gdbserver and GDB for a detailed description.

If the embedded gdbserver is enabled but no gdb is currently being used, the vgdb command line utility can send "monitor commands" to Valgrind from a shell. The Valgrind core provides a set of Valgrind monitor commands. A tool can optionally provide tool specific monitor commands, which are documented in the tool specific chapter.

--vgdb-error=<number> [default: 999999999] Use this option when the Valgrind gdbserver is enabled with --vgdb=yes or --vgdb=full. Tools that report errors will wait for "number" errors to be reported before freezing the program and waiting for you to connect with GDB. It follows that a value of zero will cause the gdbserver to be started before your program is executed. This is typically used to insert GDB breakpoints before execution, and also works with tools that do not report errors, such as Massif.

--vgdb-stop-at=<set> [default: none] Use this option when the Valgrind gdbserver is enabled with --vgdb=yes or --vgdb=full. The Valgrind gdbserver will be invoked for each error after --vgdb-error have been reported. You can additionally ask the Valgrind gdbserver to be invoked for other events, specified in one of the following ways:

• a comma separated list of one or more of startup exit valgrindabexit.

The values startup exit valgrindabexit respectively indicate to invoke gdbserver before your program is executed, after the last instruction of your program, on Valgrind abnormal exit (e.g. internal error, out of memory, ...).

Note: startup and --vgdb-error=0 will both cause Valgrind gdbserver to be invoked before your program is executed. The --vgdb-error=0 will in addition cause your program to stop on all subsequent errors.

• all to specify the complete set. It is equivalent to --vgdb-stop-at=startup,exit,valgrindabexit.

• none for the empty set.

--track-fds=<yes|no|all> [default: no] When enabled, Valgrind will print out a list of open file descriptors on exit or on request, via the gdbserver monitor command v.info open_fds. Along with each file descriptor is printed a stack backtrace of where the file was opened and any details relating to the file descriptor such as the file name or socket details. Use all to include reporting on stdin, stdout and stderr.

--time-stamp=<yes|no> [default: no] When enabled, each message is preceded with an indication of the elapsed wallclock time since startup, expressed as days, hours, minutes, seconds and milliseconds.

--log-fd=<number> [default: 2, stderr] Specifies that Valgrind should send all of its messages to the specified file descriptor. The default, 2, is the standard error channel (stderr). Note that this may interfere with the client's own use of stderr, as Valgrind's output will be interleaved with any output that the client sends to stderr.

--log-file=<filename> Specifies that Valgrind should send all of its messages to the specified file. If the file name is empty, it causes an abort. There are three special format specifiers that can be used in the file name.

%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 OR your program forks without calling exec afterwards, 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. Note: If the program forks and calls exec afterwards, Valgrind output of the child from the period between fork and exec will be lost. Fortunately this gap is really tiny for most programs; and modern programs use posix_spawn anyway.

%n is replaced with a file sequence number unique for this process. This is useful for processes that produces several files from the same filename template.

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

If the file name specifies a relative file name, it is put in the program's initial working directory: this is the current directory when the program started its execution after the fork or after the exec. If it specifies an absolute file name (ie. starts with '/') then it is put there.

--log-socket=<ip-address:port-number> Specifies that Valgrind should send all of its messages to the specified port at the specified IP address. The port may be omitted, in which case port 1500 is used. If a connection cannot be made to the specified socket, Valgrind falls back to writing output to the standard error (stderr). This option is intended to be used in conjunction with the valgrind-listener program. For further details, see the commentary in the manual.