valgrind
VALGRIND(1) VALGRIND(1)
NAME
valgrind - a suite of tools for debugging and profiling programs
SYNOPSIS
valgrind [valgrind options] your-program [your-program options]
DESCRIPTION
valgrind is a flexible program for debugging and profiling Linux exe-
cutables. 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.
INVOCATION
valgrind is typically invoked as follows:
valgrind program args
This runs program (with arguments args) under valgrind using the mem-
check tool. memcheck performs a range of memory-checking functions,
including detecting accesses to uninitialized memory, misuse of allo-
cated 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 typi-
cally 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-chil-
dren=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 track-
ing 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 subse-
quent runs.
Pressing Ret or n Ret or N Ret will cause no sup-
pression 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 val-
grind 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 out-
put 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. <file-
name>.<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 val-
grind 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 loca-
tions. You can change that number with this
option. This can help in determining the pro-
gram’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. Use-
ful 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 back-
traces 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/val-
grind/default.supp]
Specifies an extra file from which to read
descriptions of errors to suppress. You may spec-
ify 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 pro-
cesses. 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 exe-
cution of file descriptors that are still in use.
-v --verbose
Be more verbose. Gives extra information on vari-
ous 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.
MEMCHECK OPTIONS
--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 mem-
check 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 mem-
ory is printed. When no leak checking is per-
formed, 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 address-
ible 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 corre-
sponding to legal addresses are considered
defined.
When disabled, loads from partially invalid
addresses are treated the same as loads from com-
pletely 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 com-
piler 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.
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 instruc-
tion) 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 speci-
fied, 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 instruc-
tion) is used.
MASSIF OPTIONS
--alloc-fn=<name>
Specify a function that allocates memory. This
is useful for functions that are wrappers to mal-
loc(), 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 func-
tions.
--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.
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 most processors.
Some programs might however assume that malloc et
al return 16- or more aligned memory. These pro-
grams are broken and should be fixed, but if this
is impossible for whatever reason the alignment
can be increased using this parameter. The sup-
plied 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 specifi-
cally 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 notice-
able 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 non-
standard 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. Speci-
fying 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.
CORE DEBUGGING OPTIONS
Valgrind has several debugging options that are mostly
of use to developers. Use --help-debug to show them.
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, and other Valgrind developers subse-
quently.
VALGRIND(1)
