valgrind - a suite of tools for debugging and profiling programs

valgrind [valgrind options] your-program [your-program options]

valgrind is a flexible program for debugging and profiling Linux executables. It consists of a core, which provides a synthetic CPU in software, and a series of "tools", each of which is a debugging or profiling tool. The architecture is modular, so that new tools can be created easily and without disturbing the existing structure.

This manual page covers only basic usage and options. Please see the HTML documentation for more comprehensive information.

valgrind is typically invoked as follows:

valgrind program args

This runs program (with arguments args) under valgrind using the memcheck tool. memcheck performs a range of memory-checking functions, including detecting accesses to uninitialized memory, misuse of allocated memory (double frees, access after free, etc.) and detecting memory leaks.

To use a different tool, use the --tool option:

valgrind --tool=toolname program args

The following tools are available:

- cachegrind cachegrind is a cache simulator. It can be used to annotate every line of your program with the number of instructions executed and cache misses incurred.

- lackey lackey is a sample tool that can be used as a template for generating your own tools. After the program terminates, it prints out some basic statistics about the program execution.

- massif massif is a heap profiler. It measures how much heap memory your program uses.

- memcheck memcheck is a fine-grained memory checker.

- none none performs no function - it simply runs the program under valgrind. This is typically used for debugging and benchmarking valgrind.

--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 the debugger (specified by the --db-command option) 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.

Pressing C Ret or c Ret causes valgrind not to start the debugger and valgrind will not ask again.

--db-attach=yes conflicts with --trace-children=yes. You can't use them together. valgrind refuses to start up in this situation. 1 May 2002: this is a historical relic which could be easily fixed if it gets in your way. Mail me 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.

--demangle=<yes|no> [default: yes] Enable or disable automatic demangling (decoding) of C++ names. Enabled by default. When enabled, valgrind will attempt to translate encoded C++ procedure names back to something approaching the original. The demangler handles symbols mangled by g++ versions 2.X, 3.X and 4.X.

--error-limit=<yes|no> [default: yes] When enabled, valgrind stops reporting errors after 100000 in total, or 1000 different ones, have been seen. This is to stop the error tracking machinery from becoming a huge performance overhead in programs with many errors.

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

Pressing Y Ret or y Ret will cause a suppression for this error to be printed. This suppression can be cut-and-paste into a custom suppressions file and used to suppress this error in subsequent runs.

Pressing Ret or n Ret or N Ret will cause no suppression to be printed.

Pressing C Ret or c Ret will cause no suppression to be printed and valgrind will not ask again.

When set to ll, valgrind will print suppressions for all errors without asking any questions.

-h --help Show help for all options, both for the core and for the selected tool.

--help-debug Show help for all options, both for the core and for the selected tool, including options for debugging valgrind.

--input-fd=<number> [default: 0, stdin] Specify the file descriptor to use for reading input from the user. This is used whenever valgrind needs to prompt the user for a decision.

--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 in this case 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. In fact, the file name used is created by concatenating the text filename and the process ID (ie. <filename>.<pid>), so as to create a file per process. The specified file name may not be the empty string.

--log-file-exactly=<filename> Just like --log-file, but the pid suffix is not added. If you trace multiple processes with Valgrind when using this option the log file may get all messed up.

--log-file-qualifier=<VAR> Specifies that valgrind should send all of its messages to the file named by the environment variable $VAR. This is useful when running MPI programs.

--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 section 2.3 of the user manual.

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

--num-callers=<number> [default: 12] By default, valgrind shows 12 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 in most cases 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.

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

--show-below-main=<yes|no> [default: no] When enabled, this option causes full stack backtraces to be emited, including the part before main (or similar functions such as glibc's __libc_start_main, if main is not present in the stack trace) in your program (subject to the --num-callers option.) When disabled, only the part of the stack backtrace up to and including main is printed.

--suppressions=<filename> [default: $PREFIX/lib/valgrind/default.supp] Specifies an extra file from which to read descriptions of errors to suppress. You may specify up to 10 additional suppression files.

--time-stamp=<yes|no> [default: no] When enabled, a time-stamp is added to all log messages. It shows how long has elapsed since the client program started.

--tool=<toolname> [default: memcheck] Specify which tool to use. The default tool is memcheck.

--trace-children=<yes|no> [default: no] When enabled, valgrind will trace into child processes. This can be confusing and usually not what you want, so is disabled by default. But it is necessary is some cases, particularly if your program is started by a script.

--track-fds=<yes|no> [default: no] Track file descriptor creation and deletion and produce a summary at the end of the program execution of file descriptors that are still in use.

-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 flag increases the verbosity level.

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

--xml=<yes|no> [default: no] Generate output in XML format. Only memcheck and nulgrind currently support this option.

--xml-user-comment=<string> The specified string will be output at the start of the XML file if XML output is requested.

--freelist-vol=<number> [default: 5000000] When the client program releases memory using free (in C) or delete (C++), that memory is not immediately made available for re-allocation. Instead it is marked inaccessible and placed in a queue of freed blocks. The purpose is to delay the point at which freed-up memory comes back into circulation. This increases the chance that memcheck will be able to detect invalid accesses to blocks for some significant period of time after they have been freed.

This flag specifies the maximum total size, in bytes, of the blocks in the queue. The default value is one 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.

--leak-check=<yes|no|summary|full> [default: summary] Enables full, summary or no leak checking. When full (full or yes options) checking is performed, details on all leaked blocks are printed after the program finishes executing. When summary checking is enabled, a summary of all leaked memory is printed. When no leak checking is performed, no leaked memory details are produced. Disabling leak checking can speed up your program execution.

--leak-resolution=<low|med|high> [default: low] When doing leak checking, determines how willing memcheck is to consider different backtraces to be the same. When set to low, the default, only the first two entries need match. When med, four entries have to match. When high, all entries need to match.

--partial-loads-ok=<yes|no> [default: no] Controls how memcheck handles word (4-byte) loads from addresses for which some bytes are addressible and others are not. When enabled, such loads do not elicit an address error. Instead, memcheck considers the bytes corresponding to the illegal addresses as undefined, and those corresponding to legal addresses are considered defined.

When disabled, loads from partially invalid addresses are treated the same as loads from completely invalid addresses: an illegal-address error is issued, and the memcheck considers all bytes as invalid data.

--show-reachable=<yes|no> [default: no] When performing full leak checking, print out details of blocks that are leaked but still reachable. For details of what a reachable block is, see the HTML documentation.

--workaround-gcc296-bugs=<yes|no> [default: no] When enabled, assume that reads and writes some small distance below the stack pointer %esp are due to bugs in gcc 2.96, and does not report them. The "small distance" is 256 bytes by default. Note that gcc 2.96 is the default compiler on some older Linux distributions (RedHat 7.X, Mandrake) and so you may well need to use this flag. Do not use it if you do not have to, as it can cause real errors to be overlooked. Another option is to use a gcc/g++ which does not generate accesses below the stack pointer. 2.95.3 seems to be a good choice in this respect.

--D1=<size>,<associativity>,<line size> Specify the size, associativity and line size of the level 1 data cache. All values are measured in bytes. If this options is not specified, the system value (as retrieved by the CPUID instruction) is used.

--I1=<size>,<associativity>,<line size> Specify the size, associativity and line size of the level 1 instruction cache. All values are measured in bytes. If this options is not specified, the system value (as retrieved by the CPUID instruction) is used.

--L2=<size>,<associativity>,<line size> Specify the size, associativity and line size of the level 2 cache. All values are measured in bytes. If this options is not specified, the system value (as retrieved by the CPUID instruction) is used.

--alloc-fn=<name> Specify a function that allocates memory. This is useful for functions that are wrappers to malloc(), which can fill up the context information uselessly (and give very uninformative bands on the graph). Functions specified will be ignored in contexts, i.e. treated as though they were malloc(). This option can be specified multiple times on the command line, to name multiple functions.

--depth=<number> [default: 3] Depth of call chains to present in the detailed heap information. Increasing it will give more information, but massif will run the program more slowly, using more memory, and produce a bigger .txt or .hp file.

--format=<text|html> [default: text] Produce the detailed heap information in text or HTML format. The file suffix used will be either .txt or .html.

--heap=<yes|no> [default: yes] When enabled, profile heap usage in detail. Without it, the .txt or .html file will be very short.

--heap-admin=<number> [default: 8] The number of admin bytes per block to use. This can only be an estimate of the average, since it may vary. The allocator used by glibc requires somewhere between 4 to 15 bytes per block, depending on various factors. It also requires admin space for freed blocks, although massif does not count this.

--stacks=<yes|no> [default: yes] When enabled, include stack(s) in the profile. Threaded programs can have multiple stacks.

--alignment=<number> [default: 8] By default valgrind's malloc, realloc, etc, return 8-byte aligned addresses. These are suitable for any accesses on most processors. Some programs might however assume that malloc et al return 16- or more aligned memory. These programs are broken and should be fixed, but if this is impossible for whatever reason the alignment can be increased using this parameter. The supplied value must be between 8 and 4096 inclusive, and must be a power of two.

--run-libc-freeres=<yes|no> [default: yes] The GNU C library (libc.so), which is used by all programs, may allocate memory for its own uses. Usually it doesn't bother to free that memory when the program ends - there would be no point, since the Linux kernel reclaims all process resources when a process exits anyway, so it would just slow things down.

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. The MemCheck and AddrCheck tools therefore try and run __libc_freeres at exit.

Unfortunately, in some versions of glibc, __libc_freeres is sufficiently buggy to cause segmentation faults. This is 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.

--sim-hints=hint1,hint2,... Pass miscellaneous hints to valgrind which slightly modify the simulated behaviour in nonstandard or dangerous ways, possibly to help the simulation of strange features. By default no hints are enabled. Use with caution! Currently known hints are:

- lax-ioctls If valgrind encounters an ioctl that it doesn't understand, it normally prints a warning message before continuing. Specifying the lax-ioctls hack tells valgrind to be very lax about ioctl handling and assume that unknown ioctls just behave correctly.

- enable-outer Enable some special magic needed when the program being run is itself valgrind.

--smc-check=<none|stack|all> [default: stack] Control which areas of memory valgrind should consider might contain self modifying code.

Valgrind has several debugging options that are mostly of use to developers. Use --help-debug to show them.

/usr/share/doc/valgrind/html/manual.html

Julian Seward <jseward@acm.org> is the original author of valgrind and there are other contributors listed on /usr/share/doc/valgrind/AUTHORS.

This manpage has been written by Andres Roldan <aroldan@debian.org> for the Debian Project, but can be used for any other distribution. Updated, rearranged and expanded by Robert Walsh <rjwalsh@durables.org> for the 2.4.0 release, and other Valgrind developers subsequently.