valgrind is a flexible program for debugging and profiling Linux-x86
executables. It consists of a core, which provides a synthetic x86 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.
INVOCATION
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:
- addrcheck
addrcheck is similar to memcheck, but does not perform the same
granularity of memory checking. This will run faster and use less memory,
but may miss some problems that memcheck would catch.
- cachegrind
cachegrind is a cache simulator.
." .TP
." .B
." - helgrind
." helgrind spots potential race conditions in your program.
- 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.
COMMON CORE OPTIONS
--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.
--error-limit=<yes|no> [default: yes]
When enabled, valgrind stops reporting errors after 30000 in total,
or 300 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> [default: no]
When enabled, valgrind will pause after every error shown and
print the line:
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.
-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.
--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, ".pid" and the process ID, so as to create a file
per process. The specified file name may not be the empty string.
--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 errors are commoned up using only
the top three function locations (the place in the current function,
and that of its two 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.
--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.
--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 is
confusing and usually not what you want, so is disabled by default.
--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.
ADDRCHECK OPTIONS
--freelist-vol=<number> [default: 1000000]
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 addrcheck 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 addrcheck 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 addrcheck 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: yes]
Controls how addrcheck 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, addrcheck
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 addrcheck 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.
MEMCHECK OPTIONS
memcheck understands the same options as addrcheck, along
with the following options:
--avoid-strlen-errors=<yes|no> [default: yes]
Enable or disable a heuristic for dealing with highly-optimized versions
of strlen. These versions of strlen can cause spurious
errors to be reported by memcheck, so it's usually a good idea to
leave this enabled.
--cleanup=<yes|no> [default: yes]
This is a flag to help debug valgrind itself. It is of no use to
end-users. When enabled, various improvments are applied to the
post-instrumented intermediate code, aimed at removing redundant value
checks.
CACHEGRIND OPTIONS
--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.
MASSIF OPTIONS
--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.
." .SH HELGRIND OPTIONS
." .TP
." .B
." --private-stacks=<yes|no> [default: no]
." Assume thread stacks are used privately.
." .TP
." .B
." --show-last-access=<yes|some|no> [default: no]
." Show location of last word access on error.
LESS FREQUENTLY USED CORE OPTIONS
--alignment=<number> [default: 8]
By default valgrind's malloc, realloc, etc, return 8-byte aligned
addresses. These are suitable for any accesses on x86 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.
--branchpred=<yes|no> [default: no]
This option enables the generation of static branch prediction hints.
In theory this allows the real CPU to do a better job of running the
generated code, but in practice it makes almost no measurable difference.
It may have a large effect on some x86 implementations.
--chain-bb=<yes|no> [default: yes]
Enables basic-block chaining. If basic-block chaining is disabled,
the synthetic CPU returns to the scheduler after interpreting each basic
block. With basic block chaining enabled, it can immediately proceed to
the next basic block. This almost always results in a performance gain,
so it is enabled by default.
--command-line-only=<yes|no> [default: no]
Normally, valgrind will look for command-line options in the
following locations:
- The valgrind command line
- The .valgrindrc file in the invocation directory
- The .valgrindrc file in users home directory
- The $VALGRIND_OPTS environment variable
When this option is enabled, valgrind will only look at the command
line for options.
--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 and 3.X.
--dump-error=<number>
After the program has exited, show gory details of the translation of
the basic block containing the <number>'th error context. When
used with --single-step=yes, can show the exact x86 instruction causing
an error. This is all fairly dodgy and doesn't work at all if threads
are involved.
--exec=<filename>
Specify the executable to run. If this is specified, it takes precedence
over the your-program executable from the command-line. If this is
not specified, valgrind searches the path for the your-program
executable, just like a regular shell would.
--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 this may interfere with the client's own
use of stderr.
--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.
--optimise=<yes|no> [default: yes]
When enabled, various improvements are applied to the intermediate code,
mainly aimed at allowing the simulated CPU's registers to be cached in
the real CPU's registers over several simulated instructions.
--pointercheck=<yes|no> [default: yes]
When enabled, enforces client address space limits. If this option is
disabled, the client program has full and unfettered access to the part
of the address space used internally by valgrind. This can cause
unexplained crashes and false error reports, so it is best left enabled.
--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.
--show-below-main=<yes|no> [default: no]
When enabled, this option causes full stack backtraces to be emited,
including the part before main 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.
--single-step=<yes|no> [default: no]
When enabled, each x86 insn is translated separately into instrumented
code. When disabled, translation is done on a per-basic-block basis,
giving much better translations. This is needed when running
valgrind under valgrind.
--sloppy-malloc=<yes|no> [default: no]
When enabled, valgrind rounds all memory allocation request sizes
up to 4 bytes.
--time-stamp=<yes|no> [default: no]
When enabled, a time-stamp is added to all log messages.
--weird-hacks=hack1,hack2,...
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 hacks are enabled. Use
with caution! Currently known hacks 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.
- ioctl-mmap
Tell valgrind to search for new memory mappings after an unknown
ioctl call.
CORE DEBUGGING OPTIONS
--profile=<yes|no> [default: no]
When enabled, does crude internal profiling of valgrind itself. This
is not for profiling your programs. Rather it is to allow the developers
to assess where valgrind is spending its time. The tools must be
built for profiling for this to work.
--sanity-level=<number> [default: 1]
Set the level of sanity checking to perform. This is used for debugging
valgrind. Setting this to 2 or higher can cause more internal
sanity checks to be performed, but can slow your program down
appreciably. Setting this to 0 disables sanity checks.
--trace-codegen=<bitmask>
Produce lots of output showing exactly how valgrind is translating
each basic block. The argument to this option is a 5-bit wide bitmask.
Each bit refers to a specific feature to trace. If the bit is 1, the
feature is traced. If it is 0, the feature is not traced.
The traced features are:
Bit 1: basic-block disassembly
Bit 2: optimization phase
Bit 3: tool instrumentation
Bit 4: register allocation
Bit 5: final code generation
--trace-malloc=<yes|no> [default: no]
Enable or disable tracing of malloc, free and other memory-manager calls.
--trace-redir=<yes|no> [default: no]
Enable or disable tracing of function redirection.
--trace-sched=<yes|no> [default: no]
Enable or disable tracing of thread scheduling events.
--trace-signals=<yes|no> [default: no]
Enable or disable tracing of signal handling.
--trace-syscalls=<yes|no> [default: no]
Enable or disable tracing of system call intercepts.
--trace-symtab=<yes|no> [default: no]
Enable or disable tracing of symbol table reading.
SEE ALSO
/usr/share/doc/valgrind/html/manual.html
AUTHOR
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.
