1VALGRIND(1) Release 3.8.0 VALGRIND(1)
2
6 valgrind - a suite of tools for debugging and profiling programs
7
9 valgrind [valgrind-options] [your-program] [your-program-options]
10
12 Valgrind is a flexible program for debugging and profiling Linux
13 executables. It consists of a core, which provides a synthetic CPU in
14 software, and a series of debugging and profiling tools. The
15 architecture is modular, so that new tools can be created easily and
16 without disturbing the existing structure.
17 Some of the options described below work with all Valgrind tools, and
19 some only work with a few or one. The section MEMCHECK OPTIONS and
20 those below it describe tool-specific options.
21 This manual page covers only basic usage and options. For more
23 comprehensive information, please see the HTML documentation on your
24 system: $INSTALL/share/doc/valgrind/html/index.html, or online:
25 http://www.valgrind.org/docs/manual/index.html.
26
28 The single most important option.
29 --tool=<toolname> [default: memcheck]
31 Run the Valgrind tool called toolname, e.g. Memcheck, Cachegrind,
32 etc.
33
35 These options work with all tools.
36 -h --help
38 Show help for all options, both for the core and for the selected
39 tool. If the option is repeated it is equivalent to giving
40 --help-debug.
41 --help-debug
43 Same as --help, but also lists debugging options which usually are
44 only of use to Valgrind's developers.
45 --version
47 Show the version number of the Valgrind core. Tools can have their
48 own version numbers. There is a scheme in place to ensure that
49 tools only execute when the core version is one they are known to
50 work with. This was done to minimise the chances of strange
51 problems arising from tool-vs-core version incompatibilities.
52 -q, --quiet
54 Run silently, and only print error messages. Useful if you are
55 running regression tests or have some other automated test
56 machinery.
57 -v, --verbose
59 Be more verbose. Gives extra information on various aspects of your
60 program, such as: the shared objects loaded, the suppressions used,
61 the progress of the instrumentation and execution engines, and
62 warnings about unusual behaviour. Repeating the option increases
63 the verbosity level.
64 --trace-children=<yes|no> [default: no]
66 When enabled, Valgrind will trace into sub-processes initiated via
67 the exec system call. This is necessary for multi-process programs.
68 Note that Valgrind does trace into the child of a fork (it would be
70 difficult not to, since fork makes an identical copy of a process),
71 so this option is arguably badly named. However, most children of
72 fork calls immediately call exec anyway.
73 --trace-children-skip=patt1,patt2,...
75 This option only has an effect when --trace-children=yes is
76 specified. It allows for some children to be skipped. The option
77 takes a comma separated list of patterns for the names of child
78 executables that Valgrind should not trace into. Patterns may
79 include the metacharacters ? and *, which have the usual meaning.
80 This can be useful for pruning uninteresting branches from a tree
82 of processes being run on Valgrind. But you should be careful when
83 using it. When Valgrind skips tracing into an executable, it
84 doesn't just skip tracing that executable, it also skips tracing
85 any of that executable's child processes. In other words, the flag
86 doesn't merely cause tracing to stop at the specified executables
87 -- it skips tracing of entire process subtrees rooted at any of the
88 specified executables.
89 --trace-children-skip-by-arg=patt1,patt2,...
91 This is the same as --trace-children-skip, with one difference: the
92 decision as to whether to trace into a child process is made by
93 examining the arguments to the child process, rather than the name
94 of its executable.
95 --child-silent-after-fork=<yes|no> [default: no]
97 When enabled, Valgrind will not show any debugging or logging
98 output for the child process resulting from a fork call. This can
99 make the output less confusing (although more misleading) when
100 dealing with processes that create children. It is particularly
101 useful in conjunction with --trace-children=. Use of this option is
102 also strongly recommended if you are requesting XML output
103 (--xml=yes), since otherwise the XML from child and parent may
104 become mixed up, which usually makes it useless.
105 --vgdb=<no|yes|full> [default: yes]
107 Valgrind will provide "gdbserver" functionality when --vgdb=yes or
108 --vgdb=full is specified. This allows an external GNU GDB debugger
109 to control and debug your program when it runs on Valgrind.
110 --vgdb=full incurs significant performance overheads, but provides
111 more precise breakpoints and watchpoints. See ??? for a detailed
112 description.
113 If the embedded gdbserver is enabled but no gdb is currently being
115 used, the ??? command line utility can send "monitor commands" to
116 Valgrind from a shell. The Valgrind core provides a set of ???. A
117 tool can optionally provide tool specific monitor commands, which
118 are documented in the tool specific chapter.
119 --vgdb-error=<number> [default: 999999999]
121 Use this option when the Valgrind gdbserver is enabled with
122 --vgdb=yes or --vgdb=full. Tools that report errors will wait for
123 "number" errors to be reported before freezing the program and
124 waiting for you to connect with GDB. It follows that a value of
125 zero will cause the gdbserver to be started before your program is
126 executed. This is typically used to insert GDB breakpoints before
127 execution, and also works with tools that do not report errors,
128 such as Massif.
129 --track-fds=<yes|no> [default: no]
131 When enabled, Valgrind will print out a list of open file
132 descriptors on exit. Along with each file descriptor is printed a
133 stack backtrace of where the file was opened and any details
134 relating to the file descriptor such as the file name or socket
135 details.
136 --time-stamp=<yes|no> [default: no]
138 When enabled, each message is preceded with an indication of the
139 elapsed wallclock time since startup, expressed as days, hours,
140 minutes, seconds and milliseconds.
141 --log-fd=<number> [default: 2, stderr]
143 Specifies that Valgrind should send all of its messages to the
144 specified file descriptor. The default, 2, is the standard error
145 channel (stderr). Note that this may interfere with the client's
146 own use of stderr, as Valgrind's output will be interleaved with
147 any output that the client sends to stderr.
148 --log-file=<filename>
150 Specifies that Valgrind should send all of its messages to the
151 specified file. If the file name is empty, it causes an abort.
152 There are three special format specifiers that can be used in the
153 file name.
154 %p is replaced with the current process ID. This is very useful for
156 program that invoke multiple processes. WARNING: If you use
157 --trace-children=yes and your program invokes multiple processes OR
158 your program forks without calling exec afterwards, and you don't
159 use this specifier (or the %q specifier below), the Valgrind output
160 from all those processes will go into one file, possibly jumbled
161 up, and possibly incomplete.
162 %q{FOO} is replaced with the contents of the environment variable
164 FOO. If the {FOO} part is malformed, it causes an abort. This
165 specifier is rarely needed, but very useful in certain
166 circumstances (eg. when running MPI programs). The idea is that you
167 specify a variable which will be set differently for each process
168 in the job, for example BPROC_RANK or whatever is applicable in
169 your MPI setup. If the named environment variable is not set, it
170 causes an abort. Note that in some shells, the { and } characters
171 may need to be escaped with a backslash.
172 %% is replaced with %.
174 If an % is followed by any other character, it causes an abort.
176 --log-socket=<ip-address:port-number>
178 Specifies that Valgrind should send all of its messages to the
179 specified port at the specified IP address. The port may be
180 omitted, in which case port 1500 is used. If a connection cannot be
181 made to the specified socket, Valgrind falls back to writing output
182 to the standard error (stderr). This option is intended to be used
183 in conjunction with the valgrind-listener program. For further
184 details, see the commentary in the manual.
185
187 These options are used by all tools that can report errors, e.g.
188 Memcheck, but not Cachegrind.
189 --xml=<yes|no> [default: no]
191 When enabled, the important parts of the output (e.g. tool error
192 messages) will be in XML format rather than plain text.
193 Furthermore, the XML output will be sent to a different output
194 channel than the plain text output. Therefore, you also must use
195 one of --xml-fd, --xml-file or --xml-socket to specify where the
196 XML is to be sent.
197 Less important messages will still be printed in plain text, but
199 because the XML output and plain text output are sent to different
200 output channels (the destination of the plain text output is still
201 controlled by --log-fd, --log-file and --log-socket) this should
202 not cause problems.
203 This option is aimed at making life easier for tools that consume
205 Valgrind's output as input, such as GUI front ends. Currently this
206 option works with Memcheck, Helgrind, DRD and SGcheck. The output
207 format is specified in the file
208 docs/internals/xml-output-protocol4.txt in the source tree for
209 Valgrind 3.5.0 or later.
210 The recommended options for a GUI to pass, when requesting XML
212 output, are: --xml=yes to enable XML output, --xml-file to send the
213 XML output to a (presumably GUI-selected) file, --log-file to send
214 the plain text output to a second GUI-selected file,
215 --child-silent-after-fork=yes, and -q to restrict the plain text
216 output to critical error messages created by Valgrind itself. For
217 example, failure to read a specified suppressions file counts as a
218 critical error message. In this way, for a successful run the text
219 output file will be empty. But if it isn't empty, then it will
220 contain important information which the GUI user should be made
221 aware of.
222 --xml-fd=<number> [default: -1, disabled]
224 Specifies that Valgrind should send its XML output to the specified
225 file descriptor. It must be used in conjunction with --xml=yes.
226 --xml-file=<filename>
228 Specifies that Valgrind should send its XML output to the specified
229 file. It must be used in conjunction with --xml=yes. Any %p or %q
230 sequences appearing in the filename are expanded in exactly the
231 same way as they are for --log-file. See the description of
232 --log-file for details.
233 --xml-socket=<ip-address:port-number>
235 Specifies that Valgrind should send its XML output the specified
236 port at the specified IP address. It must be used in conjunction
237 with --xml=yes. The form of the argument is the same as that used
238 by --log-socket. See the description of --log-socket for further
239 details.
240 --xml-user-comment=<string>
242 Embeds an extra user comment string at the start of the XML output.
243 Only works when --xml=yes is specified; ignored otherwise.
244 --demangle=<yes|no> [default: yes]
246 Enable/disable automatic demangling (decoding) of C++ names.
247 Enabled by default. When enabled, Valgrind will attempt to
248 translate encoded C++ names back to something approaching the
249 original. The demangler handles symbols mangled by g++ versions
250 2.X, 3.X and 4.X.
251 An important fact about demangling is that function names mentioned
253 in suppressions files should be in their mangled form. Valgrind
254 does not demangle function names when searching for applicable
255 suppressions, because to do otherwise would make suppression file
256 contents dependent on the state of Valgrind's demangling machinery,
257 and also slow down suppression matching.
258 --num-callers=<number> [default: 12]
260 Specifies the maximum number of entries shown in stack traces that
261 identify program locations. Note that errors are commoned up using
262 only the top four function locations (the place in the current
263 function, and that of its three immediate callers). So this doesn't
264 affect the total number of errors reported.
265 The maximum value for this is 500. Note that higher settings will
267 make Valgrind run a bit more slowly and take a bit more memory, but
268 can be useful when working with programs with deeply-nested call
269 chains.
270 --error-limit=<yes|no> [default: yes]
272 When enabled, Valgrind stops reporting errors after 10,000,000 in
273 total, or 1,000 different ones, have been seen. This is to stop the
274 error tracking machinery from becoming a huge performance overhead
275 in programs with many errors.
276 --error-exitcode=<number> [default: 0]
278 Specifies an alternative exit code to return if Valgrind reported
279 any errors in the run. When set to the default value (zero), the
280 return value from Valgrind will always be the return value of the
281 process being simulated. When set to a nonzero value, that value is
282 returned instead, if Valgrind detects any errors. This is useful
283 for using Valgrind as part of an automated test suite, since it
284 makes it easy to detect test cases for which Valgrind has reported
285 errors, just by inspecting return codes.
286 --show-below-main=<yes|no> [default: no]
288 By default, stack traces for errors do not show any functions that
289 appear beneath main because most of the time it's uninteresting C
290 library stuff and/or gobbledygook. Alternatively, if main is not
291 present in the stack trace, stack traces will not show any
292 functions below main-like functions such as glibc's
293 __libc_start_main. Furthermore, if main-like functions are present
294 in the trace, they are normalised as (below main), in order to make
295 the output more deterministic.
296 If this option is enabled, all stack trace entries will be shown
298 and main-like functions will not be normalised.
299 --fullpath-after=<string> [default: don't show source paths]
301 By default Valgrind only shows the filenames in stack traces, but
302 not full paths to source files. When using Valgrind in large
303 projects where the sources reside in multiple different
304 directories, this can be inconvenient. --fullpath-after provides a
305 flexible solution to this problem. When this option is present, the
306 path to each source file is shown, with the following all-important
307 caveat: if string is found in the path, then the path up to and
308 including string is omitted, else the path is shown unmodified.
309 Note that string is not required to be a prefix of the path.
310 For example, consider a file named
312 /home/janedoe/blah/src/foo/bar/xyzzy.c. Specifying
313 --fullpath-after=/home/janedoe/blah/src/ will cause Valgrind to
314 show the name as foo/bar/xyzzy.c.
315 Because the string is not required to be a prefix,
317 --fullpath-after=src/ will produce the same output. This is useful
318 when the path contains arbitrary machine-generated characters. For
319 example, the path /my/build/dir/C32A1B47/blah/src/foo/xyzzy can be
320 pruned to foo/xyzzy using --fullpath-after=/blah/src/.
321 If you simply want to see the full path, just specify an empty
323 string: --fullpath-after=. This isn't a special case, merely a
324 logical consequence of the above rules.
325 Finally, you can use --fullpath-after multiple times. Any
327 appearance of it causes Valgrind to switch to producing full paths
328 and applying the above filtering rule. Each produced path is
329 compared against all the --fullpath-after-specified strings, in the
330 order specified. The first string to match causes the path to be
331 truncated as described above. If none match, the full path is
332 shown. This facilitates chopping off prefixes when the sources are
333 drawn from a number of unrelated directories.
334 --suppressions=<filename> [default: $PREFIX/lib/valgrind/default.supp]
336 Specifies an extra file from which to read descriptions of errors
337 to suppress. You may use up to 100 extra suppression files.
338 --gen-suppressions=<yes|no|all> [default: no]
340 When set to yes, Valgrind will pause after every error shown and
341 print the line:
342 ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ----
344 The prompt's behaviour is the same as for the --db-attach option
346 (see below).
347 If you choose to, Valgrind will print out a suppression for this
349 error. You can then cut and paste it into a suppression file if you
350 don't want to hear about the error in the future.
351 When set to all, Valgrind will print a suppression for every
353 reported error, without querying the user.
354 This option is particularly useful with C++ programs, as it prints
356 out the suppressions with mangled names, as required.
357 Note that the suppressions printed are as specific as possible. You
359 may want to common up similar ones, by adding wildcards to function
360 names, and by using frame-level wildcards. The wildcarding
361 facilities are powerful yet flexible, and with a bit of careful
362 editing, you may be able to suppress a whole family of related
363 errors with only a few suppressions.
364 Sometimes two different errors are suppressed by the same
366 suppression, in which case Valgrind will output the suppression
367 more than once, but you only need to have one copy in your
368 suppression file (but having more than one won't cause problems).
369 Also, the suppression name is given as <insert a suppression name
370 here>; the name doesn't really matter, it's only used with the -v
371 option which prints out all used suppression records.
372 --db-attach=<yes|no> [default: no]
374 When enabled, Valgrind will pause after every error shown and print
375 the line:
376 ---- Attach to debugger ? --- [Return/N/n/Y/y/C/c] ----
378 Pressing Ret, or N Ret or n Ret, causes Valgrind not to start a
380 debugger for this error.
381 Pressing Y Ret or y Ret causes Valgrind to start a debugger for the
383 program at this point. When you have finished with the debugger,
384 quit from it, and the program will continue. Trying to continue
385 from inside the debugger doesn't work.
386 Note: if you use GDB, more powerful debugging support is provided
388 by the --vgdb= yes or full value. This activates Valgrind's
389 internal gdbserver, which provides more-or-less full GDB-style
390 control of the application: insertion of breakpoints, continuing
391 from inside GDB, inferior function calls, and much more.
392 C Ret or c Ret causes Valgrind not to start a debugger, and not to
394 ask again.
395 --db-command=<command> [default: gdb -nw %f %p]
397 Specify the debugger to use with the --db-attach command. The
398 default debugger is GDB. This option is a template that is expanded
399 by Valgrind at runtime. %f is replaced with the executable's file
400 name and %p is replaced by the process ID of the executable.
401 This specifies how Valgrind will invoke the debugger. By default it
403 will use whatever GDB is detected at build time, which is usually
404 /usr/bin/gdb. Using this command, you can specify some alternative
405 command to invoke the debugger you want to use.
406 The command string given can include one or instances of the %p and
408 %f expansions. Each instance of %p expands to the PID of the
409 process to be debugged and each instance of %f expands to the path
410 to the executable for the process to be debugged.
411 Since <command> is likely to contain spaces, you will need to put
413 this entire option in quotes to ensure it is correctly handled by
414 the shell.
415 --input-fd=<number> [default: 0, stdin]
417 When using --db-attach=yes or --gen-suppressions=yes, Valgrind will
418 stop so as to read keyboard input from you when each error occurs.
419 By default it reads from the standard input (stdin), which is
420 problematic for programs which close stdin. This option allows you
421 to specify an alternative file descriptor from which to read input.
422 --dsymutil=no|yes [no]
424 This option is only relevant when running Valgrind on Mac OS X.
425 Mac OS X uses a deferred debug information (debuginfo) linking
427 scheme. When object files containing debuginfo are linked into a
428 .dylib or an executable, the debuginfo is not copied into the final
429 file. Instead, the debuginfo must be linked manually by running
430 dsymutil, a system-provided utility, on the executable or .dylib.
431 The resulting combined debuginfo is placed in a directory alongside
432 the executable or .dylib, but with the extension .dSYM.
433 With --dsymutil=no, Valgrind will detect cases where the .dSYM
435 directory is either missing, or is present but does not appear to
436 match the associated executable or .dylib, most likely because it
437 is out of date. In these cases, Valgrind will print a warning
438 message but take no further action.
439 With --dsymutil=yes, Valgrind will, in such cases, automatically
441 run dsymutil as necessary to bring the debuginfo up to date. For
442 all practical purposes, if you always use --dsymutil=yes, then
443 there is never any need to run dsymutil manually or as part of your
444 applications's build system, since Valgrind will run it as
445 necessary.
446 Valgrind will not attempt to run dsymutil on any executable or
448 library in /usr/, /bin/, /sbin/, /opt/, /sw/, /System/, /Library/
449 or /Applications/ since dsymutil will always fail in such
450 situations. It fails both because the debuginfo for such
451 pre-installed system components is not available anywhere, and also
452 because it would require write privileges in those directories.
453 Be careful when using --dsymutil=yes, since it will cause
455 pre-existing .dSYM directories to be silently deleted and
456 re-created. Also note that dsymutil is quite slow, sometimes
457 excessively so.
458 --max-stackframe=<number> [default: 2000000]
460 The maximum size of a stack frame. If the stack pointer moves by
461 more than this amount then Valgrind will assume that the program is
462 switching to a different stack.
463 You may need to use this option if your program has large
465 stack-allocated arrays. Valgrind keeps track of your program's
466 stack pointer. If it changes by more than the threshold amount,
467 Valgrind assumes your program is switching to a different stack,
468 and Memcheck behaves differently than it would for a stack pointer
469 change smaller than the threshold. Usually this heuristic works
470 well. However, if your program allocates large structures on the
471 stack, this heuristic will be fooled, and Memcheck will
472 subsequently report large numbers of invalid stack accesses. This
473 option allows you to change the threshold to a different value.
474 You should only consider use of this option if Valgrind's debug
476 output directs you to do so. In that case it will tell you the new
477 threshold you should specify.
478 In general, allocating large structures on the stack is a bad idea,
480 because you can easily run out of stack space, especially on
481 systems with limited memory or which expect to support large
482 numbers of threads each with a small stack, and also because the
483 error checking performed by Memcheck is more effective for
484 heap-allocated data than for stack-allocated data. If you have to
485 use this option, you may wish to consider rewriting your code to
486 allocate on the heap rather than on the stack.
487 --main-stacksize=<number> [default: use current 'ulimit' value]
489 Specifies the size of the main thread's stack.
490 To simplify its memory management, Valgrind reserves all required
492 space for the main thread's stack at startup. That means it needs
493 to know the required stack size at startup.
494 By default, Valgrind uses the current "ulimit" value for the stack
496 size, or 16 MB, whichever is lower. In many cases this gives a
497 stack size in the range 8 to 16 MB, which almost never overflows
498 for most applications.
499 If you need a larger total stack size, use --main-stacksize to
501 specify it. Only set it as high as you need, since reserving far
502 more space than you need (that is, hundreds of megabytes more than
503 you need) constrains Valgrind's memory allocators and may reduce
504 the total amount of memory that Valgrind can use. This is only
505 really of significance on 32-bit machines.
506 On Linux, you may request a stack of size up to 2GB. Valgrind will
508 stop with a diagnostic message if the stack cannot be allocated.
509 --main-stacksize only affects the stack size for the program's
511 initial thread. It has no bearing on the size of thread stacks, as
512 Valgrind does not allocate those.
513 You may need to use both --main-stacksize and --max-stackframe
515 together. It is important to understand that --main-stacksize sets
516 the maximum total stack size, whilst --max-stackframe specifies the
517 largest size of any one stack frame. You will have to work out the
518 --main-stacksize value for yourself (usually, if your applications
519 segfaults). But Valgrind will tell you the needed --max-stackframe
520 size, if necessary.
521 As discussed further in the description of --max-stackframe, a
523 requirement for a large stack is a sign of potential portability
524 problems. You are best advised to place all large data in
525 heap-allocated memory.
526
528 For tools that use their own version of malloc (e.g. Memcheck, Massif,
529 Helgrind, DRD), the following options apply.
530 --alignment=<number> [default: 8 or 16, depending on the platform]
532 By default Valgrind's malloc, realloc, etc, return a block whose
533 starting address is 8-byte aligned or 16-byte aligned (the value
534 depends on the platform and matches the platform default). This
535 option allows you to specify a different alignment. The supplied
536 value must be greater than or equal to the default, less than or
537 equal to 4096, and must be a power of two.
538 --redzone-size=<number> [default: depends on the tool]
540 Valgrind's malloc, realloc, etc, add padding blocks before and
541 after each heap block allocated by the program being run. Such
542 padding blocks are called redzones. The default value for the
543 redzone size depends on the tool. For example, Memcheck adds and
544 protects a minimum of 16 bytes before and after each block
545 allocated by the client. This allows it to detect block underruns
546 or overruns of up to 16 bytes.
547 Increasing the redzone size makes it possible to detect overruns of
549 larger distances, but increases the amount of memory used by
550 Valgrind. Decreasing the redzone size will reduce the memory needed
551 by Valgrind but also reduces the chances of detecting
552 over/underruns, so is not recommended.
553
555 These options apply to all tools, as they affect certain obscure
556 workings of the Valgrind core. Most people won't need to use them.
557 --smc-check=<none|stack|all|all-non-file> [default: stack]
559 This option controls Valgrind's detection of self-modifying code.
560 If no checking is done, if a program executes some code, then
561 overwrites it with new code, and executes the new code, Valgrind
562 will continue to execute the translations it made for the old code.
563 This will likely lead to incorrect behaviour and/or crashes.
564 Valgrind has four levels of self-modifying code detection: no
566 detection, detect self-modifying code on the stack (which is used
567 by GCC to implement nested functions), detect self-modifying code
568 everywhere, and detect self-modifying code everywhere except in
569 file-backed mappings. Note that the default option will catch the
570 vast majority of cases. The main case it will not catch is programs
571 such as JIT compilers that dynamically generate code and
572 subsequently overwrite part or all of it. Running with all will
573 slow Valgrind down noticeably. Running with none will rarely speed
574 things up, since very little code gets put on the stack for most
575 programs. The VALGRIND_DISCARD_TRANSLATIONS client request is an
576 alternative to --smc-check=all that requires more programmer effort
577 but allows Valgrind to run your program faster, by telling it
578 precisely when translations need to be re-made.
579 --smc-check=all-non-file provides a cheaper but more limited
581 version of --smc-check=all. It adds checks to any translations that
582 do not originate from file-backed memory mappings. Typical
583 applications that generate code, for example JITs in web browsers,
584 generate code into anonymous mmaped areas, whereas the "fixed" code
585 of the browser always lives in file-backed mappings.
586 --smc-check=all-non-file takes advantage of this observation,
587 limiting the overhead of checking to code which is likely to be JIT
588 generated.
589 Some architectures (including ppc32, ppc64, ARM and MIPS) require
591 programs which create code at runtime to flush the instruction
592 cache in between code generation and first use. Valgrind observes
593 and honours such instructions. Hence, on ppc32/Linux, ppc64/Linux
594 and ARM/Linux, Valgrind always provides complete, transparent
595 support for self-modifying code. It is only on platforms such as
596 x86/Linux, AMD64/Linux, x86/Darwin and AMD64/Darwin that you need
597 to use this option.
598 --read-var-info=<yes|no> [default: no]
600 When enabled, Valgrind will read information about variable types
601 and locations from DWARF3 debug info. This slows Valgrind down and
602 makes it use more memory, but for the tools that can take advantage
603 of it (Memcheck, Helgrind, DRD) it can result in more precise error
604 messages. For example, here are some standard errors issued by
605 Memcheck:
606 ==15516== Uninitialised byte(s) found during client check request
608 ==15516== at 0x400633: croak (varinfo1.c:28)
609 ==15516== by 0x4006B2: main (varinfo1.c:55)
610 ==15516== Address 0x60103b is 7 bytes inside data symbol "global_i2"
611 ==15516==
612 ==15516== Uninitialised byte(s) found during client check request
613 ==15516== at 0x400633: croak (varinfo1.c:28)
614 ==15516== by 0x4006BC: main (varinfo1.c:56)
615 ==15516== Address 0x7fefffefc is on thread 1's stack
616 And here are the same errors with --read-var-info=yes:
618 ==15522== Uninitialised byte(s) found during client check request
620 ==15522== at 0x400633: croak (varinfo1.c:28)
621 ==15522== by 0x4006B2: main (varinfo1.c:55)
622 ==15522== Location 0x60103b is 0 bytes inside global_i2[7],
623 ==15522== a global variable declared at varinfo1.c:41
624 ==15522==
625 ==15522== Uninitialised byte(s) found during client check request
626 ==15522== at 0x400633: croak (varinfo1.c:28)
627 ==15522== by 0x4006BC: main (varinfo1.c:56)
628 ==15522== Location 0x7fefffefc is 0 bytes inside local var "local"
629 ==15522== declared at varinfo1.c:46, in frame #1 of thread 1
630 --vgdb-poll=<number> [default: 5000]
632 As part of its main loop, the Valgrind scheduler will poll to check
633 if some activity (such as an external command or some input from a
634 gdb) has to be handled by gdbserver. This activity poll will be
635 done after having run the given number of basic blocks (or slightly
636 more than the given number of basic blocks). This poll is quite
637 cheap so the default value is set relatively low. You might further
638 decrease this value if vgdb cannot use ptrace system call to
639 interrupt Valgrind if all threads are (most of the time) blocked in
640 a system call.
641 --vgdb-shadow-registers=no|yes [default: no]
643 When activated, gdbserver will expose the Valgrind shadow registers
644 to GDB. With this, the value of the Valgrind shadow registers can
645 be examined or changed using GDB. Exposing shadow registers only
646 works with GDB version 7.1 or later.
647 --vgdb-prefix=<prefix> [default: /tmp/vgdb-pipe]
649 To communicate with gdb/vgdb, the Valgrind gdbserver creates 3
650 files (2 named FIFOs and a mmap shared memory file). The prefix
651 option controls the directory and prefix for the creation of these
652 files.
653 --run-libc-freeres=<yes|no> [default: yes]
655 This option is only relevant when running Valgrind on Linux.
656 The GNU C library (libc.so), which is used by all programs, may
658 allocate memory for its own uses. Usually it doesn't bother to free
659 that memory when the program ends—there would be no point, since
660 the Linux kernel reclaims all process resources when a process
661 exits anyway, so it would just slow things down.
662 The glibc authors realised that this behaviour causes leak
664 checkers, such as Valgrind, to falsely report leaks in glibc, when
665 a leak check is done at exit. In order to avoid this, they provided
666 a routine called __libc_freeres specifically to make glibc release
667 all memory it has allocated. Memcheck therefore tries to run
668 __libc_freeres at exit.
669 Unfortunately, in some very old versions of glibc, __libc_freeres
671 is sufficiently buggy to cause segmentation faults. This was
672 particularly noticeable on Red Hat 7.1. So this option is provided
673 in order to inhibit the run of __libc_freeres. If your program
674 seems to run fine on Valgrind, but segfaults at exit, you may find
675 that --run-libc-freeres=no fixes that, although at the cost of
676 possibly falsely reporting space leaks in libc.so.
677 --sim-hints=hint1,hint2,...
679 Pass miscellaneous hints to Valgrind which slightly modify the
680 simulated behaviour in nonstandard or dangerous ways, possibly to
681 help the simulation of strange features. By default no hints are
682 enabled. Use with caution! Currently known hints are:
683 · lax-ioctls: Be very lax about ioctl handling; the only
685 assumption is that the size is correct. Doesn't require the
686 full buffer to be initialized when writing. Without this, using
687 some device drivers with a large number of strange ioctl
688 commands becomes very tiresome.
689 · enable-outer: Enable some special magic needed when the program
691 being run is itself Valgrind.
692 · no-inner-prefix: Disable printing a prefix > in front of each
694 stdout or stderr output line in an inner Valgrind being run by
695 an outer Valgrind. This is useful when running Valgrind
696 regression tests in an outer/inner setup. Note that the prefix
697 > will always be printed in front of the inner debug logging
698 lines.
699 · fuse-compatible: Enable special handling for certain system
701 calls that may block in a FUSE file-system. This may be
702 necessary when running Valgrind on a multi-threaded program
703 that uses one thread to manage a FUSE file-system and another
704 thread to access that file-system.
705 --fair-sched=<no|yes|try> [default: no]
707 The --fair-sched option controls the locking mechanism used by
708 Valgrind to serialise thread execution. The locking mechanism
709 controls the way the threads are scheduled, and different settings
710 give different trade-offs between fairness and performance. For
711 more details about the Valgrind thread serialisation scheme and its
712 impact on performance and thread scheduling, see ???.
713 · The value --fair-sched=yes activates a fair scheduler. In
715 short, if multiple threads are ready to run, the threads will
716 be scheduled in a round robin fashion. This mechanism is not
717 available on all platforms or Linux versions. If not available,
718 using --fair-sched=yes will cause Valgrind to terminate with an
719 error.
720 You may find this setting improves overall responsiveness if
722 you are running an interactive multithreaded program, for
723 example a web browser, on Valgrind.
724 · The value --fair-sched=try activates fair scheduling if
726 available on the platform. Otherwise, it will automatically
727 fall back to --fair-sched=no.
728 · The value --fair-sched=no activates a scheduler which does not
730 guarantee fairness between threads ready to run, but which in
731 general gives the highest performance.
732 --kernel-variant=variant1,variant2,...
735 Handle system calls and ioctls arising from minor variants of the
736 default kernel for this platform. This is useful for running on
737 hacked kernels or with kernel modules which support nonstandard
738 ioctls, for example. Use with caution. If you don't understand what
739 this option does then you almost certainly don't need it. Currently
740 known variants are:
741 · bproc: Support the sys_broc system call on x86. This is for
743 running on BProc, which is a minor variant of standard Linux
744 which is sometimes used for building clusters.
745 --show-emwarns=<yes|no> [default: no]
747 When enabled, Valgrind will emit warnings about its CPU emulation
748 in certain cases. These are usually not interesting.
749 --require-text-symbol=:sonamepatt:fnnamepatt
751 When a shared object whose soname matches sonamepatt is loaded into
752 the process, examine all the text symbols it exports. If none of
753 those match fnnamepatt, print an error message and abandon the run.
754 This makes it possible to ensure that the run does not continue
755 unless a given shared object contains a particular function name.
756 Both sonamepatt and fnnamepatt can be written using the usual ?
758 and * wildcards. For example: ":*libc.so*:foo?bar". You may use
759 characters other than a colon to separate the two patterns. It is
760 only important that the first character and the separator character
761 are the same. For example, the above example could also be written
762 "Q*libc.so*Qfoo?bar". Multiple
763 --require-text-symbol flags are allowed, in which case shared
764 objects that are loaded into the process will be checked against
765 all of them.
766 The purpose of this is to support reliable usage of marked-up
768 libraries. For example, suppose we have a version of GCC's
769 libgomp.so which has been marked up with annotations to support
770 Helgrind. It is only too easy and confusing to load the wrong,
771 un-annotated libgomp.so into the application. So the idea is: add a
772 text symbol in the marked-up library, for example
773 annotated_for_helgrind_3_6, and then give the flag
774 --require-text-symbol=:*libgomp*so*:annotated_for_helgrind_3_6 so
775 that when libgomp.so is loaded, Valgrind scans its symbol table,
776 and if the symbol isn't present the run is aborted, rather than
777 continuing silently with the un-marked-up library. Note that you
778 should put the entire flag in quotes to stop shells expanding up
779 the * and ? wildcards.
780 --soname-synonyms=syn1=pattern1,syn2=pattern2,...
782 When a shared library is loaded, Valgrind checks for functions in
783 the library that must be replaced or wrapped. For example, Memcheck
784 replaces all malloc related functions (malloc, free, calloc, ...)
785 with its own versions. Such replacements are done by default only
786 in shared libraries whose soname matches a predefined soname
787 pattern (e.g. libc.so* on linux). By default, no replacement is
788 done for a statically linked library or for alternative libraries
789 such as tcmalloc. In some cases, the replacements allow
790 --soname-synonyms to specify one additional synonym pattern, giving
791 flexibility in the replacement.
792 Currently, this flexibility is only allowed for the malloc related
794 functions, using the synonym somalloc. This synonym is usable for
795 all tools doing standard replacement of malloc related functions
796 (e.g. memcheck, massif, drd, helgrind, exp-dhat, exp-sgcheck).
797 · Alternate malloc library: to replace the malloc related
799 functions in an alternate library with soname mymalloclib.so,
800 give the option --soname-synonyms=somalloc=mymalloclib.so. A
801 pattern can be used to match multiple libraries sonames. For
802 example, --soname-synonyms=somalloc=*tcmalloc* will match the
803 soname of all variants of the tcmalloc library (native, debug,
804 profiled, ... tcmalloc variants).
805 Note: the soname of a elf shared library can be retrieved using
807 the readelf utility.
808 · Replacements in a statically linked library are done by using
810 the NONE pattern. For example, if you link with libtcmalloc.a,
811 memcheck will properly work when you give the option
812 --soname-synonyms=somalloc=NONE. Note that a NONE pattern will
813 match the main executable and any shared library having no
814 soname.
815 · To run a "default" Firefox build for Linux, in which JEMalloc
817 is linked in to the main executable, use
818 --soname-synonyms=somalloc=NONE.
819
821 There are also some options for debugging Valgrind itself. You
822 shouldn't need to use them in the normal run of things. If you wish to
823 see the list, use the --help-debug option.
824
826 --leak-check=<no|summary|yes|full> [default: summary]
827 When enabled, search for memory leaks when the client program
828 finishes. If set to summary, it says how many leaks occurred. If
829 set to full or yes, it also gives details of each individual leak.
830 --show-possibly-lost=<yes|no> [default: yes]
832 When disabled, the memory leak detector will not show "possibly
833 lost" blocks.
834 --leak-resolution=<low|med|high> [default: high]
836 When doing leak checking, determines how willing Memcheck is to
837 consider different backtraces to be the same for the purposes of
838 merging multiple leaks into a single leak report. When set to low,
839 only the first two entries need match. When med, four entries have
840 to match. When high, all entries need to match.
841 For hardcore leak debugging, you probably want to use
843 --leak-resolution=high together with --num-callers=40 or some such
844 large number.
845 Note that the --leak-resolution setting does not affect Memcheck's
847 ability to find leaks. It only changes how the results are
848 presented.
849 --show-reachable=<yes|no> [default: no]
851 When disabled, the memory leak detector only shows "definitely
852 lost" and "possibly lost" blocks. When enabled, the leak detector
853 also shows "reachable" and "indirectly lost" blocks. (In other
854 words, it shows all blocks, except suppressed ones, so --show-all
855 would be a better name for it.)
856 --undef-value-errors=<yes|no> [default: yes]
858 Controls whether Memcheck reports uses of undefined value errors.
859 Set this to no if you don't want to see undefined value errors. It
860 also has the side effect of speeding up Memcheck somewhat.
861 --track-origins=<yes|no> [default: no]
863 Controls whether Memcheck tracks the origin of uninitialised
864 values. By default, it does not, which means that although it can
865 tell you that an uninitialised value is being used in a dangerous
866 way, it cannot tell you where the uninitialised value came from.
867 This often makes it difficult to track down the root problem.
868 When set to yes, Memcheck keeps track of the origins of all
870 uninitialised values. Then, when an uninitialised value error is
871 reported, Memcheck will try to show the origin of the value. An
872 origin can be one of the following four places: a heap block, a
873 stack allocation, a client request, or miscellaneous other sources
874 (eg, a call to brk).
875 For uninitialised values originating from a heap block, Memcheck
877 shows where the block was allocated. For uninitialised values
878 originating from a stack allocation, Memcheck can tell you which
879 function allocated the value, but no more than that -- typically it
880 shows you the source location of the opening brace of the function.
881 So you should carefully check that all of the function's local
882 variables are initialised properly.
883 Performance overhead: origin tracking is expensive. It halves
885 Memcheck's speed and increases memory use by a minimum of 100MB,
886 and possibly more. Nevertheless it can drastically reduce the
887 effort required to identify the root cause of uninitialised value
888 errors, and so is often a programmer productivity win, despite
889 running more slowly.
890 Accuracy: Memcheck tracks origins quite accurately. To avoid very
892 large space and time overheads, some approximations are made. It is
893 possible, although unlikely, that Memcheck will report an incorrect
894 origin, or not be able to identify any origin.
895 Note that the combination --track-origins=yes and
897 --undef-value-errors=no is nonsensical. Memcheck checks for and
898 rejects this combination at startup.
899 --partial-loads-ok=<yes|no> [default: no]
901 Controls how Memcheck handles word-sized, word-aligned loads from
902 addresses for which some bytes are addressable and others are not.
903 When yes, such loads do not produce an address error. Instead,
904 loaded bytes originating from illegal addresses are marked as
905 uninitialised, and those corresponding to legal addresses are
906 handled in the normal way.
907 When no, loads from partially invalid addresses are treated the
909 same as loads from completely invalid addresses: an illegal-address
910 error is issued, and the resulting bytes are marked as initialised.
911 Note that code that behaves in this way is in violation of the the
913 ISO C/C++ standards, and should be considered broken. If at all
914 possible, such code should be fixed. This option should be used
915 only as a last resort.
916 --freelist-vol=<number> [default: 20000000]
918 When the client program releases memory using free (in C) or delete
919 (C++), that memory is not immediately made available for
920 re-allocation. Instead, it is marked inaccessible and placed in a
921 queue of freed blocks. The purpose is to defer as long as possible
922 the point at which freed-up memory comes back into circulation.
923 This increases the chance that Memcheck will be able to detect
924 invalid accesses to blocks for some significant period of time
925 after they have been freed.
926 This option specifies the maximum total size, in bytes, of the
928 blocks in the queue. The default value is twenty million bytes.
929 Increasing this increases the total amount of memory used by
930 Memcheck but may detect invalid uses of freed blocks which would
931 otherwise go undetected.
932 --freelist-big-blocks=<number> [default: 1000000]
934 When making blocks from the queue of freed blocks available for
935 re-allocation, Memcheck will in priority re-circulate the blocks
936 with a size greater or equal to --freelist-big-blocks. This ensures
937 that freeing big blocks (in particular freeing blocks bigger than
938 --freelist-vol) does not immediately lead to a re-circulation of
939 all (or a lot of) the small blocks in the free list. In other
940 words, this option increases the likelihood to discover dangling
941 pointers for the "small" blocks, even when big blocks are freed.
942 Setting a value of 0 means that all the blocks are re-circulated in
944 a FIFO order.
945 --workaround-gcc296-bugs=<yes|no> [default: no]
947 When enabled, assume that reads and writes some small distance
948 below the stack pointer are due to bugs in GCC 2.96, and does not
949 report them. The "small distance" is 256 bytes by default. Note
950 that GCC 2.96 is the default compiler on some ancient Linux
951 distributions (RedHat 7.X) and so you may need to use this option.
952 Do not use it if you do not have to, as it can cause real errors to
953 be overlooked. A better alternative is to use a more recent GCC in
954 which this bug is fixed.
955 You may also need to use this option when working with GCC 3.X or
957 4.X on 32-bit PowerPC Linux. This is because GCC generates code
958 which occasionally accesses below the stack pointer, particularly
959 for floating-point to/from integer conversions. This is in
960 violation of the 32-bit PowerPC ELF specification, which makes no
961 provision for locations below the stack pointer to be accessible.
962 --ignore-ranges=0xPP-0xQQ[,0xRR-0xSS]
964 Any ranges listed in this option (and multiple ranges can be
965 specified, separated by commas) will be ignored by Memcheck's
966 addressability checking.
967 --malloc-fill=<hexnumber>
969 Fills blocks allocated by malloc, new, etc, but not by calloc, with
970 the specified byte. This can be useful when trying to shake out
971 obscure memory corruption problems. The allocated area is still
972 regarded by Memcheck as undefined -- this option only affects its
973 contents. Note that --malloc-fill does not affect a block of memory
974 when it is used as argument to client requests
975 VALGRIND_MEMPOOL_ALLOC or VALGRIND_MALLOCLIKE_BLOCK.
976 --free-fill=<hexnumber>
978 Fills blocks freed by free, delete, etc, with the specified byte
979 value. This can be useful when trying to shake out obscure memory
980 corruption problems. The freed area is still regarded by Memcheck
981 as not valid for access -- this option only affects its contents.
982 Note that --free-fill does not affect a block of memory when it is
983 used as argument to client requests VALGRIND_MEMPOOL_FREE or
984 VALGRIND_FREELIKE_BLOCK.
985
987 --I1=<size>,<associativity>,<line size>
988 Specify the size, associativity and line size of the level 1
989 instruction cache.
990 --D1=<size>,<associativity>,<line size>
992 Specify the size, associativity and line size of the level 1 data
993 cache.
994 --LL=<size>,<associativity>,<line size>
996 Specify the size, associativity and line size of the last-level
997 cache.
998 --cache-sim=no|yes [yes]
1000 Enables or disables collection of cache access and miss counts.
1001 --branch-sim=no|yes [no]
1003 Enables or disables collection of branch instruction and
1004 misprediction counts. By default this is disabled as it slows
1005 Cachegrind down by approximately 25%. Note that you cannot specify
1006 --cache-sim=no and --branch-sim=no together, as that would leave
1007 Cachegrind with no information to collect.
1008 --cachegrind-out-file=<file>
1010 Write the profile data to file rather than to the default output
1011 file, cachegrind.out.<pid>. The %p and %q format specifiers can be
1012 used to embed the process ID and/or the contents of an environment
1013 variable in the name, as is the case for the core option --log-
1014 file.
1015
1017 --callgrind-out-file=<file>
1018 Write the profile data to file rather than to the default output
1019 file, callgrind.out.<pid>. The %p and %q format specifiers can be
1020 used to embed the process ID and/or the contents of an environment
1021 variable in the name, as is the case for the core option --log-
1022 file. When multiple dumps are made, the file name is modified
1023 further; see below.
1024 --dump-line=<no|yes> [default: yes]
1026 This specifies that event counting should be performed at source
1027 line granularity. This allows source annotation for sources which
1028 are compiled with debug information (-g).
1029 --dump-instr=<no|yes> [default: no]
1031 This specifies that event counting should be performed at
1032 per-instruction granularity. This allows for assembly code
1033 annotation. Currently the results can only be displayed by
1034 KCachegrind.
1035 --compress-strings=<no|yes> [default: yes]
1037 This option influences the output format of the profile data. It
1038 specifies whether strings (file and function names) should be
1039 identified by numbers. This shrinks the file, but makes it more
1040 difficult for humans to read (which is not recommended in any
1041 case).
1042 --compress-pos=<no|yes> [default: yes]
1044 This option influences the output format of the profile data. It
1045 specifies whether numerical positions are always specified as
1046 absolute values or are allowed to be relative to previous numbers.
1047 This shrinks the file size.
1048 --combine-dumps=<no|yes> [default: no]
1050 When enabled, when multiple profile data parts are to be generated
1051 these parts are appended to the same output file. Not recommended.
1052 --dump-every-bb=<count> [default: 0, never]
1054 Dump profile data every count basic blocks. Whether a dump is
1055 needed is only checked when Valgrind's internal scheduler is run.
1056 Therefore, the minimum setting useful is about 100000. The count is
1057 a 64-bit value to make long dump periods possible.
1058 --dump-before=<function>
1060 Dump when entering function.
1061 --zero-before=<function>
1063 Zero all costs when entering function.
1064 --dump-after=<function>
1066 Dump when leaving function.
1067 --instr-atstart=<yes|no> [default: yes]
1069 Specify if you want Callgrind to start simulation and profiling
1070 from the beginning of the program. When set to no, Callgrind will
1071 not be able to collect any information, including calls, but it
1072 will have at most a slowdown of around 4, which is the minimum
1073 Valgrind overhead. Instrumentation can be interactively enabled via
1074 callgrind_control -i on.
1075 Note that the resulting call graph will most probably not contain
1077 main, but will contain all the functions executed after
1078 instrumentation was enabled. Instrumentation can also
1079 programatically enabled/disabled. See the Callgrind include file
1080 callgrind.h for the macro you have to use in your source code.
1081 For cache simulation, results will be less accurate when switching
1083 on instrumentation later in the program run, as the simulator
1084 starts with an empty cache at that moment. Switch on event
1085 collection later to cope with this error.
1086 --collect-atstart=<yes|no> [default: yes]
1088 Specify whether event collection is enabled at beginning of the
1089 profile run.
1090 To only look at parts of your program, you have two possibilities:
1092 1. Zero event counters before entering the program part you want
1094 to profile, and dump the event counters to a file after leaving
1095 that program part.
1096 2. Switch on/off collection state as needed to only see event
1098 counters happening while inside of the program part you want to
1099 profile.
1100 The second option can be used if the program part you want to
1102 profile is called many times. Option 1, i.e. creating a lot of
1103 dumps is not practical here.
1104 Collection state can be toggled at entry and exit of a given
1106 function with the option --toggle-collect. If you use this option,
1107 collection state should be disabled at the beginning. Note that the
1108 specification of --toggle-collect implicitly sets
1109 --collect-state=no.
1110 Collection state can be toggled also by inserting the client
1112 request CALLGRIND_TOGGLE_COLLECT ; at the needed code positions.
1113 --toggle-collect=<function>
1115 Toggle collection on entry/exit of function.
1116 --collect-jumps=<no|yes> [default: no]
1118 This specifies whether information for (conditional) jumps should
1119 be collected. As above, callgrind_annotate currently is not able to
1120 show you the data. You have to use KCachegrind to get jump arrows
1121 in the annotated code.
1122 --collect-systime=<no|yes> [default: no]
1124 This specifies whether information for system call times should be
1125 collected.
1126 --collect-bus=<no|yes> [default: no]
1128 This specifies whether the number of global bus events executed
1129 should be collected. The event type "Ge" is used for these events.
1130 --cache-sim=<yes|no> [default: no]
1132 Specify if you want to do full cache simulation. By default, only
1133 instruction read accesses will be counted ("Ir"). With cache
1134 simulation, further event counters are enabled: Cache misses on
1135 instruction reads ("I1mr"/"ILmr"), data read accesses ("Dr") and
1136 related cache misses ("D1mr"/"DLmr"), data write accesses ("Dw")
1137 and related cache misses ("D1mw"/"DLmw"). For more information, see
1138 ???.
1139 --branch-sim=<yes|no> [default: no]
1141 Specify if you want to do branch prediction simulation. Further
1142 event counters are enabled: Number of executed conditional branches
1143 and related predictor misses ("Bc"/"Bcm"), executed indirect jumps
1144 and related misses of the jump address predictor ("Bi"/"Bim").
1145
1147 --free-is-write=no|yes [default: no]
1148 When enabled (not the default), Helgrind treats freeing of heap
1149 memory as if the memory was written immediately before the free.
1150 This exposes races where memory is referenced by one thread, and
1151 freed by another, but there is no observable synchronisation event
1152 to ensure that the reference happens before the free.
1153 This functionality is new in Valgrind 3.7.0, and is regarded as
1155 experimental. It is not enabled by default because its interaction
1156 with custom memory allocators is not well understood at present.
1157 User feedback is welcomed.
1158 --track-lockorders=no|yes [default: yes]
1160 When enabled (the default), Helgrind performs lock order
1161 consistency checking. For some buggy programs, the large number of
1162 lock order errors reported can become annoying, particularly if
1163 you're only interested in race errors. You may therefore find it
1164 helpful to disable lock order checking.
1165 --history-level=none|approx|full [default: full]
1167 --history-level=full (the default) causes Helgrind collects enough
1168 information about "old" accesses that it can produce two stack
1169 traces in a race report -- both the stack trace for the current
1170 access, and the trace for the older, conflicting access. To limit
1171 memory usage, "old" accesses stack traces are limited to a maximum
1172 of 8 entries, even if --num-callers value is bigger.
1173 Collecting such information is expensive in both speed and memory,
1175 particularly for programs that do many inter-thread synchronisation
1176 events (locks, unlocks, etc). Without such information, it is more
1177 difficult to track down the root causes of races. Nonetheless, you
1178 may not need it in situations where you just want to check for the
1179 presence or absence of races, for example, when doing regression
1180 testing of a previously race-free program.
1181 --history-level=none is the opposite extreme. It causes Helgrind
1183 not to collect any information about previous accesses. This can be
1184 dramatically faster than --history-level=full.
1185 --history-level=approx provides a compromise between these two
1187 extremes. It causes Helgrind to show a full trace for the later
1188 access, and approximate information regarding the earlier access.
1189 This approximate information consists of two stacks, and the
1190 earlier access is guaranteed to have occurred somewhere between
1191 program points denoted by the two stacks. This is not as useful as
1192 showing the exact stack for the previous access (as
1193 --history-level=full does), but it is better than nothing, and it
1194 is almost as fast as --history-level=none.
1195 --conflict-cache-size=N [default: 1000000]
1197 This flag only has any effect at --history-level=full.
1198 Information about "old" conflicting accesses is stored in a cache
1200 of limited size, with LRU-style management. This is necessary
1201 because it isn't practical to store a stack trace for every single
1202 memory access made by the program. Historical information on not
1203 recently accessed locations is periodically discarded, to free up
1204 space in the cache.
1205 This option controls the size of the cache, in terms of the number
1207 of different memory addresses for which conflicting access
1208 information is stored. If you find that Helgrind is showing race
1209 errors with only one stack instead of the expected two stacks, try
1210 increasing this value.
1211 The minimum value is 10,000 and the maximum is 30,000,000 (thirty
1213 times the default value). Increasing the value by 1 increases
1214 Helgrind's memory requirement by very roughly 100 bytes, so the
1215 maximum value will easily eat up three extra gigabytes or so of
1216 memory.
1217 --check-stack-refs=no|yes [default: yes]
1219 By default Helgrind checks all data memory accesses made by your
1220 program. This flag enables you to skip checking for accesses to
1221 thread stacks (local variables). This can improve performance, but
1222 comes at the cost of missing races on stack-allocated data.
1223
1225 --check-stack-var=<yes|no> [default: no]
1226 Controls whether DRD detects data races on stack variables.
1227 Verifying stack variables is disabled by default because most
1228 programs do not share stack variables over threads.
1229 --exclusive-threshold=<n> [default: off]
1231 Print an error message if any mutex or writer lock has been held
1232 longer than the time specified in milliseconds. This option enables
1233 the detection of lock contention.
1234 --join-list-vol=<n> [default: 10]
1236 Data races that occur between a statement at the end of one thread
1237 and another thread can be missed if memory access information is
1238 discarded immediately after a thread has been joined. This option
1239 allows to specify for how many joined threads memory access
1240 information should be retained.
1241 --first-race-only=<yes|no> [default: no]
1243 Whether to report only the first data race that has been detected
1244 on a memory location or all data races that have been detected on a
1245 memory location.
1246 --free-is-write=<yes|no> [default: no]
1248 Whether to report races between accessing memory and freeing
1249 memory. Enabling this option may cause DRD to run slightly slower.
1250 Notes:
1251 · Don't enable this option when using custom memory allocators
1253 that use the VG_USERREQ__MALLOCLIKE_BLOCK and
1254 VG_USERREQ__FREELIKE_BLOCK because that would result in false
1255 positives.
1256 · Don't enable this option when using reference-counted objects
1258 because that will result in false positives, even when that
1259 code has been annotated properly with ANNOTATE_HAPPENS_BEFORE
1260 and ANNOTATE_HAPPENS_AFTER. See e.g. the output of the
1261 following command for an example: valgrind --tool=drd
1262 --free-is-write=yes drd/tests/annotate_smart_pointer.
1263 --report-signal-unlocked=<yes|no> [default: yes]
1266 Whether to report calls to pthread_cond_signal and
1267 pthread_cond_broadcast where the mutex associated with the signal
1268 through pthread_cond_wait or pthread_cond_timed_waitis not locked
1269 at the time the signal is sent. Sending a signal without holding a
1270 lock on the associated mutex is a common programming error which
1271 can cause subtle race conditions and unpredictable behavior. There
1272 exist some uncommon synchronization patterns however where it is
1273 safe to send a signal without holding a lock on the associated
1274 mutex.
1275 --segment-merging=<yes|no> [default: yes]
1277 Controls segment merging. Segment merging is an algorithm to limit
1278 memory usage of the data race detection algorithm. Disabling
1279 segment merging may improve the accuracy of the so-called 'other
1280 segments' displayed in race reports but can also trigger an out of
1281 memory error.
1282 --segment-merging-interval=<n> [default: 10]
1284 Perform segment merging only after the specified number of new
1285 segments have been created. This is an advanced configuration
1286 option that allows to choose whether to minimize DRD's memory usage
1287 by choosing a low value or to let DRD run faster by choosing a
1288 slightly higher value. The optimal value for this parameter depends
1289 on the program being analyzed. The default value works well for
1290 most programs.
1291 --shared-threshold=<n> [default: off]
1293 Print an error message if a reader lock has been held longer than
1294 the specified time (in milliseconds). This option enables the
1295 detection of lock contention.
1296 --show-confl-seg=<yes|no> [default: yes]
1298 Show conflicting segments in race reports. Since this information
1299 can help to find the cause of a data race, this option is enabled
1300 by default. Disabling this option makes the output of DRD more
1301 compact.
1302 --show-stack-usage=<yes|no> [default: no]
1304 Print stack usage at thread exit time. When a program creates a
1305 large number of threads it becomes important to limit the amount of
1306 virtual memory allocated for thread stacks. This option makes it
1307 possible to observe how much stack memory has been used by each
1308 thread of the the client program. Note: the DRD tool itself
1309 allocates some temporary data on the client thread stack. The space
1310 necessary for this temporary data must be allocated by the client
1311 program when it allocates stack memory, but is not included in
1312 stack usage reported by DRD.
1313 --trace-addr=<address> [default: none]
1315 Trace all load and store activity for the specified address. This
1316 option may be specified more than once.
1317 --ptrace-addr=<address> [default: none]
1319 Trace all load and store activity for the specified address and
1320 keep doing that even after the memory at that address has been
1321 freed and reallocated.
1322 --trace-alloc=<yes|no> [default: no]
1324 Trace all memory allocations and deallocations. May produce a huge
1325 amount of output.
1326 --trace-barrier=<yes|no> [default: no]
1328 Trace all barrier activity.
1329 --trace-cond=<yes|no> [default: no]
1331 Trace all condition variable activity.
1332 --trace-fork-join=<yes|no> [default: no]
1334 Trace all thread creation and all thread termination events.
1335 --trace-hb=<yes|no> [default: no]
1337 Trace execution of the ANNOTATE_HAPPENS_BEFORE(),
1338 ANNOTATE_HAPPENS_AFTER() and ANNOTATE_HAPPENS_DONE() client
1339 requests.
1340 --trace-mutex=<yes|no> [default: no]
1342 Trace all mutex activity.
1343 --trace-rwlock=<yes|no> [default: no]
1345 Trace all reader-writer lock activity.
1346 --trace-semaphore=<yes|no> [default: no]
1348 Trace all semaphore activity.
1349
1351 --heap=<yes|no> [default: yes]
1352 Specifies whether heap profiling should be done.
1353 --heap-admin=<size> [default: 8]
1355 If heap profiling is enabled, gives the number of administrative
1356 bytes per block to use. This should be an estimate of the average,
1357 since it may vary. For example, the allocator used by glibc on
1358 Linux requires somewhere between 4 to 15 bytes per block, depending
1359 on various factors. That allocator also requires admin space for
1360 freed blocks, but Massif cannot account for this.
1361 --stacks=<yes|no> [default: no]
1363 Specifies whether stack profiling should be done. This option slows
1364 Massif down greatly, and so is off by default. Note that Massif
1365 assumes that the main stack has size zero at start-up. This is not
1366 true, but doing otherwise accurately is difficult. Furthermore,
1367 starting at zero better indicates the size of the part of the main
1368 stack that a user program actually has control over.
1369 --pages-as-heap=<yes|no> [default: no]
1371 Tells Massif to profile memory at the page level rather than at the
1372 malloc'd block level. See above for details.
1373 --depth=<number> [default: 30]
1375 Maximum depth of the allocation trees recorded for detailed
1376 snapshots. Increasing it will make Massif run somewhat more slowly,
1377 use more memory, and produce bigger output files.
1378 --alloc-fn=<name>
1380 Functions specified with this option will be treated as though they
1381 were a heap allocation function such as malloc. This is useful for
1382 functions that are wrappers to malloc or new, which can fill up the
1383 allocation trees with uninteresting information. This option can be
1384 specified multiple times on the command line, to name multiple
1385 functions.
1386 Note that the named function will only be treated this way if it is
1388 the top entry in a stack trace, or just below another function
1389 treated this way. For example, if you have a function malloc1 that
1390 wraps malloc, and malloc2 that wraps malloc1, just specifying
1391 --alloc-fn=malloc2 will have no effect. You need to specify
1392 --alloc-fn=malloc1 as well. This is a little inconvenient, but the
1393 reason is that checking for allocation functions is slow, and it
1394 saves a lot of time if Massif can stop looking through the stack
1395 trace entries as soon as it finds one that doesn't match rather
1396 than having to continue through all the entries.
1397 Note that C++ names are demangled. Note also that overloaded C++
1399 names must be written in full. Single quotes may be necessary to
1400 prevent the shell from breaking them up. For example:
1401 --alloc-fn='operator new(unsigned, std::nothrow_t const&)'
1403 --ignore-fn=<name>
1406 Any direct heap allocation (i.e. a call to malloc, new, etc, or a
1407 call to a function named by an --alloc-fn option) that occurs in a
1408 function specified by this option will be ignored. This is mostly
1409 useful for testing purposes. This option can be specified multiple
1410 times on the command line, to name multiple functions.
1411 Any realloc of an ignored block will also be ignored, even if the
1413 realloc call does not occur in an ignored function. This avoids the
1414 possibility of negative heap sizes if ignored blocks are shrunk
1415 with realloc.
1416 The rules for writing C++ function names are the same as for
1418 --alloc-fn above.
1419 --threshold=<m.n> [default: 1.0]
1421 The significance threshold for heap allocations, as a percentage of
1422 total memory size. Allocation tree entries that account for less
1423 than this will be aggregated. Note that this should be specified in
1424 tandem with ms_print's option of the same name.
1425 --peak-inaccuracy=<m.n> [default: 1.0]
1427 Massif does not necessarily record the actual global memory
1428 allocation peak; by default it records a peak only when the global
1429 memory allocation size exceeds the previous peak by at least 1.0%.
1430 This is because there can be many local allocation peaks along the
1431 way, and doing a detailed snapshot for every one would be expensive
1432 and wasteful, as all but one of them will be later discarded. This
1433 inaccuracy can be changed (even to 0.0%) via this option, but
1434 Massif will run drastically slower as the number approaches zero.
1435 --time-unit=<i|ms|B> [default: i]
1437 The time unit used for the profiling. There are three
1438 possibilities: instructions executed (i), which is good for most
1439 cases; real (wallclock) time (ms, i.e. milliseconds), which is
1440 sometimes useful; and bytes allocated/deallocated on the heap
1441 and/or stack (B), which is useful for very short-run programs, and
1442 for testing purposes, because it is the most reproducible across
1443 different machines.
1444 --detailed-freq=<n> [default: 10]
1446 Frequency of detailed snapshots. With --detailed-freq=1, every
1447 snapshot is detailed.
1448 --max-snapshots=<n> [default: 100]
1450 The maximum number of snapshots recorded. If set to N, for all
1451 programs except very short-running ones, the final number of
1452 snapshots will be between N/2 and N.
1453 --massif-out-file=<file> [default: massif.out.%p]
1455 Write the profile data to file rather than to the default output
1456 file, massif.out.<pid>. The %p and %q format specifiers can be used
1457 to embed the process ID and/or the contents of an environment
1458 variable in the name, as is the case for the core option --log-
1459 file.
1460
1462 <xi:include></xi:include>.SH "BBV OPTIONS"
1463 --bb-out-file=<name> [default: bb.out.%p]
1465 This option selects the name of the basic block vector file. The %p
1466 and %q format specifiers can be used to embed the process ID and/or
1467 the contents of an environment variable in the name, as is the case
1468 for the core option --log-file.
1469 --pc-out-file=<name> [default: pc.out.%p]
1471 This option selects the name of the PC file. This file holds
1472 program counter addresses and function name info for the various
1473 basic blocks. This can be used in conjunction with the basic block
1474 vector file to fast-forward via function names instead of just
1475 instruction counts. The %p and %q format specifiers can be used to
1476 embed the process ID and/or the contents of an environment variable
1477 in the name, as is the case for the core option --log-file.
1478 --interval-size=<number> [default: 100000000]
1480 This option selects the size of the interval to use. The default is
1481 100 million instructions, which is a commonly used value. Other
1482 sizes can be used; smaller intervals can help programs with
1483 finer-grained phases. However smaller interval size can lead to
1484 accuracy issues due to warm-up effects (When fast-forwarding the
1485 various architectural features will be un-initialized, and it will
1486 take some number of instructions before they "warm up" to the state
1487 a full simulation would be at without the fast-forwarding. Large
1488 interval sizes tend to mitigate this.)
1489 --instr-count-only [default: no]
1491 This option tells the tool to only display instruction count
1492 totals, and to not generate the actual basic block vector file.
1493 This is useful for debugging, and for gathering instruction count
1494 info without generating the large basic block vector files.
1495
1497 --basic-counts=<no|yes> [default: yes]
1498 When enabled, Lackey prints the following statistics and
1499 information about the execution of the client program:
1500 1. The number of calls to the function specified by the --fnname
1502 option (the default is main). If the program has had its
1503 symbols stripped, the count will always be zero.
1504 2. The number of conditional branches encountered and the number
1506 and proportion of those taken.
1507 3. The number of superblocks entered and completed by the program.
1509 Note that due to optimisations done by the JIT, this is not at
1510 all an accurate value.
1511 4. The number of guest (x86, amd64, ppc, etc.) instructions and IR
1513 statements executed. IR is Valgrind's RISC-like intermediate
1514 representation via which all instrumentation is done.
1515 5. Ratios between some of these counts.
1517 6. The exit code of the client program.
1519 --detailed-counts=<no|yes> [default: no]
1521 When enabled, Lackey prints a table containing counts of loads,
1522 stores and ALU operations, differentiated by their IR types. The IR
1523 types are identified by their IR name ("I1", "I8", ... "I128",
1524 "F32", "F64", and "V128").
1525 --trace-mem=<no|yes> [default: no]
1527 When enabled, Lackey prints the size and address of almost every
1528 memory access made by the program. See the comments at the top of
1529 the file lackey/lk_main.c for details about the output format, how
1530 it works, and inaccuracies in the address trace. Note that this
1531 option produces immense amounts of output.
1532 --trace-superblocks=<no|yes> [default: no]
1534 When enabled, Lackey prints out the address of every superblock (a
1535 single entry, multiple exit, linear chunk of code) executed by the
1536 program. This is primarily of interest to Valgrind developers. See
1537 the comments at the top of the file lackey/lk_main.c for details
1538 about the output format. Note that this option produces large
1539 amounts of output.
1540 --fnname=<name> [default: main]
1542 Changes the function for which calls are counted when
1543 --basic-counts=yes is specified.
1544
1546 cg_annotate(1), callgrind_annotate(1), callgrind_control(1),
1547 ms_print(1), $INSTALL/share/doc/valgrind/html/index.html or
1548 http://www.valgrind.org/docs/manual/index.html.
1549
1551 The Valgrind developers.
1552 This manpage was written by Andres Roldan <aroldan@debian.org> and the
1554 Valgrind developers.
1555Release 3.8.0 09/18/2012 VALGRIND(1)