1VALGRIND(1)                        valgrind                        VALGRIND(1)
2
3
4

NAME

6       valgrind - a suite of tools for debugging and profiling programs
7

SYNOPSIS

9       valgrind [valgrind-options] [your-program] [your-program-options]
10

DESCRIPTION

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
18       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
22       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

TOOL SELECTION OPTIONS

28       The single most important option.
29
30       --tool=<toolname> [default: memcheck]
31           Run the Valgrind tool called toolname, e.g. memcheck, cachegrind,
32           callgrind, helgrind, drd, massif, dhat, lackey, none, exp-bbv, etc.
33

BASIC OPTIONS

35       These options work with all tools.
36
37       -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
42       --help-debug
43           Same as --help, but also lists debugging options which usually are
44           only of use to Valgrind's developers.
45
46       --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
53       -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
58       -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
65       --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
69           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
74       --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
81           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
90       --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
96       --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
106       --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 Debugging your
112           program using Valgrind's gdbserver and GDB for a detailed
113           description.
114
115           If the embedded gdbserver is enabled but no gdb is currently being
116           used, the vgdb command line utility can send "monitor commands" to
117           Valgrind from a shell. The Valgrind core provides a set of Valgrind
118           monitor commands. A tool can optionally provide tool specific
119           monitor commands, which are documented in the tool specific
120           chapter.
121
122       --vgdb-error=<number> [default: 999999999]
123           Use this option when the Valgrind gdbserver is enabled with
124           --vgdb=yes or --vgdb=full. Tools that report errors will wait for
125           "number" errors to be reported before freezing the program and
126           waiting for you to connect with GDB. It follows that a value of
127           zero will cause the gdbserver to be started before your program is
128           executed. This is typically used to insert GDB breakpoints before
129           execution, and also works with tools that do not report errors,
130           such as Massif.
131
132       --vgdb-stop-at=<set> [default: none]
133           Use this option when the Valgrind gdbserver is enabled with
134           --vgdb=yes or --vgdb=full. The Valgrind gdbserver will be invoked
135           for each error after --vgdb-error have been reported. You can
136           additionally ask the Valgrind gdbserver to be invoked for other
137           events, specified in one of the following ways:
138
139           •   a comma separated list of one or more of startup exit
140               valgrindabexit.
141
142               The values startup exit valgrindabexit respectively indicate to
143               invoke gdbserver before your program is executed, after the
144               last instruction of your program, on Valgrind abnormal exit
145               (e.g. internal error, out of memory, ...).
146
147               Note: startup and --vgdb-error=0 will both cause Valgrind
148               gdbserver to be invoked before your program is executed. The
149               --vgdb-error=0 will in addition cause your program to stop on
150               all subsequent errors.
151
152all to specify the complete set. It is equivalent to
153               --vgdb-stop-at=startup,exit,valgrindabexit.
154
155none for the empty set.
156
157       --track-fds=<yes|no|all> [default: no]
158           When enabled, Valgrind will print out a list of open file
159           descriptors on exit or on request, via the gdbserver monitor
160           command v.info open_fds. Along with each file descriptor is printed
161           a stack backtrace of where the file was opened and any details
162           relating to the file descriptor such as the file name or socket
163           details. Use all to include reporting on stdin, stdout and stderr.
164
165       --time-stamp=<yes|no> [default: no]
166           When enabled, each message is preceded with an indication of the
167           elapsed wallclock time since startup, expressed as days, hours,
168           minutes, seconds and milliseconds.
169
170       --log-fd=<number> [default: 2, stderr]
171           Specifies that Valgrind should send all of its messages to the
172           specified file descriptor. The default, 2, is the standard error
173           channel (stderr). Note that this may interfere with the client's
174           own use of stderr, as Valgrind's output will be interleaved with
175           any output that the client sends to stderr.
176
177       --log-file=<filename>
178           Specifies that Valgrind should send all of its messages to the
179           specified file. If the file name is empty, it causes an abort.
180           There are three special format specifiers that can be used in the
181           file name.
182
183           %p is replaced with the current process ID. This is very useful for
184           program that invoke multiple processes. WARNING: If you use
185           --trace-children=yes and your program invokes multiple processes OR
186           your program forks without calling exec afterwards, and you don't
187           use this specifier (or the %q specifier below), the Valgrind output
188           from all those processes will go into one file, possibly jumbled
189           up, and possibly incomplete. Note: If the program forks and calls
190           exec afterwards, Valgrind output of the child from the period
191           between fork and exec will be lost. Fortunately this gap is really
192           tiny for most programs; and modern programs use posix_spawn anyway.
193
194           %n is replaced with a file sequence number unique for this process.
195           This is useful for processes that produces several files from the
196           same filename template.
197
198           %q{FOO} is replaced with the contents of the environment variable
199           FOO. If the {FOO} part is malformed, it causes an abort. This
200           specifier is rarely needed, but very useful in certain
201           circumstances (eg. when running MPI programs). The idea is that you
202           specify a variable which will be set differently for each process
203           in the job, for example BPROC_RANK or whatever is applicable in
204           your MPI setup. If the named environment variable is not set, it
205           causes an abort. Note that in some shells, the { and } characters
206           may need to be escaped with a backslash.
207
208           %% is replaced with %.
209
210           If an % is followed by any other character, it causes an abort.
211
212           If the file name specifies a relative file name, it is put in the
213           program's initial working directory: this is the current directory
214           when the program started its execution after the fork or after the
215           exec. If it specifies an absolute file name (ie. starts with '/')
216           then it is put there.
217
218       --log-socket=<ip-address:port-number>
219           Specifies that Valgrind should send all of its messages to the
220           specified port at the specified IP address. The port may be
221           omitted, in which case port 1500 is used. If a connection cannot be
222           made to the specified socket, Valgrind falls back to writing output
223           to the standard error (stderr). This option is intended to be used
224           in conjunction with the valgrind-listener program. For further
225           details, see the commentary in the manual.
226
228       These options are used by all tools that can report errors, e.g.
229       Memcheck, but not Cachegrind.
230
231       --xml=<yes|no> [default: no]
232           When enabled, the important parts of the output (e.g. tool error
233           messages) will be in XML format rather than plain text.
234           Furthermore, the XML output will be sent to a different output
235           channel than the plain text output. Therefore, you also must use
236           one of --xml-fd, --xml-file or --xml-socket to specify where the
237           XML is to be sent.
238
239           Less important messages will still be printed in plain text, but
240           because the XML output and plain text output are sent to different
241           output channels (the destination of the plain text output is still
242           controlled by --log-fd, --log-file and --log-socket) this should
243           not cause problems.
244
245           This option is aimed at making life easier for tools that consume
246           Valgrind's output as input, such as GUI front ends. Currently this
247           option works with Memcheck, Helgrind and DRD. The output format is
248           specified in the file docs/internals/xml-output-protocol4.txt in
249           the source tree for Valgrind 3.5.0 or later.
250
251           The recommended options for a GUI to pass, when requesting XML
252           output, are: --xml=yes to enable XML output, --xml-file to send the
253           XML output to a (presumably GUI-selected) file, --log-file to send
254           the plain text output to a second GUI-selected file,
255           --child-silent-after-fork=yes, and -q to restrict the plain text
256           output to critical error messages created by Valgrind itself. For
257           example, failure to read a specified suppressions file counts as a
258           critical error message. In this way, for a successful run the text
259           output file will be empty. But if it isn't empty, then it will
260           contain important information which the GUI user should be made
261           aware of.
262
263       --xml-fd=<number> [default: -1, disabled]
264           Specifies that Valgrind should send its XML output to the specified
265           file descriptor. It must be used in conjunction with --xml=yes.
266
267       --xml-file=<filename>
268           Specifies that Valgrind should send its XML output to the specified
269           file. It must be used in conjunction with --xml=yes. Any %p or %q
270           sequences appearing in the filename are expanded in exactly the
271           same way as they are for --log-file. See the description of --log-
272           file for details.
273
274       --xml-socket=<ip-address:port-number>
275           Specifies that Valgrind should send its XML output the specified
276           port at the specified IP address. It must be used in conjunction
277           with --xml=yes. The form of the argument is the same as that used
278           by --log-socket. See the description of --log-socket for further
279           details.
280
281       --xml-user-comment=<string>
282           Embeds an extra user comment string at the start of the XML output.
283           Only works when --xml=yes is specified; ignored otherwise.
284
285       --demangle=<yes|no> [default: yes]
286           Enable/disable automatic demangling (decoding) of C++ names.
287           Enabled by default. When enabled, Valgrind will attempt to
288           translate encoded C++ names back to something approaching the
289           original. The demangler handles symbols mangled by g++ versions
290           2.X, 3.X and 4.X.
291
292           An important fact about demangling is that function names mentioned
293           in suppressions files should be in their mangled form. Valgrind
294           does not demangle function names when searching for applicable
295           suppressions, because to do otherwise would make suppression file
296           contents dependent on the state of Valgrind's demangling machinery,
297           and also slow down suppression matching.
298
299       --num-callers=<number> [default: 12]
300           Specifies the maximum number of entries shown in stack traces that
301           identify program locations. Note that errors are commoned up using
302           only the top four function locations (the place in the current
303           function, and that of its three immediate callers). So this doesn't
304           affect the total number of errors reported.
305
306           The maximum value for this is 500. Note that higher settings will
307           make Valgrind run a bit more slowly and take a bit more memory, but
308           can be useful when working with programs with deeply-nested call
309           chains.
310
311       --unw-stack-scan-thresh=<number> [default: 0] ,
312       --unw-stack-scan-frames=<number> [default: 5]
313           Stack-scanning support is available only on ARM targets.
314
315           These flags enable and control stack unwinding by stack scanning.
316           When the normal stack unwinding mechanisms -- usage of Dwarf CFI
317           records, and frame-pointer following -- fail, stack scanning may be
318           able to recover a stack trace.
319
320           Note that stack scanning is an imprecise, heuristic mechanism that
321           may give very misleading results, or none at all. It should be used
322           only in emergencies, when normal unwinding fails, and it is
323           important to nevertheless have stack traces.
324
325           Stack scanning is a simple technique: the unwinder reads words from
326           the stack, and tries to guess which of them might be return
327           addresses, by checking to see if they point just after ARM or Thumb
328           call instructions. If so, the word is added to the backtrace.
329
330           The main danger occurs when a function call returns, leaving its
331           return address exposed, and a new function is called, but the new
332           function does not overwrite the old address. The result of this is
333           that the backtrace may contain entries for functions which have
334           already returned, and so be very confusing.
335
336           A second limitation of this implementation is that it will scan
337           only the page (4KB, normally) containing the starting stack
338           pointer. If the stack frames are large, this may result in only a
339           few (or not even any) being present in the trace. Also, if you are
340           unlucky and have an initial stack pointer near the end of its
341           containing page, the scan may miss all interesting frames.
342
343           By default stack scanning is disabled. The normal use case is to
344           ask for it when a stack trace would otherwise be very short. So, to
345           enable it, use --unw-stack-scan-thresh=number. This requests
346           Valgrind to try using stack scanning to "extend" stack traces which
347           contain fewer than number frames.
348
349           If stack scanning does take place, it will only generate at most
350           the number of frames specified by --unw-stack-scan-frames.
351           Typically, stack scanning generates so many garbage entries that
352           this value is set to a low value (5) by default. In no case will a
353           stack trace larger than the value specified by --num-callers be
354           created.
355
356       --error-limit=<yes|no> [default: yes]
357           When enabled, Valgrind stops reporting errors after 10,000,000 in
358           total, or 1,000 different ones, have been seen. This is to stop the
359           error tracking machinery from becoming a huge performance overhead
360           in programs with many errors.
361
362       --error-exitcode=<number> [default: 0]
363           Specifies an alternative exit code to return if Valgrind reported
364           any errors in the run. When set to the default value (zero), the
365           return value from Valgrind will always be the return value of the
366           process being simulated. When set to a nonzero value, that value is
367           returned instead, if Valgrind detects any errors. This is useful
368           for using Valgrind as part of an automated test suite, since it
369           makes it easy to detect test cases for which Valgrind has reported
370           errors, just by inspecting return codes.
371
372       --exit-on-first-error=<yes|no> [default: no]
373           If this option is enabled, Valgrind exits on the first error. A
374           nonzero exit value must be defined using --error-exitcode option.
375           Useful if you are running regression tests or have some other
376           automated test machinery.
377
378       --error-markers=<begin>,<end> [default: none]
379           When errors are output as plain text (i.e. XML not used),
380           --error-markers instructs to output a line containing the begin
381           (end) string before (after) each error.
382
383           Such marker lines facilitate searching for errors and/or extracting
384           errors in an output file that contain valgrind errors mixed with
385           the program output.
386
387           Note that empty markers are accepted. So, only using a begin (or an
388           end) marker is possible.
389
390       --show-error-list=no|yes [default: no]
391           If this option is enabled, for tools that report errors, valgrind
392           will show the list of detected errors and the list of used
393           suppressions at exit.
394
395           Note that at verbosity 2 and above, valgrind automatically shows
396           the list of detected errors and the list of used suppressions at
397           exit, unless --show-error-list=no is selected.
398
399       -s
400           Specifying -s is equivalent to --show-error-list=yes.
401
402       --sigill-diagnostics=<yes|no> [default: yes]
403           Enable/disable printing of illegal instruction diagnostics. Enabled
404           by default, but defaults to disabled when --quiet is given. The
405           default can always be explicitly overridden by giving this option.
406
407           When enabled, a warning message will be printed, along with some
408           diagnostics, whenever an instruction is encountered that Valgrind
409           cannot decode or translate, before the program is given a SIGILL
410           signal. Often an illegal instruction indicates a bug in the program
411           or missing support for the particular instruction in Valgrind. But
412           some programs do deliberately try to execute an instruction that
413           might be missing and trap the SIGILL signal to detect processor
414           features. Using this flag makes it possible to avoid the diagnostic
415           output that you would otherwise get in such cases.
416
417       --keep-debuginfo=<yes|no> [default: no]
418           When enabled, keep ("archive") symbols and all other debuginfo for
419           unloaded code. This allows saved stack traces to include file/line
420           info for code that has been dlclose'd (or similar). Be careful with
421           this, since it can lead to unbounded memory use for programs which
422           repeatedly load and unload shared objects.
423
424           Some tools and some functionalities have only limited support for
425           archived debug info. Memcheck fully supports it. Generally, tools
426           that report errors can use archived debug info to show the error
427           stack traces. The known limitations are: Helgrind's past access
428           stack trace of a race condition is does not use archived debug
429           info. Massif (and more generally the xtree Massif output format)
430           does not make use of archived debug info. Only Memcheck has been
431           (somewhat) tested with --keep-debuginfo=yes, so other tools may
432           have unknown limitations.
433
434       --show-below-main=<yes|no> [default: no]
435           By default, stack traces for errors do not show any functions that
436           appear beneath main because most of the time it's uninteresting C
437           library stuff and/or gobbledygook. Alternatively, if main is not
438           present in the stack trace, stack traces will not show any
439           functions below main-like functions such as glibc's
440           __libc_start_main. Furthermore, if main-like functions are present
441           in the trace, they are normalised as (below main), in order to make
442           the output more deterministic.
443
444           If this option is enabled, all stack trace entries will be shown
445           and main-like functions will not be normalised.
446
447       --fullpath-after=<string> [default: don't show source paths]
448           By default Valgrind only shows the filenames in stack traces, but
449           not full paths to source files. When using Valgrind in large
450           projects where the sources reside in multiple different
451           directories, this can be inconvenient.  --fullpath-after provides a
452           flexible solution to this problem. When this option is present, the
453           path to each source file is shown, with the following all-important
454           caveat: if string is found in the path, then the path up to and
455           including string is omitted, else the path is shown unmodified.
456           Note that string is not required to be a prefix of the path.
457
458           For example, consider a file named
459           /home/janedoe/blah/src/foo/bar/xyzzy.c. Specifying
460           --fullpath-after=/home/janedoe/blah/src/ will cause Valgrind to
461           show the name as foo/bar/xyzzy.c.
462
463           Because the string is not required to be a prefix,
464           --fullpath-after=src/ will produce the same output. This is useful
465           when the path contains arbitrary machine-generated characters. For
466           example, the path /my/build/dir/C32A1B47/blah/src/foo/xyzzy can be
467           pruned to foo/xyzzy using --fullpath-after=/blah/src/.
468
469           If you simply want to see the full path, just specify an empty
470           string: --fullpath-after=. This isn't a special case, merely a
471           logical consequence of the above rules.
472
473           Finally, you can use --fullpath-after multiple times. Any
474           appearance of it causes Valgrind to switch to producing full paths
475           and applying the above filtering rule. Each produced path is
476           compared against all the --fullpath-after-specified strings, in the
477           order specified. The first string to match causes the path to be
478           truncated as described above. If none match, the full path is
479           shown. This facilitates chopping off prefixes when the sources are
480           drawn from a number of unrelated directories.
481
482       --extra-debuginfo-path=<path> [default: undefined and unused]
483           By default Valgrind searches in several well-known paths for debug
484           objects, such as /usr/lib/debug/.
485
486           However, there may be scenarios where you may wish to put debug
487           objects at an arbitrary location, such as external storage when
488           running Valgrind on a mobile device with limited local storage.
489           Another example might be a situation where you do not have
490           permission to install debug object packages on the system where you
491           are running Valgrind.
492
493           In these scenarios, you may provide an absolute path as an extra,
494           final place for Valgrind to search for debug objects by specifying
495           --extra-debuginfo-path=/path/to/debug/objects. The given path will
496           be prepended to the absolute path name of the searched-for object.
497           For example, if Valgrind is looking for the debuginfo for
498           /w/x/y/zz.so and --extra-debuginfo-path=/a/b/c is specified, it
499           will look for a debug object at /a/b/c/w/x/y/zz.so.
500
501           This flag should only be specified once. If it is specified
502           multiple times, only the last instance is honoured.
503
504       --debuginfo-server=ipaddr:port [default: undefined and unused]
505           This is a new, experimental, feature introduced in version 3.9.0.
506
507           In some scenarios it may be convenient to read debuginfo from
508           objects stored on a different machine. With this flag, Valgrind
509           will query a debuginfo server running on ipaddr and listening on
510           port port, if it cannot find the debuginfo object in the local
511           filesystem.
512
513           The debuginfo server must accept TCP connections on port port. The
514           debuginfo server is contained in the source file
515           auxprogs/valgrind-di-server.c. It will only serve from the
516           directory it is started in.  port defaults to 1500 in both client
517           and server if not specified.
518
519           If Valgrind looks for the debuginfo for /w/x/y/zz.so by using the
520           debuginfo server, it will strip the pathname components and merely
521           request zz.so on the server. That in turn will look only in its
522           current working directory for a matching debuginfo object.
523
524           The debuginfo data is transmitted in small fragments (8 KB) as
525           requested by Valgrind. Each block is compressed using LZO to reduce
526           transmission time. The implementation has been tuned for best
527           performance over a single-stage 802.11g (WiFi) network link.
528
529           Note that checks for matching primary vs debug objects, using GNU
530           debuglink CRC scheme, are performed even when using the debuginfo
531           server. To disable such checking, you need to also specify
532           --allow-mismatched-debuginfo=yes.
533
534           By default the Valgrind build system will build valgrind-di-server
535           for the target platform, which is almost certainly not what you
536           want. So far we have been unable to find out how to get
537           automake/autoconf to build it for the build platform. If you want
538           to use it, you will have to recompile it by hand using the command
539           shown at the top of auxprogs/valgrind-di-server.c.
540
541           Valgrind can also download debuginfo via debuginfod. See the
542           DEBUGINFOD section for more information.
543
544       --allow-mismatched-debuginfo=no|yes [no]
545           When reading debuginfo from separate debuginfo objects, Valgrind
546           will by default check that the main and debuginfo objects match,
547           using the GNU debuglink mechanism. This guarantees that it does not
548           read debuginfo from out of date debuginfo objects, and also ensures
549           that Valgrind can't crash as a result of mismatches.
550
551           This check can be overridden using
552           --allow-mismatched-debuginfo=yes. This may be useful when the
553           debuginfo and main objects have not been split in the proper way.
554           Be careful when using this, though: it disables all consistency
555           checking, and Valgrind has been observed to crash when the main and
556           debuginfo objects don't match.
557
558       --suppressions=<filename> [default: $PREFIX/lib/valgrind/default.supp]
559           Specifies an extra file from which to read descriptions of errors
560           to suppress. You may use up to 100 extra suppression files.
561
562       --gen-suppressions=<yes|no|all> [default: no]
563           When set to yes, Valgrind will pause after every error shown and
564           print the line:
565
566                   ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ----
567
568           Pressing Ret, or N Ret or n Ret, causes Valgrind continue execution
569           without printing a suppression for this error.
570
571           Pressing Y Ret or y Ret causes Valgrind to write a suppression for
572           this error. You can then cut and paste it into a suppression file
573           if you don't want to hear about the error in the future.
574
575           When set to all, Valgrind will print a suppression for every
576           reported error, without querying the user.
577
578           This option is particularly useful with C++ programs, as it prints
579           out the suppressions with mangled names, as required.
580
581           Note that the suppressions printed are as specific as possible. You
582           may want to common up similar ones, by adding wildcards to function
583           names, and by using frame-level wildcards. The wildcarding
584           facilities are powerful yet flexible, and with a bit of careful
585           editing, you may be able to suppress a whole family of related
586           errors with only a few suppressions.
587
588           Sometimes two different errors are suppressed by the same
589           suppression, in which case Valgrind will output the suppression
590           more than once, but you only need to have one copy in your
591           suppression file (but having more than one won't cause problems).
592           Also, the suppression name is given as <insert a suppression name
593           here>; the name doesn't really matter, it's only used with the -v
594           option which prints out all used suppression records.
595
596       --input-fd=<number> [default: 0, stdin]
597           When using --gen-suppressions=yes, Valgrind will stop so as to read
598           keyboard input from you when each error occurs. By default it reads
599           from the standard input (stdin), which is problematic for programs
600           which close stdin. This option allows you to specify an alternative
601           file descriptor from which to read input.
602
603       --dsymutil=no|yes [yes]
604           This option is only relevant when running Valgrind on Mac OS X.
605
606           Mac OS X uses a deferred debug information (debuginfo) linking
607           scheme. When object files containing debuginfo are linked into a
608           .dylib or an executable, the debuginfo is not copied into the final
609           file. Instead, the debuginfo must be linked manually by running
610           dsymutil, a system-provided utility, on the executable or .dylib.
611           The resulting combined debuginfo is placed in a directory alongside
612           the executable or .dylib, but with the extension .dSYM.
613
614           With --dsymutil=no, Valgrind will detect cases where the .dSYM
615           directory is either missing, or is present but does not appear to
616           match the associated executable or .dylib, most likely because it
617           is out of date. In these cases, Valgrind will print a warning
618           message but take no further action.
619
620           With --dsymutil=yes, Valgrind will, in such cases, automatically
621           run dsymutil as necessary to bring the debuginfo up to date. For
622           all practical purposes, if you always use --dsymutil=yes, then
623           there is never any need to run dsymutil manually or as part of your
624           applications's build system, since Valgrind will run it as
625           necessary.
626
627           Valgrind will not attempt to run dsymutil on any executable or
628           library in /usr/, /bin/, /sbin/, /opt/, /sw/, /System/, /Library/
629           or /Applications/ since dsymutil will always fail in such
630           situations. It fails both because the debuginfo for such
631           pre-installed system components is not available anywhere, and also
632           because it would require write privileges in those directories.
633
634           Be careful when using --dsymutil=yes, since it will cause
635           pre-existing .dSYM directories to be silently deleted and
636           re-created. Also note that dsymutil is quite slow, sometimes
637           excessively so.
638
639       --max-stackframe=<number> [default: 2000000]
640           The maximum size of a stack frame. If the stack pointer moves by
641           more than this amount then Valgrind will assume that the program is
642           switching to a different stack.
643
644           You may need to use this option if your program has large
645           stack-allocated arrays. Valgrind keeps track of your program's
646           stack pointer. If it changes by more than the threshold amount,
647           Valgrind assumes your program is switching to a different stack,
648           and Memcheck behaves differently than it would for a stack pointer
649           change smaller than the threshold. Usually this heuristic works
650           well. However, if your program allocates large structures on the
651           stack, this heuristic will be fooled, and Memcheck will
652           subsequently report large numbers of invalid stack accesses. This
653           option allows you to change the threshold to a different value.
654
655           You should only consider use of this option if Valgrind's debug
656           output directs you to do so. In that case it will tell you the new
657           threshold you should specify.
658
659           In general, allocating large structures on the stack is a bad idea,
660           because you can easily run out of stack space, especially on
661           systems with limited memory or which expect to support large
662           numbers of threads each with a small stack, and also because the
663           error checking performed by Memcheck is more effective for
664           heap-allocated data than for stack-allocated data. If you have to
665           use this option, you may wish to consider rewriting your code to
666           allocate on the heap rather than on the stack.
667
668       --main-stacksize=<number> [default: use current 'ulimit' value]
669           Specifies the size of the main thread's stack.
670
671           To simplify its memory management, Valgrind reserves all required
672           space for the main thread's stack at startup. That means it needs
673           to know the required stack size at startup.
674
675           By default, Valgrind uses the current "ulimit" value for the stack
676           size, or 16 MB, whichever is lower. In many cases this gives a
677           stack size in the range 8 to 16 MB, which almost never overflows
678           for most applications.
679
680           If you need a larger total stack size, use --main-stacksize to
681           specify it. Only set it as high as you need, since reserving far
682           more space than you need (that is, hundreds of megabytes more than
683           you need) constrains Valgrind's memory allocators and may reduce
684           the total amount of memory that Valgrind can use. This is only
685           really of significance on 32-bit machines.
686
687           On Linux, you may request a stack of size up to 2GB. Valgrind will
688           stop with a diagnostic message if the stack cannot be allocated.
689
690           --main-stacksize only affects the stack size for the program's
691           initial thread. It has no bearing on the size of thread stacks, as
692           Valgrind does not allocate those.
693
694           You may need to use both --main-stacksize and --max-stackframe
695           together. It is important to understand that --main-stacksize sets
696           the maximum total stack size, whilst --max-stackframe specifies the
697           largest size of any one stack frame. You will have to work out the
698           --main-stacksize value for yourself (usually, if your applications
699           segfaults). But Valgrind will tell you the needed --max-stackframe
700           size, if necessary.
701
702           As discussed further in the description of --max-stackframe, a
703           requirement for a large stack is a sign of potential portability
704           problems. You are best advised to place all large data in
705           heap-allocated memory.
706
707       --max-threads=<number> [default: 500]
708           By default, Valgrind can handle to up to 500 threads. Occasionally,
709           that number is too small. Use this option to provide a different
710           limit. E.g.  --max-threads=3000.
711
713       For tools that use their own version of malloc (e.g. Memcheck, Massif,
714       Helgrind, DRD), the following options apply.
715
716       --alignment=<number> [default: 8 or 16, depending on the platform]
717           By default Valgrind's malloc, realloc, etc, return a block whose
718           starting address is 8-byte aligned or 16-byte aligned (the value
719           depends on the platform and matches the platform default). This
720           option allows you to specify a different alignment. The supplied
721           value must be greater than or equal to the default, less than or
722           equal to 4096, and must be a power of two.
723
724       --redzone-size=<number> [default: depends on the tool]
725           Valgrind's malloc, realloc, etc, add padding blocks before and
726           after each heap block allocated by the program being run. Such
727           padding blocks are called redzones. The default value for the
728           redzone size depends on the tool. For example, Memcheck adds and
729           protects a minimum of 16 bytes before and after each block
730           allocated by the client. This allows it to detect block underruns
731           or overruns of up to 16 bytes.
732
733           Increasing the redzone size makes it possible to detect overruns of
734           larger distances, but increases the amount of memory used by
735           Valgrind. Decreasing the redzone size will reduce the memory needed
736           by Valgrind but also reduces the chances of detecting
737           over/underruns, so is not recommended.
738
739       --xtree-memory=none|allocs|full [none]
740           Tools replacing Valgrind's malloc, realloc, etc, can optionally
741           produce an execution tree detailing which piece of code is
742           responsible for heap memory usage. See Execution Trees for a
743           detailed explanation about execution trees.
744
745           When set to none, no memory execution tree is produced.
746
747           When set to allocs, the memory execution tree gives the current
748           number of allocated bytes and the current number of allocated
749           blocks.
750
751           When set to full, the memory execution tree gives 6 different
752           measurements : the current number of allocated bytes and blocks
753           (same values as for allocs), the total number of allocated bytes
754           and blocks, the total number of freed bytes and blocks.
755
756           Note that the overhead in cpu and memory to produce an xtree
757           depends on the tool. The overhead in cpu is small for the value
758           allocs, as the information needed to produce this report is
759           maintained in any case by the tool. For massif and helgrind,
760           specifying full implies to capture a stack trace for each free
761           operation, while normally these tools only capture an allocation
762           stack trace. For Memcheck, the cpu overhead for the value full is
763           small, as this can only be used in combination with
764           --keep-stacktraces=alloc-and-free or
765           --keep-stacktraces=alloc-then-free, which already records a stack
766           trace for each free operation. The memory overhead varies between 5
767           and 10 words per unique stacktrace in the xtree, plus the memory
768           needed to record the stack trace for the free operations, if needed
769           specifically for the xtree.
770
771       --xtree-memory-file=<filename> [default: xtmemory.kcg.%p]
772           Specifies that Valgrind should produce the xtree memory report in
773           the specified file. Any %p or %q sequences appearing in the
774           filename are expanded in exactly the same way as they are for
775           --log-file. See the description of --log-file for details.
776
777           If the filename contains the extension .ms, then the produced file
778           format will be a massif output file format. If the filename
779           contains the extension .kcg or no extension is provided or
780           recognised, then the produced file format will be a callgrind
781           output format.
782
783           See Execution Trees for a detailed explanation about execution
784           trees formats.
785

UNCOMMON OPTIONS

787       These options apply to all tools, as they affect certain obscure
788       workings of the Valgrind core. Most people won't need to use them.
789
790       --smc-check=<none|stack|all|all-non-file> [default: all-non-file for
791       x86/amd64/s390x, stack for other archs]
792           This option controls Valgrind's detection of self-modifying code.
793           If no checking is done, when a program executes some code, then
794           overwrites it with new code, and executes the new code, Valgrind
795           will continue to execute the translations it made for the old code.
796           This will likely lead to incorrect behaviour and/or crashes.
797
798           For "modern" architectures -- anything that's not x86, amd64 or
799           s390x -- the default is stack. This is because a correct program
800           must take explicit action to reestablish D-I cache coherence
801           following code modification. Valgrind observes and honours such
802           actions, with the result that self-modifying code is transparently
803           handled with zero extra cost.
804
805           For x86, amd64 and s390x, the program is not required to notify the
806           hardware of required D-I coherence syncing. Hence the default is
807           all-non-file, which covers the normal case of generating code into
808           an anonymous (non-file-backed) mmap'd area.
809
810           The meanings of the four available settings are as follows. No
811           detection (none), detect self-modifying code on the stack (which is
812           used by GCC to implement nested functions) (stack), detect
813           self-modifying code everywhere (all), and detect self-modifying
814           code everywhere except in file-backed mappings (all-non-file).
815
816           Running with all will slow Valgrind down noticeably. Running with
817           none will rarely speed things up, since very little code gets
818           dynamically generated in most programs. The
819           VALGRIND_DISCARD_TRANSLATIONS client request is an alternative to
820           --smc-check=all and --smc-check=all-non-file that requires more
821           programmer effort but allows Valgrind to run your program faster,
822           by telling it precisely when translations need to be re-made.
823
824           --smc-check=all-non-file provides a cheaper but more limited
825           version of --smc-check=all. It adds checks to any translations that
826           do not originate from file-backed memory mappings. Typical
827           applications that generate code, for example JITs in web browsers,
828           generate code into anonymous mmaped areas, whereas the "fixed" code
829           of the browser always lives in file-backed mappings.
830           --smc-check=all-non-file takes advantage of this observation,
831           limiting the overhead of checking to code which is likely to be JIT
832           generated.
833
834       --read-inline-info=<yes|no> [default: see below]
835           When enabled, Valgrind will read information about inlined function
836           calls from DWARF3 debug info. This slows Valgrind startup and makes
837           it use more memory (typically for each inlined piece of code, 6
838           words and space for the function name), but it results in more
839           descriptive stacktraces. Currently, this functionality is enabled
840           by default only for Linux, Android and Solaris targets and only for
841           the tools Memcheck, Massif, Helgrind and DRD. Here is an example of
842           some stacktraces with --read-inline-info=no:
843
844               ==15380== Conditional jump or move depends on uninitialised value(s)
845               ==15380==    at 0x80484EA: main (inlinfo.c:6)
846               ==15380==
847               ==15380== Conditional jump or move depends on uninitialised value(s)
848               ==15380==    at 0x8048550: fun_noninline (inlinfo.c:6)
849               ==15380==    by 0x804850E: main (inlinfo.c:34)
850               ==15380==
851               ==15380== Conditional jump or move depends on uninitialised value(s)
852               ==15380==    at 0x8048520: main (inlinfo.c:6)
853
854           And here are the same errors with --read-inline-info=yes:
855
856               ==15377== Conditional jump or move depends on uninitialised value(s)
857               ==15377==    at 0x80484EA: fun_d (inlinfo.c:6)
858               ==15377==    by 0x80484EA: fun_c (inlinfo.c:14)
859               ==15377==    by 0x80484EA: fun_b (inlinfo.c:20)
860               ==15377==    by 0x80484EA: fun_a (inlinfo.c:26)
861               ==15377==    by 0x80484EA: main (inlinfo.c:33)
862               ==15377==
863               ==15377== Conditional jump or move depends on uninitialised value(s)
864               ==15377==    at 0x8048550: fun_d (inlinfo.c:6)
865               ==15377==    by 0x8048550: fun_noninline (inlinfo.c:41)
866               ==15377==    by 0x804850E: main (inlinfo.c:34)
867               ==15377==
868               ==15377== Conditional jump or move depends on uninitialised value(s)
869               ==15377==    at 0x8048520: fun_d (inlinfo.c:6)
870               ==15377==    by 0x8048520: main (inlinfo.c:35)
871
872       --read-var-info=<yes|no> [default: no]
873           When enabled, Valgrind will read information about variable types
874           and locations from DWARF3 debug info. This slows Valgrind startup
875           significantly and makes it use significantly more memory, but for
876           the tools that can take advantage of it (Memcheck, Helgrind, DRD)
877           it can result in more precise error messages. For example, here are
878           some standard errors issued by Memcheck:
879
880               ==15363== Uninitialised byte(s) found during client check request
881               ==15363==    at 0x80484A9: croak (varinfo1.c:28)
882               ==15363==    by 0x8048544: main (varinfo1.c:55)
883               ==15363==  Address 0x80497f7 is 7 bytes inside data symbol "global_i2"
884               ==15363==
885               ==15363== Uninitialised byte(s) found during client check request
886               ==15363==    at 0x80484A9: croak (varinfo1.c:28)
887               ==15363==    by 0x8048550: main (varinfo1.c:56)
888               ==15363==  Address 0xbea0d0cc is on thread 1's stack
889               ==15363==  in frame #1, created by main (varinfo1.c:45)
890
891           And here are the same errors with --read-var-info=yes:
892
893               ==15370== Uninitialised byte(s) found during client check request
894               ==15370==    at 0x80484A9: croak (varinfo1.c:28)
895               ==15370==    by 0x8048544: main (varinfo1.c:55)
896               ==15370==  Location 0x80497f7 is 0 bytes inside global_i2[7],
897               ==15370==  a global variable declared at varinfo1.c:41
898               ==15370==
899               ==15370== Uninitialised byte(s) found during client check request
900               ==15370==    at 0x80484A9: croak (varinfo1.c:28)
901               ==15370==    by 0x8048550: main (varinfo1.c:56)
902               ==15370==  Location 0xbeb4a0cc is 0 bytes inside local var "local"
903               ==15370==  declared at varinfo1.c:46, in frame #1 of thread 1
904
905       --vgdb-poll=<number> [default: 5000]
906           As part of its main loop, the Valgrind scheduler will poll to check
907           if some activity (such as an external command or some input from a
908           gdb) has to be handled by gdbserver. This activity poll will be
909           done after having run the given number of basic blocks (or slightly
910           more than the given number of basic blocks). This poll is quite
911           cheap so the default value is set relatively low. You might further
912           decrease this value if vgdb cannot use ptrace system call to
913           interrupt Valgrind if all threads are (most of the time) blocked in
914           a system call.
915
916       --vgdb-shadow-registers=no|yes [default: no]
917           When activated, gdbserver will expose the Valgrind shadow registers
918           to GDB. With this, the value of the Valgrind shadow registers can
919           be examined or changed using GDB. Exposing shadow registers only
920           works with GDB version 7.1 or later.
921
922       --vgdb-prefix=<prefix> [default: /tmp/vgdb-pipe]
923           To communicate with gdb/vgdb, the Valgrind gdbserver creates 3
924           files (2 named FIFOs and a mmap shared memory file). The prefix
925           option controls the directory and prefix for the creation of these
926           files.
927
928       --run-libc-freeres=<yes|no> [default: yes]
929           This option is only relevant when running Valgrind on Linux.
930
931           The GNU C library (libc.so), which is used by all programs, may
932           allocate memory for its own uses. Usually it doesn't bother to free
933           that memory when the program ends—there would be no point, since
934           the Linux kernel reclaims all process resources when a process
935           exits anyway, so it would just slow things down.
936
937           The glibc authors realised that this behaviour causes leak
938           checkers, such as Valgrind, to falsely report leaks in glibc, when
939           a leak check is done at exit. In order to avoid this, they provided
940           a routine called __libc_freeres specifically to make glibc release
941           all memory it has allocated. Memcheck therefore tries to run
942           __libc_freeres at exit.
943
944           Unfortunately, in some very old versions of glibc, __libc_freeres
945           is sufficiently buggy to cause segmentation faults. This was
946           particularly noticeable on Red Hat 7.1. So this option is provided
947           in order to inhibit the run of __libc_freeres. If your program
948           seems to run fine on Valgrind, but segfaults at exit, you may find
949           that --run-libc-freeres=no fixes that, although at the cost of
950           possibly falsely reporting space leaks in libc.so.
951
952       --run-cxx-freeres=<yes|no> [default: yes]
953           This option is only relevant when running Valgrind on Linux or
954           Solaris C++ programs.
955
956           The GNU Standard C++ library (libstdc++.so), which is used by all
957           C++ programs compiled with g++, may allocate memory for its own
958           uses. Usually it doesn't bother to free that memory when the
959           program ends—there would be no point, since the kernel reclaims all
960           process resources when a process exits anyway, so it would just
961           slow things down.
962
963           The gcc authors realised that this behaviour causes leak checkers,
964           such as Valgrind, to falsely report leaks in libstdc++, when a leak
965           check is done at exit. In order to avoid this, they provided a
966           routine called __gnu_cxx::__freeres specifically to make libstdc++
967           release all memory it has allocated. Memcheck therefore tries to
968           run __gnu_cxx::__freeres at exit.
969
970           For the sake of flexibility and unforeseen problems with
971           __gnu_cxx::__freeres, option --run-cxx-freeres=no exists, although
972           at the cost of possibly falsely reporting space leaks in
973           libstdc++.so.
974
975       --sim-hints=hint1,hint2,...
976           Pass miscellaneous hints to Valgrind which slightly modify the
977           simulated behaviour in nonstandard or dangerous ways, possibly to
978           help the simulation of strange features. By default no hints are
979           enabled. Use with caution! Currently known hints are:
980
981lax-ioctls: Be very lax about ioctl handling; the only
982               assumption is that the size is correct. Doesn't require the
983               full buffer to be initialised when writing. Without this, using
984               some device drivers with a large number of strange ioctl
985               commands becomes very tiresome.
986
987fuse-compatible: Enable special handling for certain system
988               calls that may block in a FUSE file-system. This may be
989               necessary when running Valgrind on a multi-threaded program
990               that uses one thread to manage a FUSE file-system and another
991               thread to access that file-system.
992
993enable-outer: Enable some special magic needed when the program
994               being run is itself Valgrind.
995
996no-inner-prefix: Disable printing a prefix > in front of each
997               stdout or stderr output line in an inner Valgrind being run by
998               an outer Valgrind. This is useful when running Valgrind
999               regression tests in an outer/inner setup. Note that the prefix
1000               > will always be printed in front of the inner debug logging
1001               lines.
1002
1003no-nptl-pthread-stackcache: This hint is only relevant when
1004               running Valgrind on Linux; it is ignored on Solaris and Mac OS
1005               X.
1006
1007               The GNU glibc pthread library (libpthread.so), which is used by
1008               pthread programs, maintains a cache of pthread stacks. When a
1009               pthread terminates, the memory used for the pthread stack and
1010               some thread local storage related data structure are not always
1011               directly released. This memory is kept in a cache (up to a
1012               certain size), and is re-used if a new thread is started.
1013
1014               This cache causes the helgrind tool to report some false
1015               positive race condition errors on this cached memory, as
1016               helgrind does not understand the internal glibc cache
1017               synchronisation primitives. So, when using helgrind, disabling
1018               the cache helps to avoid false positive race conditions, in
1019               particular when using thread local storage variables (e.g.
1020               variables using the __thread qualifier).
1021
1022               When using the memcheck tool, disabling the cache ensures the
1023               memory used by glibc to handle __thread variables is directly
1024               released when a thread terminates.
1025
1026               Note: Valgrind disables the cache using some internal knowledge
1027               of the glibc stack cache implementation and by examining the
1028               debug information of the pthread library. This technique is
1029               thus somewhat fragile and might not work for all glibc
1030               versions. This has been successfully tested with various glibc
1031               versions (e.g. 2.11, 2.16, 2.18) on various platforms.
1032
1033lax-doors: (Solaris only) Be very lax about door syscall
1034               handling over unrecognised door file descriptors. Does not
1035               require that full buffer is initialised when writing. Without
1036               this, programs using libdoor(3LIB) functionality with
1037               completely proprietary semantics may report large number of
1038               false positives.
1039
1040fallback-llsc: (MIPS and ARM64 only): Enables an alternative
1041               implementation of Load-Linked (LL) and Store-Conditional (SC)
1042               instructions. The standard implementation gives more correct
1043               behaviour, but can cause indefinite looping on certain
1044               processor implementations that are intolerant of extra memory
1045               references between LL and SC. So far this is known only to
1046               happen on Cavium 3 cores. You should not need to use this flag,
1047               since the relevant cores are detected at startup and the
1048               alternative implementation is automatically enabled if
1049               necessary. There is no equivalent anti-flag: you cannot
1050               force-disable the alternative implementation, if it is
1051               automatically enabled. The underlying problem exists because
1052               the "standard" implementation of LL and SC is done by copying
1053               through LL and SC instructions into the instrumented code.
1054               However, tools may insert extra instrumentation memory
1055               references in between the LL and SC instructions. These memory
1056               references are not present in the original uninstrumented code,
1057               and their presence in the instrumented code can cause the SC
1058               instructions to persistently fail, leading to indefinite
1059               looping in LL-SC blocks. The alternative implementation gives
1060               correct behaviour of LL and SC instructions between threads in
1061               a process, up to and including the ABA scenario. It also gives
1062               correct behaviour between a Valgrinded thread and a
1063               non-Valgrinded thread running in a different process, that
1064               communicate via shared memory, but only up to and including
1065               correct CAS behaviour -- in this case the ABA scenario may not
1066               be correctly handled.
1067
1068       --fair-sched=<no|yes|try> [default: no]
1069           The --fair-sched option controls the locking mechanism used by
1070           Valgrind to serialise thread execution. The locking mechanism
1071           controls the way the threads are scheduled, and different settings
1072           give different trade-offs between fairness and performance. For
1073           more details about the Valgrind thread serialisation scheme and its
1074           impact on performance and thread scheduling, see Scheduling and
1075           Multi-Thread Performance.
1076
1077           •   The value --fair-sched=yes activates a fair scheduler. In
1078               short, if multiple threads are ready to run, the threads will
1079               be scheduled in a round robin fashion. This mechanism is not
1080               available on all platforms or Linux versions. If not available,
1081               using --fair-sched=yes will cause Valgrind to terminate with an
1082               error.
1083
1084               You may find this setting improves overall responsiveness if
1085               you are running an interactive multithreaded program, for
1086               example a web browser, on Valgrind.
1087
1088           •   The value --fair-sched=try activates fair scheduling if
1089               available on the platform. Otherwise, it will automatically
1090               fall back to --fair-sched=no.
1091
1092           •   The value --fair-sched=no activates a scheduler which does not
1093               guarantee fairness between threads ready to run, but which in
1094               general gives the highest performance.
1095
1096       --kernel-variant=variant1,variant2,...
1097           Handle system calls and ioctls arising from minor variants of the
1098           default kernel for this platform. This is useful for running on
1099           hacked kernels or with kernel modules which support nonstandard
1100           ioctls, for example. Use with caution. If you don't understand what
1101           this option does then you almost certainly don't need it. Currently
1102           known variants are:
1103
1104bproc: support the sys_broc system call on x86. This is for
1105               running on BProc, which is a minor variant of standard Linux
1106               which is sometimes used for building clusters.
1107
1108android-no-hw-tls: some versions of the Android emulator for
1109               ARM do not provide a hardware TLS (thread-local state)
1110               register, and Valgrind crashes at startup. Use this variant to
1111               select software support for TLS.
1112
1113android-gpu-sgx5xx: use this to support handling of proprietary
1114               ioctls for the PowerVR SGX 5XX series of GPUs on Android
1115               devices. Failure to select this does not cause stability
1116               problems, but may cause Memcheck to report false errors after
1117               the program performs GPU-specific ioctls.
1118
1119android-gpu-adreno3xx: similarly, use this to support handling
1120               of proprietary ioctls for the Qualcomm Adreno 3XX series of
1121               GPUs on Android devices.
1122
1123       --merge-recursive-frames=<number> [default: 0]
1124           Some recursive algorithms, for example balanced binary tree
1125           implementations, create many different stack traces, each
1126           containing cycles of calls. A cycle is defined as two identical
1127           program counter values separated by zero or more other program
1128           counter values. Valgrind may then use a lot of memory to store all
1129           these stack traces. This is a poor use of memory considering that
1130           such stack traces contain repeated uninteresting recursive calls
1131           instead of more interesting information such as the function that
1132           has initiated the recursive call.
1133
1134           The option --merge-recursive-frames=<number> instructs Valgrind to
1135           detect and merge recursive call cycles having a size of up to
1136           <number> frames. When such a cycle is detected, Valgrind records
1137           the cycle in the stack trace as a unique program counter.
1138
1139           The value 0 (the default) causes no recursive call merging. A value
1140           of 1 will cause stack traces of simple recursive algorithms (for
1141           example, a factorial implementation) to be collapsed. A value of 2
1142           will usually be needed to collapse stack traces produced by
1143           recursive algorithms such as binary trees, quick sort, etc. Higher
1144           values might be needed for more complex recursive algorithms.
1145
1146           Note: recursive calls are detected by analysis of program counter
1147           values. They are not detected by looking at function names.
1148
1149       --num-transtab-sectors=<number> [default: 6 for Android platforms, 16
1150       for all others]
1151           Valgrind translates and instruments your program's machine code in
1152           small fragments (basic blocks). The translations are stored in a
1153           translation cache that is divided into a number of sections
1154           (sectors). If the cache is full, the sector containing the oldest
1155           translations is emptied and reused. If these old translations are
1156           needed again, Valgrind must re-translate and re-instrument the
1157           corresponding machine code, which is expensive. If the "executed
1158           instructions" working set of a program is big, increasing the
1159           number of sectors may improve performance by reducing the number of
1160           re-translations needed. Sectors are allocated on demand. Once
1161           allocated, a sector can never be freed, and occupies considerable
1162           space, depending on the tool and the value of
1163           --avg-transtab-entry-size (about 40 MB per sector for Memcheck).
1164           Use the option --stats=yes to obtain precise information about the
1165           memory used by a sector and the allocation and recycling of
1166           sectors.
1167
1168       --avg-transtab-entry-size=<number> [default: 0, meaning use tool
1169       provided default]
1170           Average size of translated basic block. This average size is used
1171           to dimension the size of a sector. Each tool provides a default
1172           value to be used. If this default value is too small, the
1173           translation sectors will become full too quickly. If this default
1174           value is too big, a significant part of the translation sector
1175           memory will be unused. Note that the average size of a basic block
1176           translation depends on the tool, and might depend on tool options.
1177           For example, the memcheck option --track-origins=yes increases the
1178           size of the basic block translations. Use --avg-transtab-entry-size
1179           to tune the size of the sectors, either to gain memory or to avoid
1180           too many retranslations.
1181
1182       --aspace-minaddr=<address> [default: depends on the platform]
1183           To avoid potential conflicts with some system libraries, Valgrind
1184           does not use the address space below --aspace-minaddr value,
1185           keeping it reserved in case a library specifically requests memory
1186           in this region. So, some "pessimistic" value is guessed by Valgrind
1187           depending on the platform. On linux, by default, Valgrind avoids
1188           using the first 64MB even if typically there is no conflict in this
1189           complete zone. You can use the option --aspace-minaddr to have your
1190           memory hungry application benefitting from more of this lower
1191           memory. On the other hand, if you encounter a conflict, increasing
1192           aspace-minaddr value might solve it. Conflicts will typically
1193           manifest themselves with mmap failures in the low range of the
1194           address space. The provided address must be page aligned and must
1195           be equal or bigger to 0x1000 (4KB). To find the default value on
1196           your platform, do something such as valgrind -d -d date 2>&1 | grep
1197           -i minaddr. Values lower than 0x10000 (64KB) are known to create
1198           problems on some distributions.
1199
1200       --valgrind-stacksize=<number> [default: 1MB]
1201           For each thread, Valgrind needs its own 'private' stack. The
1202           default size for these stacks is largely dimensioned, and so should
1203           be sufficient in most cases. In case the size is too small,
1204           Valgrind will segfault. Before segfaulting, a warning might be
1205           produced by Valgrind when approaching the limit.
1206
1207           Use the option --valgrind-stacksize if such an (unlikely) warning
1208           is produced, or Valgrind dies due to a segmentation violation. Such
1209           segmentation violations have been seen when demangling huge C++
1210           symbols.
1211
1212           If your application uses many threads and needs a lot of memory,
1213           you can gain some memory by reducing the size of these Valgrind
1214           stacks using the option --valgrind-stacksize.
1215
1216       --show-emwarns=<yes|no> [default: no]
1217           When enabled, Valgrind will emit warnings about its CPU emulation
1218           in certain cases. These are usually not interesting.
1219
1220       --require-text-symbol=:sonamepatt:fnnamepatt
1221           When a shared object whose soname matches sonamepatt is loaded into
1222           the process, examine all the text symbols it exports. If none of
1223           those match fnnamepatt, print an error message and abandon the run.
1224           This makes it possible to ensure that the run does not continue
1225           unless a given shared object contains a particular function name.
1226
1227           Both sonamepatt and fnnamepatt can be written using the usual ?
1228           and * wildcards. For example: ":*libc.so*:foo?bar". You may use
1229           characters other than a colon to separate the two patterns. It is
1230           only important that the first character and the separator character
1231           are the same. For example, the above example could also be written
1232           "Q*libc.so*Qfoo?bar". Multiple
1233            --require-text-symbol flags are allowed, in which case shared
1234           objects that are loaded into the process will be checked against
1235           all of them.
1236
1237           The purpose of this is to support reliable usage of marked-up
1238           libraries. For example, suppose we have a version of GCC's
1239           libgomp.so which has been marked up with annotations to support
1240           Helgrind. It is only too easy and confusing to load the wrong,
1241           un-annotated libgomp.so into the application. So the idea is: add a
1242           text symbol in the marked-up library, for example
1243           annotated_for_helgrind_3_6, and then give the flag
1244           --require-text-symbol=:*libgomp*so*:annotated_for_helgrind_3_6 so
1245           that when libgomp.so is loaded, Valgrind scans its symbol table,
1246           and if the symbol isn't present the run is aborted, rather than
1247           continuing silently with the un-marked-up library. Note that you
1248           should put the entire flag in quotes to stop shells expanding up
1249           the * and ?  wildcards.
1250
1251       --soname-synonyms=syn1=pattern1,syn2=pattern2,...
1252           When a shared library is loaded, Valgrind checks for functions in
1253           the library that must be replaced or wrapped. For example, Memcheck
1254           replaces some string and memory functions (strchr, strlen, strcpy,
1255           memchr, memcpy, memmove, etc.) with its own versions. Such
1256           replacements are normally done only in shared libraries whose
1257           soname matches a predefined soname pattern (e.g.  libc.so* on
1258           linux). By default, no replacement is done for a statically linked
1259           binary or for alternative libraries, except for the allocation
1260           functions (malloc, free, calloc, memalign, realloc, operator new,
1261           operator delete, etc.) Such allocation functions are intercepted by
1262           default in any shared library or in the executable if they are
1263           exported as global symbols. This means that if a replacement
1264           allocation library such as tcmalloc is found, its functions are
1265           also intercepted by default. In some cases, the replacements allow
1266           --soname-synonyms to specify one additional synonym pattern, giving
1267           flexibility in the replacement. Or to prevent interception of all
1268           public allocation symbols.
1269
1270           Currently, this flexibility is only allowed for the malloc related
1271           functions, using the synonym somalloc. This synonym is usable for
1272           all tools doing standard replacement of malloc related functions
1273           (e.g. memcheck, helgrind, drd, massif, dhat).
1274
1275           •   Alternate malloc library: to replace the malloc related
1276               functions in a specific alternate library with soname
1277               mymalloclib.so (and not in any others), give the option
1278               --soname-synonyms=somalloc=mymalloclib.so. A pattern can be
1279               used to match multiple libraries sonames. For example,
1280               --soname-synonyms=somalloc=*tcmalloc* will match the soname of
1281               all variants of the tcmalloc library (native, debug, profiled,
1282               ... tcmalloc variants).
1283
1284               Note: the soname of a elf shared library can be retrieved using
1285               the readelf utility.
1286
1287           •   Replacements in a statically linked library are done by using
1288               the NONE pattern. For example, if you link with libtcmalloc.a,
1289               and only want to intercept the malloc related functions in the
1290               executable (and standard libraries) themselves, but not any
1291               other shared libraries, you can give the option
1292               --soname-synonyms=somalloc=NONE. Note that a NONE pattern will
1293               match the main executable and any shared library having no
1294               soname.
1295
1296           •   To run a "default" Firefox build for Linux, in which JEMalloc
1297               is linked in to the main executable, use
1298               --soname-synonyms=somalloc=NONE.
1299
1300           •   To only intercept allocation symbols in the default system
1301               libraries, but not in any other shared library or the
1302               executable defining public malloc or operator new related
1303               functions use a non-existing library name like
1304               --soname-synonyms=somalloc=nouserintercepts (where
1305               nouserintercepts can be any non-existing library name).
1306
1307           •   Shared library of the dynamic (runtime) linker is excluded from
1308               searching for global public symbols, such as those for the
1309               malloc related functions (identified by somalloc synonym).
1310
1311       --progress-interval=<number> [default: 0, meaning 'disabled']
1312           This is an enhancement to Valgrind's debugging output. It is
1313           unlikely to be of interest to end users.
1314
1315           When number is set to a non-zero value, Valgrind will print a
1316           one-line progress summary every number seconds. Valid settings for
1317           number are between 0 and 3600 inclusive. Here's some example output
1318           with number set to 10:
1319
1320               PROGRESS: U 110s, W 113s, 97.3% CPU, EvC 414.79M, TIn 616.7k, TOut 0.5k, #thr 67
1321               PROGRESS: U 120s, W 124s, 96.8% CPU, EvC 505.27M, TIn 636.6k, TOut 3.0k, #thr 64
1322               PROGRESS: U 130s, W 134s, 97.0% CPU, EvC 574.90M, TIn 657.5k, TOut 3.0k, #thr 63
1323
1324           Each line shows:
1325
1326U: total user time
1327
1328W: total wallclock time
1329
1330CPU: overall average cpu use
1331
1332EvC: number of event checks. An event check is a backwards
1333               branch in the simulated program, so this is a measure of
1334               forward progress of the program
1335
1336TIn: number of code blocks instrumented by the JIT
1337
1338TOut: number of instrumented code blocks that have been thrown
1339               away
1340
1341#thr: number of threads in the program
1342
1343           From the progress of these, it is possible to observe:
1344
1345           •   when the program is compute bound (TIn rises slowly, EvC rises
1346               rapidly)
1347
1348           •   when the program is in a spinloop (TIn/TOut fixed, EvC rises
1349               rapidly)
1350
1351           •   when the program is JIT-bound (TIn rises rapidly)
1352
1353           •   when the program is rapidly discarding code (TOut rises
1354               rapidly)
1355
1356           •   when the program is about to achieve some expected state (EvC
1357               arrives at some value you expect)
1358
1359           •   when the program is idling (U rises more slowly than W)
1360
1361

DEBUGGING VALGRIND OPTIONS

1363       There are also some options for debugging Valgrind itself. You
1364       shouldn't need to use them in the normal run of things. If you wish to
1365       see the list, use the --help-debug option.
1366

MEMCHECK OPTIONS

1368       --leak-check=<no|summary|yes|full> [default: summary]
1369           When enabled, search for memory leaks when the client program
1370           finishes. If set to summary, it says how many leaks occurred. If
1371           set to full or yes, each individual leak will be shown in detail
1372           and/or counted as an error, as specified by the options
1373           --show-leak-kinds and --errors-for-leak-kinds.
1374
1375           If --xml=yes is given, memcheck will automatically use the value
1376           --leak-check=full. You can use --show-leak-kinds=none to reduce the
1377           size of the xml output if you are not interested in the leak
1378           results.
1379
1380       --leak-resolution=<low|med|high> [default: high]
1381           When doing leak checking, determines how willing Memcheck is to
1382           consider different backtraces to be the same for the purposes of
1383           merging multiple leaks into a single leak report. When set to low,
1384           only the first two entries need match. When med, four entries have
1385           to match. When high, all entries need to match.
1386
1387           For hardcore leak debugging, you probably want to use
1388           --leak-resolution=high together with --num-callers=40 or some such
1389           large number.
1390
1391           Note that the --leak-resolution setting does not affect Memcheck's
1392           ability to find leaks. It only changes how the results are
1393           presented.
1394
1395       --show-leak-kinds=<set> [default: definite,possible]
1396           Specifies the leak kinds to show in a full leak search, in one of
1397           the following ways:
1398
1399           •   a comma separated list of one or more of definite indirect
1400               possible reachable.
1401
1402all to specify the complete set (all leak kinds). It is
1403               equivalent to
1404               --show-leak-kinds=definite,indirect,possible,reachable.
1405
1406none for the empty set.
1407
1408       --errors-for-leak-kinds=<set> [default: definite,possible]
1409           Specifies the leak kinds to count as errors in a full leak search.
1410           The <set> is specified similarly to --show-leak-kinds
1411
1412       --leak-check-heuristics=<set> [default: all]
1413           Specifies the set of leak check heuristics to be used during leak
1414           searches. The heuristics control which interior pointers to a block
1415           cause it to be considered as reachable. The heuristic set is
1416           specified in one of the following ways:
1417
1418           •   a comma separated list of one or more of stdstring length64
1419               newarray multipleinheritance.
1420
1421all to activate the complete set of heuristics. It is
1422               equivalent to
1423               --leak-check-heuristics=stdstring,length64,newarray,multipleinheritance.
1424
1425none for the empty set.
1426
1427           Note that these heuristics are dependent on the layout of the
1428           objects produced by the C++ compiler. They have been tested with
1429           some gcc versions (e.g. 4.4 and 4.7). They might not work properly
1430           with other C++ compilers.
1431
1432       --show-reachable=<yes|no> , --show-possibly-lost=<yes|no>
1433           These options provide an alternative way to specify the leak kinds
1434           to show:
1435
1436--show-reachable=no --show-possibly-lost=yes is equivalent to
1437               --show-leak-kinds=definite,possible.
1438
1439--show-reachable=no --show-possibly-lost=no is equivalent to
1440               --show-leak-kinds=definite.
1441
1442--show-reachable=yes is equivalent to --show-leak-kinds=all.
1443
1444           Note that --show-possibly-lost=no has no effect if
1445           --show-reachable=yes is specified.
1446
1447       --xtree-leak=<no|yes> [no]
1448           If set to yes, the results for the leak search done at exit will be
1449           output in a 'Callgrind Format' execution tree file. Note that this
1450           automatically sets the options --leak-check=full and
1451           --show-leak-kinds=all, to allow xtree visualisation tools such as
1452           kcachegrind to select what kind to leak to visualise. The produced
1453           file will contain the following events:
1454
1455RB : Reachable Bytes
1456
1457PB : Possibly lost Bytes
1458
1459IB : Indirectly lost Bytes
1460
1461DB : Definitely lost Bytes (direct plus indirect)
1462
1463DIB : Definitely Indirectly lost Bytes (subset of DB)
1464
1465RBk : reachable Blocks
1466
1467PBk : Possibly lost Blocks
1468
1469IBk : Indirectly lost Blocks
1470
1471DBk : Definitely lost Blocks
1472
1473           The increase or decrease for all events above will also be output
1474           in the file to provide the delta (increase or decrease) between 2
1475           successive leak searches. For example, iRB is the increase of the
1476           RB event, dPBk is the decrease of PBk event. The values for the
1477           increase and decrease events will be zero for the first leak search
1478           done.
1479
1480           See Execution Trees for a detailed explanation about execution
1481           trees.
1482
1483       --xtree-leak-file=<filename> [default: xtleak.kcg.%p]
1484           Specifies that Valgrind should produce the xtree leak report in the
1485           specified file. Any %p, %q or %n sequences appearing in the
1486           filename are expanded in exactly the same way as they are for
1487           --log-file. See the description of --log-file for details.
1488
1489           See Execution Trees for a detailed explanation about execution
1490           trees formats.
1491
1492       --undef-value-errors=<yes|no> [default: yes]
1493           Controls whether Memcheck reports uses of undefined value errors.
1494           Set this to no if you don't want to see undefined value errors. It
1495           also has the side effect of speeding up Memcheck somewhat.
1496           AddrCheck (removed in Valgrind 3.1.0) functioned like Memcheck with
1497           --undef-value-errors=no.
1498
1499       --track-origins=<yes|no> [default: no]
1500           Controls whether Memcheck tracks the origin of uninitialised
1501           values. By default, it does not, which means that although it can
1502           tell you that an uninitialised value is being used in a dangerous
1503           way, it cannot tell you where the uninitialised value came from.
1504           This often makes it difficult to track down the root problem.
1505
1506           When set to yes, Memcheck keeps track of the origins of all
1507           uninitialised values. Then, when an uninitialised value error is
1508           reported, Memcheck will try to show the origin of the value. An
1509           origin can be one of the following four places: a heap block, a
1510           stack allocation, a client request, or miscellaneous other sources
1511           (eg, a call to brk).
1512
1513           For uninitialised values originating from a heap block, Memcheck
1514           shows where the block was allocated. For uninitialised values
1515           originating from a stack allocation, Memcheck can tell you which
1516           function allocated the value, but no more than that -- typically it
1517           shows you the source location of the opening brace of the function.
1518           So you should carefully check that all of the function's local
1519           variables are initialised properly.
1520
1521           Performance overhead: origin tracking is expensive. It halves
1522           Memcheck's speed and increases memory use by a minimum of 100MB,
1523           and possibly more. Nevertheless it can drastically reduce the
1524           effort required to identify the root cause of uninitialised value
1525           errors, and so is often a programmer productivity win, despite
1526           running more slowly.
1527
1528           Accuracy: Memcheck tracks origins quite accurately. To avoid very
1529           large space and time overheads, some approximations are made. It is
1530           possible, although unlikely, that Memcheck will report an incorrect
1531           origin, or not be able to identify any origin.
1532
1533           Note that the combination --track-origins=yes and
1534           --undef-value-errors=no is nonsensical. Memcheck checks for and
1535           rejects this combination at startup.
1536
1537       --partial-loads-ok=<yes|no> [default: yes]
1538           Controls how Memcheck handles 32-, 64-, 128- and 256-bit naturally
1539           aligned loads from addresses for which some bytes are addressable
1540           and others are not. When yes, such loads do not produce an address
1541           error. Instead, loaded bytes originating from illegal addresses are
1542           marked as uninitialised, and those corresponding to legal addresses
1543           are handled in the normal way.
1544
1545           When no, loads from partially invalid addresses are treated the
1546           same as loads from completely invalid addresses: an illegal-address
1547           error is issued, and the resulting bytes are marked as initialised.
1548
1549           Note that code that behaves in this way is in violation of the ISO
1550           C/C++ standards, and should be considered broken. If at all
1551           possible, such code should be fixed.
1552
1553       --expensive-definedness-checks=<no|auto|yes> [default: auto]
1554           Controls whether Memcheck should employ more precise but also more
1555           expensive (time consuming) instrumentation when checking the
1556           definedness of certain values. In particular, this affects the
1557           instrumentation of integer adds, subtracts and equality
1558           comparisons.
1559
1560           Selecting --expensive-definedness-checks=yes causes Memcheck to use
1561           the most accurate analysis possible. This minimises false error
1562           rates but can cause up to 30% performance degradation.
1563
1564           Selecting --expensive-definedness-checks=no causes Memcheck to use
1565           the cheapest instrumentation possible. This maximises performance
1566           but will normally give an unusably high false error rate.
1567
1568           The default setting, --expensive-definedness-checks=auto, is
1569           strongly recommended. This causes Memcheck to use the minimum of
1570           expensive instrumentation needed to achieve the same false error
1571           rate as --expensive-definedness-checks=yes. It also enables an
1572           instrumentation-time analysis pass which aims to further reduce the
1573           costs of accurate instrumentation. Overall, the performance loss is
1574           generally around 5% relative to --expensive-definedness-checks=no,
1575           although this is strongly workload dependent. Note that the exact
1576           instrumentation settings in this mode are architecture dependent.
1577
1578       --keep-stacktraces=alloc|free|alloc-and-free|alloc-then-free|none
1579       [default: alloc-and-free]
1580           Controls which stack trace(s) to keep for malloc'd and/or free'd
1581           blocks.
1582
1583           With alloc-then-free, a stack trace is recorded at allocation time,
1584           and is associated with the block. When the block is freed, a second
1585           stack trace is recorded, and this replaces the allocation stack
1586           trace. As a result, any "use after free" errors relating to this
1587           block can only show a stack trace for where the block was freed.
1588
1589           With alloc-and-free, both allocation and the deallocation stack
1590           traces for the block are stored. Hence a "use after free" error
1591           will show both, which may make the error easier to diagnose.
1592           Compared to alloc-then-free, this setting slightly increases
1593           Valgrind's memory use as the block contains two references instead
1594           of one.
1595
1596           With alloc, only the allocation stack trace is recorded (and
1597           reported). With free, only the deallocation stack trace is recorded
1598           (and reported). These values somewhat decrease Valgrind's memory
1599           and cpu usage. They can be useful depending on the error types you
1600           are searching for and the level of detail you need to analyse them.
1601           For example, if you are only interested in memory leak errors, it
1602           is sufficient to record the allocation stack traces.
1603
1604           With none, no stack traces are recorded for malloc and free
1605           operations. If your program allocates a lot of blocks and/or
1606           allocates/frees from many different stack traces, this can
1607           significantly decrease cpu and/or memory required. Of course, few
1608           details will be reported for errors related to heap blocks.
1609
1610           Note that once a stack trace is recorded, Valgrind keeps the stack
1611           trace in memory even if it is not referenced by any block. Some
1612           programs (for example, recursive algorithms) can generate a huge
1613           number of stack traces. If Valgrind uses too much memory in such
1614           circumstances, you can reduce the memory required with the options
1615           --keep-stacktraces and/or by using a smaller value for the option
1616           --num-callers.
1617
1618           If you want to use --xtree-memory=full memory profiling (see
1619           Execution Trees), then you cannot specify --keep-stacktraces=free
1620           or --keep-stacktraces=none.
1621
1622       --freelist-vol=<number> [default: 20000000]
1623           When the client program releases memory using free (in C) or delete
1624           (C++), that memory is not immediately made available for
1625           re-allocation. Instead, it is marked inaccessible and placed in a
1626           queue of freed blocks. The purpose is to defer as long as possible
1627           the point at which freed-up memory comes back into circulation.
1628           This increases the chance that Memcheck will be able to detect
1629           invalid accesses to blocks for some significant period of time
1630           after they have been freed.
1631
1632           This option specifies the maximum total size, in bytes, of the
1633           blocks in the queue. The default value is twenty million bytes.
1634           Increasing this increases the total amount of memory used by
1635           Memcheck but may detect invalid uses of freed blocks which would
1636           otherwise go undetected.
1637
1638       --freelist-big-blocks=<number> [default: 1000000]
1639           When making blocks from the queue of freed blocks available for
1640           re-allocation, Memcheck will in priority re-circulate the blocks
1641           with a size greater or equal to --freelist-big-blocks. This ensures
1642           that freeing big blocks (in particular freeing blocks bigger than
1643           --freelist-vol) does not immediately lead to a re-circulation of
1644           all (or a lot of) the small blocks in the free list. In other
1645           words, this option increases the likelihood to discover dangling
1646           pointers for the "small" blocks, even when big blocks are freed.
1647
1648           Setting a value of 0 means that all the blocks are re-circulated in
1649           a FIFO order.
1650
1651       --workaround-gcc296-bugs=<yes|no> [default: no]
1652           When enabled, assume that reads and writes some small distance
1653           below the stack pointer are due to bugs in GCC 2.96, and does not
1654           report them. The "small distance" is 256 bytes by default. Note
1655           that GCC 2.96 is the default compiler on some ancient Linux
1656           distributions (RedHat 7.X) and so you may need to use this option.
1657           Do not use it if you do not have to, as it can cause real errors to
1658           be overlooked. A better alternative is to use a more recent GCC in
1659           which this bug is fixed.
1660
1661           You may also need to use this option when working with GCC 3.X or
1662           4.X on 32-bit PowerPC Linux. This is because GCC generates code
1663           which occasionally accesses below the stack pointer, particularly
1664           for floating-point to/from integer conversions. This is in
1665           violation of the 32-bit PowerPC ELF specification, which makes no
1666           provision for locations below the stack pointer to be accessible.
1667
1668           This option is deprecated as of version 3.12 and may be removed
1669           from future versions. You should instead use
1670           --ignore-range-below-sp to specify the exact range of offsets below
1671           the stack pointer that should be ignored. A suitable equivalent is
1672           --ignore-range-below-sp=1024-1.
1673
1674       --ignore-range-below-sp=<number>-<number>
1675           This is a more general replacement for the deprecated
1676           --workaround-gcc296-bugs option. When specified, it causes Memcheck
1677           not to report errors for accesses at the specified offsets below
1678           the stack pointer. The two offsets must be positive decimal numbers
1679           and -- somewhat counterintuitively -- the first one must be larger,
1680           in order to imply a non-wraparound address range to ignore. For
1681           example, to ignore 4 byte accesses at 8192 bytes below the stack
1682           pointer, use --ignore-range-below-sp=8192-8189. Only one range may
1683           be specified.
1684
1685       --show-mismatched-frees=<yes|no> [default: yes]
1686           When enabled, Memcheck checks that heap blocks are deallocated
1687           using a function that matches the allocating function. That is, it
1688           expects free to be used to deallocate blocks allocated by malloc,
1689           delete for blocks allocated by new, and delete[] for blocks
1690           allocated by new[]. If a mismatch is detected, an error is
1691           reported. This is in general important because in some
1692           environments, freeing with a non-matching function can cause
1693           crashes.
1694
1695           There is however a scenario where such mismatches cannot be
1696           avoided. That is when the user provides implementations of
1697           new/new[] that call malloc and of delete/delete[] that call free,
1698           and these functions are asymmetrically inlined. For example,
1699           imagine that delete[] is inlined but new[] is not. The result is
1700           that Memcheck "sees" all delete[] calls as direct calls to free,
1701           even when the program source contains no mismatched calls.
1702
1703           This causes a lot of confusing and irrelevant error reports.
1704           --show-mismatched-frees=no disables these checks. It is not
1705           generally advisable to disable them, though, because you may miss
1706           real errors as a result.
1707
1708       --ignore-ranges=0xPP-0xQQ[,0xRR-0xSS]
1709           Any ranges listed in this option (and multiple ranges can be
1710           specified, separated by commas) will be ignored by Memcheck's
1711           addressability checking.
1712
1713       --malloc-fill=<hexnumber>
1714           Fills blocks allocated by malloc, new, etc, but not by calloc, with
1715           the specified byte. This can be useful when trying to shake out
1716           obscure memory corruption problems. The allocated area is still
1717           regarded by Memcheck as undefined -- this option only affects its
1718           contents. Note that --malloc-fill does not affect a block of memory
1719           when it is used as argument to client requests
1720           VALGRIND_MEMPOOL_ALLOC or VALGRIND_MALLOCLIKE_BLOCK.
1721
1722       --free-fill=<hexnumber>
1723           Fills blocks freed by free, delete, etc, with the specified byte
1724           value. This can be useful when trying to shake out obscure memory
1725           corruption problems. The freed area is still regarded by Memcheck
1726           as not valid for access -- this option only affects its contents.
1727           Note that --free-fill does not affect a block of memory when it is
1728           used as argument to client requests VALGRIND_MEMPOOL_FREE or
1729           VALGRIND_FREELIKE_BLOCK.
1730

CACHEGRIND OPTIONS

1732       --I1=<size>,<associativity>,<line size>
1733           Specify the size, associativity and line size of the level 1
1734           instruction cache.
1735
1736       --D1=<size>,<associativity>,<line size>
1737           Specify the size, associativity and line size of the level 1 data
1738           cache.
1739
1740       --LL=<size>,<associativity>,<line size>
1741           Specify the size, associativity and line size of the last-level
1742           cache.
1743
1744       --cache-sim=no|yes [yes]
1745           Enables or disables collection of cache access and miss counts.
1746
1747       --branch-sim=no|yes [no]
1748           Enables or disables collection of branch instruction and
1749           misprediction counts. By default this is disabled as it slows
1750           Cachegrind down by approximately 25%. Note that you cannot specify
1751           --cache-sim=no and --branch-sim=no together, as that would leave
1752           Cachegrind with no information to collect.
1753
1754       --cachegrind-out-file=<file>
1755           Write the profile data to file rather than to the default output
1756           file, cachegrind.out.<pid>. The %p and %q format specifiers can be
1757           used to embed the process ID and/or the contents of an environment
1758           variable in the name, as is the case for the core option
1759           --log-file.
1760

CALLGRIND OPTIONS

1762       --callgrind-out-file=<file>
1763           Write the profile data to file rather than to the default output
1764           file, callgrind.out.<pid>. The %p and %q format specifiers can be
1765           used to embed the process ID and/or the contents of an environment
1766           variable in the name, as is the case for the core option
1767           --log-file. When multiple dumps are made, the file name is modified
1768           further; see below.
1769
1770       --dump-line=<no|yes> [default: yes]
1771           This specifies that event counting should be performed at source
1772           line granularity. This allows source annotation for sources which
1773           are compiled with debug information (-g).
1774
1775       --dump-instr=<no|yes> [default: no]
1776           This specifies that event counting should be performed at
1777           per-instruction granularity. This allows for assembly code
1778           annotation. Currently the results can only be displayed by
1779           KCachegrind.
1780
1781       --compress-strings=<no|yes> [default: yes]
1782           This option influences the output format of the profile data. It
1783           specifies whether strings (file and function names) should be
1784           identified by numbers. This shrinks the file, but makes it more
1785           difficult for humans to read (which is not recommended in any
1786           case).
1787
1788       --compress-pos=<no|yes> [default: yes]
1789           This option influences the output format of the profile data. It
1790           specifies whether numerical positions are always specified as
1791           absolute values or are allowed to be relative to previous numbers.
1792           This shrinks the file size.
1793
1794       --combine-dumps=<no|yes> [default: no]
1795           When enabled, when multiple profile data parts are to be generated
1796           these parts are appended to the same output file. Not recommended.
1797
1798       --dump-every-bb=<count> [default: 0, never]
1799           Dump profile data every count basic blocks. Whether a dump is
1800           needed is only checked when Valgrind's internal scheduler is run.
1801           Therefore, the minimum setting useful is about 100000. The count is
1802           a 64-bit value to make long dump periods possible.
1803
1804       --dump-before=<function>
1805           Dump when entering function.
1806
1807       --zero-before=<function>
1808           Zero all costs when entering function.
1809
1810       --dump-after=<function>
1811           Dump when leaving function.
1812
1813       --instr-atstart=<yes|no> [default: yes]
1814           Specify if you want Callgrind to start simulation and profiling
1815           from the beginning of the program. When set to no, Callgrind will
1816           not be able to collect any information, including calls, but it
1817           will have at most a slowdown of around 4, which is the minimum
1818           Valgrind overhead. Instrumentation can be interactively enabled via
1819           callgrind_control -i on.
1820
1821           Note that the resulting call graph will most probably not contain
1822           main, but will contain all the functions executed after
1823           instrumentation was enabled. Instrumentation can also be
1824           programmatically enabled/disabled. See the Callgrind include file
1825           callgrind.h for the macro you have to use in your source code.
1826
1827           For cache simulation, results will be less accurate when switching
1828           on instrumentation later in the program run, as the simulator
1829           starts with an empty cache at that moment. Switch on event
1830           collection later to cope with this error.
1831
1832       --collect-atstart=<yes|no> [default: yes]
1833           Specify whether event collection is enabled at beginning of the
1834           profile run.
1835
1836           To only look at parts of your program, you have two possibilities:
1837
1838            1. Zero event counters before entering the program part you want
1839               to profile, and dump the event counters to a file after leaving
1840               that program part.
1841
1842            2. Switch on/off collection state as needed to only see event
1843               counters happening while inside of the program part you want to
1844               profile.
1845
1846           The second option can be used if the program part you want to
1847           profile is called many times. Option 1, i.e. creating a lot of
1848           dumps is not practical here.
1849
1850           Collection state can be toggled at entry and exit of a given
1851           function with the option --toggle-collect. If you use this option,
1852           collection state should be disabled at the beginning. Note that the
1853           specification of --toggle-collect implicitly sets
1854           --collect-state=no.
1855
1856           Collection state can be toggled also by inserting the client
1857           request CALLGRIND_TOGGLE_COLLECT ; at the needed code positions.
1858
1859       --toggle-collect=<function>
1860           Toggle collection on entry/exit of function.
1861
1862       --collect-jumps=<no|yes> [default: no]
1863           This specifies whether information for (conditional) jumps should
1864           be collected. As above, callgrind_annotate currently is not able to
1865           show you the data. You have to use KCachegrind to get jump arrows
1866           in the annotated code.
1867
1868       --collect-systime=<no|yes|msec|usec|nsec> [default: no]
1869           This specifies whether information for system call times should be
1870           collected.
1871
1872           The value no indicates to record no system call information.
1873
1874           The other values indicate to record the number of system calls done
1875           (sysCount event) and the elapsed time (sysTime event) spent in
1876           system calls. The --collect-systime value gives the unit used for
1877           sysTime : milli seconds, micro seconds or nano seconds. With the
1878           value nsec, callgrind also records the cpu time spent during system
1879           calls (sysCpuTime).
1880
1881           The value yes is a synonym of msec. The value nsec is not supported
1882           on Darwin.
1883
1884       --collect-bus=<no|yes> [default: no]
1885           This specifies whether the number of global bus events executed
1886           should be collected. The event type "Ge" is used for these events.
1887
1888       --cache-sim=<yes|no> [default: no]
1889           Specify if you want to do full cache simulation. By default, only
1890           instruction read accesses will be counted ("Ir"). With cache
1891           simulation, further event counters are enabled: Cache misses on
1892           instruction reads ("I1mr"/"ILmr"), data read accesses ("Dr") and
1893           related cache misses ("D1mr"/"DLmr"), data write accesses ("Dw")
1894           and related cache misses ("D1mw"/"DLmw"). For more information, see
1895           Cachegrind: a cache and branch-prediction profiler.
1896
1897       --branch-sim=<yes|no> [default: no]
1898           Specify if you want to do branch prediction simulation. Further
1899           event counters are enabled: Number of executed conditional branches
1900           and related predictor misses ("Bc"/"Bcm"), executed indirect jumps
1901           and related misses of the jump address predictor ("Bi"/"Bim").
1902

HELGRIND OPTIONS

1904       --free-is-write=no|yes [default: no]
1905           When enabled (not the default), Helgrind treats freeing of heap
1906           memory as if the memory was written immediately before the free.
1907           This exposes races where memory is referenced by one thread, and
1908           freed by another, but there is no observable synchronisation event
1909           to ensure that the reference happens before the free.
1910
1911           This functionality is new in Valgrind 3.7.0, and is regarded as
1912           experimental. It is not enabled by default because its interaction
1913           with custom memory allocators is not well understood at present.
1914           User feedback is welcomed.
1915
1916       --track-lockorders=no|yes [default: yes]
1917           When enabled (the default), Helgrind performs lock order
1918           consistency checking. For some buggy programs, the large number of
1919           lock order errors reported can become annoying, particularly if
1920           you're only interested in race errors. You may therefore find it
1921           helpful to disable lock order checking.
1922
1923       --history-level=none|approx|full [default: full]
1924           --history-level=full (the default) causes Helgrind collects enough
1925           information about "old" accesses that it can produce two stack
1926           traces in a race report -- both the stack trace for the current
1927           access, and the trace for the older, conflicting access. To limit
1928           memory usage, "old" accesses stack traces are limited to a maximum
1929           of 8 entries, even if --num-callers value is bigger.
1930
1931           Collecting such information is expensive in both speed and memory,
1932           particularly for programs that do many inter-thread synchronisation
1933           events (locks, unlocks, etc). Without such information, it is more
1934           difficult to track down the root causes of races. Nonetheless, you
1935           may not need it in situations where you just want to check for the
1936           presence or absence of races, for example, when doing regression
1937           testing of a previously race-free program.
1938
1939           --history-level=none is the opposite extreme. It causes Helgrind
1940           not to collect any information about previous accesses. This can be
1941           dramatically faster than --history-level=full.
1942
1943           --history-level=approx provides a compromise between these two
1944           extremes. It causes Helgrind to show a full trace for the later
1945           access, and approximate information regarding the earlier access.
1946           This approximate information consists of two stacks, and the
1947           earlier access is guaranteed to have occurred somewhere between
1948           program points denoted by the two stacks. This is not as useful as
1949           showing the exact stack for the previous access (as
1950           --history-level=full does), but it is better than nothing, and it
1951           is almost as fast as --history-level=none.
1952
1953       --delta-stacktrace=no|yes [default: yes on linux amd64/x86]
1954           This flag only has any effect at --history-level=full.
1955
1956           --delta-stacktrace configures the way Helgrind captures the
1957           stacktraces for the option --history-level=full. Such a stacktrace
1958           is typically needed each time a new piece of memory is read or
1959           written in a basic block of instructions.
1960
1961           --delta-stacktrace=no causes Helgrind to compute a full history
1962           stacktrace from the unwind info each time a stacktrace is needed.
1963
1964           --delta-stacktrace=yes indicates to Helgrind to derive a new
1965           stacktrace from the previous stacktrace, as long as there was no
1966           call instruction, no return instruction, or any other instruction
1967           changing the call stack since the previous stacktrace was captured.
1968           If no such instruction was executed, the new stacktrace can be
1969           derived from the previous stacktrace by just changing the top frame
1970           to the current program counter. This option can speed up Helgrind
1971           by 25% when using --history-level=full.
1972
1973           The following aspects have to be considered when using
1974           --delta-stacktrace=yes :
1975
1976           •   In some cases (for example in a function prologue), the
1977               valgrind unwinder might not properly unwind the stack, due to
1978               some limitations and/or due to wrong unwind info. When using
1979               --delta-stacktrace=yes, the wrong stack trace captured in the
1980               function prologue will be kept till the next call or return.
1981
1982           •   On the other hand, --delta-stacktrace=yes sometimes helps to
1983               obtain a correct stacktrace, for example when the unwind info
1984               allows a correct stacktrace to be done in the beginning of the
1985               sequence, but not later on in the instruction sequence.
1986
1987           •   Determining which instructions are changing the callstack is
1988               partially based on platform dependent heuristics, which have to
1989               be tuned/validated specifically for the platform. Also,
1990               unwinding in a function prologue must be good enough to allow
1991               using --delta-stacktrace=yes. Currently, the option
1992               --delta-stacktrace=yes has been reasonably validated only on
1993               linux x86 32 bits and linux amd64 64 bits. For more details
1994               about how to validate --delta-stacktrace=yes, see debug option
1995               --hg-sanity-flags and the function check_cached_rcec_ok in
1996               libhb_core.c.
1997
1998
1999       --conflict-cache-size=N [default: 1000000]
2000           This flag only has any effect at --history-level=full.
2001
2002           Information about "old" conflicting accesses is stored in a cache
2003           of limited size, with LRU-style management. This is necessary
2004           because it isn't practical to store a stack trace for every single
2005           memory access made by the program. Historical information on not
2006           recently accessed locations is periodically discarded, to free up
2007           space in the cache.
2008
2009           This option controls the size of the cache, in terms of the number
2010           of different memory addresses for which conflicting access
2011           information is stored. If you find that Helgrind is showing race
2012           errors with only one stack instead of the expected two stacks, try
2013           increasing this value.
2014
2015           The minimum value is 10,000 and the maximum is 30,000,000 (thirty
2016           times the default value). Increasing the value by 1 increases
2017           Helgrind's memory requirement by very roughly 100 bytes, so the
2018           maximum value will easily eat up three extra gigabytes or so of
2019           memory.
2020
2021       --check-stack-refs=no|yes [default: yes]
2022           By default Helgrind checks all data memory accesses made by your
2023           program. This flag enables you to skip checking for accesses to
2024           thread stacks (local variables). This can improve performance, but
2025           comes at the cost of missing races on stack-allocated data.
2026
2027       --ignore-thread-creation=<yes|no> [default: no]
2028           Controls whether all activities during thread creation should be
2029           ignored. By default enabled only on Solaris. Solaris provides
2030           higher throughput, parallelism and scalability than other operating
2031           systems, at the cost of more fine-grained locking activity. This
2032           means for example that when a thread is created under glibc, just
2033           one big lock is used for all thread setup. Solaris libc uses
2034           several fine-grained locks and the creator thread resumes its
2035           activities as soon as possible, leaving for example stack and TLS
2036           setup sequence to the created thread. This situation confuses
2037           Helgrind as it assumes there is some false ordering in place
2038           between creator and created thread; and therefore many types of
2039           race conditions in the application would not be reported. To
2040           prevent such false ordering, this command line option is set to yes
2041           by default on Solaris. All activity (loads, stores, client
2042           requests) is therefore ignored during:
2043
2044           •   pthread_create() call in the creator thread
2045
2046           •   thread creation phase (stack and TLS setup) in the created
2047               thread
2048
2049           Also new memory allocated during thread creation is untracked, that
2050           is race reporting is suppressed there. DRD does the same thing
2051           implicitly. This is necessary because Solaris libc caches many
2052           objects and reuses them for different threads and that confuses
2053           Helgrind.
2054

DRD OPTIONS

2056       --check-stack-var=<yes|no> [default: no]
2057           Controls whether DRD detects data races on stack variables.
2058           Verifying stack variables is disabled by default because most
2059           programs do not share stack variables over threads.
2060
2061       --exclusive-threshold=<n> [default: off]
2062           Print an error message if any mutex or writer lock has been held
2063           longer than the time specified in milliseconds. This option enables
2064           the detection of lock contention.
2065
2066       --join-list-vol=<n> [default: 10]
2067           Data races that occur between a statement at the end of one thread
2068           and another thread can be missed if memory access information is
2069           discarded immediately after a thread has been joined. This option
2070           allows one to specify for how many joined threads memory access
2071           information should be retained.
2072
2073        --first-race-only=<yes|no> [default: no]
2074           Whether to report only the first data race that has been detected
2075           on a memory location or all data races that have been detected on a
2076           memory location.
2077
2078        --free-is-write=<yes|no> [default: no]
2079           Whether to report races between accessing memory and freeing
2080           memory. Enabling this option may cause DRD to run slightly slower.
2081           Notes:
2082
2083           •   Don't enable this option when using custom memory allocators
2084               that use the VG_USERREQ__MALLOCLIKE_BLOCK and
2085               VG_USERREQ__FREELIKE_BLOCK because that would result in false
2086               positives.
2087
2088           •   Don't enable this option when using reference-counted objects
2089               because that will result in false positives, even when that
2090               code has been annotated properly with ANNOTATE_HAPPENS_BEFORE
2091               and ANNOTATE_HAPPENS_AFTER. See e.g. the output of the
2092               following command for an example: valgrind --tool=drd
2093               --free-is-write=yes drd/tests/annotate_smart_pointer.
2094
2095        --report-signal-unlocked=<yes|no> [default: yes]
2096           Whether to report calls to pthread_cond_signal and
2097           pthread_cond_broadcast where the mutex associated with the signal
2098           through pthread_cond_wait or pthread_cond_timed_waitis not locked
2099           at the time the signal is sent. Sending a signal without holding a
2100           lock on the associated mutex is a common programming error which
2101           can cause subtle race conditions and unpredictable behavior. There
2102           exist some uncommon synchronization patterns however where it is
2103           safe to send a signal without holding a lock on the associated
2104           mutex.
2105
2106       --segment-merging=<yes|no> [default: yes]
2107           Controls segment merging. Segment merging is an algorithm to limit
2108           memory usage of the data race detection algorithm. Disabling
2109           segment merging may improve the accuracy of the so-called 'other
2110           segments' displayed in race reports but can also trigger an out of
2111           memory error.
2112
2113       --segment-merging-interval=<n> [default: 10]
2114           Perform segment merging only after the specified number of new
2115           segments have been created. This is an advanced configuration
2116           option that allows one to choose whether to minimize DRD's memory
2117           usage by choosing a low value or to let DRD run faster by choosing
2118           a slightly higher value. The optimal value for this parameter
2119           depends on the program being analyzed. The default value works well
2120           for most programs.
2121
2122       --shared-threshold=<n> [default: off]
2123           Print an error message if a reader lock has been held longer than
2124           the specified time (in milliseconds). This option enables the
2125           detection of lock contention.
2126
2127       --show-confl-seg=<yes|no> [default: yes]
2128           Show conflicting segments in race reports. Since this information
2129           can help to find the cause of a data race, this option is enabled
2130           by default. Disabling this option makes the output of DRD more
2131           compact.
2132
2133       --show-stack-usage=<yes|no> [default: no]
2134           Print stack usage at thread exit time. When a program creates a
2135           large number of threads it becomes important to limit the amount of
2136           virtual memory allocated for thread stacks. This option makes it
2137           possible to observe how much stack memory has been used by each
2138           thread of the client program. Note: the DRD tool itself allocates
2139           some temporary data on the client thread stack. The space necessary
2140           for this temporary data must be allocated by the client program
2141           when it allocates stack memory, but is not included in stack usage
2142           reported by DRD.
2143
2144       --ignore-thread-creation=<yes|no> [default: no]
2145           Controls whether all activities during thread creation should be
2146           ignored. By default enabled only on Solaris. Solaris provides
2147           higher throughput, parallelism and scalability than other operating
2148           systems, at the cost of more fine-grained locking activity. This
2149           means for example that when a thread is created under glibc, just
2150           one big lock is used for all thread setup. Solaris libc uses
2151           several fine-grained locks and the creator thread resumes its
2152           activities as soon as possible, leaving for example stack and TLS
2153           setup sequence to the created thread. This situation confuses DRD
2154           as it assumes there is some false ordering in place between creator
2155           and created thread; and therefore many types of race conditions in
2156           the application would not be reported. To prevent such false
2157           ordering, this command line option is set to yes by default on
2158           Solaris. All activity (loads, stores, client requests) is therefore
2159           ignored during:
2160
2161           •   pthread_create() call in the creator thread
2162
2163           •   thread creation phase (stack and TLS setup) in the created
2164               thread
2165
2166       --trace-addr=<address> [default: none]
2167           Trace all load and store activity for the specified address. This
2168           option may be specified more than once.
2169
2170       --ptrace-addr=<address> [default: none]
2171           Trace all load and store activity for the specified address and
2172           keep doing that even after the memory at that address has been
2173           freed and reallocated.
2174
2175       --trace-alloc=<yes|no> [default: no]
2176           Trace all memory allocations and deallocations. May produce a huge
2177           amount of output.
2178
2179       --trace-barrier=<yes|no> [default: no]
2180           Trace all barrier activity.
2181
2182       --trace-cond=<yes|no> [default: no]
2183           Trace all condition variable activity.
2184
2185       --trace-fork-join=<yes|no> [default: no]
2186           Trace all thread creation and all thread termination events.
2187
2188       --trace-hb=<yes|no> [default: no]
2189           Trace execution of the ANNOTATE_HAPPENS_BEFORE(),
2190           ANNOTATE_HAPPENS_AFTER() and ANNOTATE_HAPPENS_DONE() client
2191           requests.
2192
2193       --trace-mutex=<yes|no> [default: no]
2194           Trace all mutex activity.
2195
2196       --trace-rwlock=<yes|no> [default: no]
2197           Trace all reader-writer lock activity.
2198
2199       --trace-semaphore=<yes|no> [default: no]
2200           Trace all semaphore activity.
2201

MASSIF OPTIONS

2203       --heap=<yes|no> [default: yes]
2204           Specifies whether heap profiling should be done.
2205
2206       --heap-admin=<size> [default: 8]
2207           If heap profiling is enabled, gives the number of administrative
2208           bytes per block to use. This should be an estimate of the average,
2209           since it may vary. For example, the allocator used by glibc on
2210           Linux requires somewhere between 4 to 15 bytes per block, depending
2211           on various factors. That allocator also requires admin space for
2212           freed blocks, but Massif cannot account for this.
2213
2214       --stacks=<yes|no> [default: no]
2215           Specifies whether stack profiling should be done. This option slows
2216           Massif down greatly, and so is off by default. Note that Massif
2217           assumes that the main stack has size zero at start-up. This is not
2218           true, but doing otherwise accurately is difficult. Furthermore,
2219           starting at zero better indicates the size of the part of the main
2220           stack that a user program actually has control over.
2221
2222       --pages-as-heap=<yes|no> [default: no]
2223           Tells Massif to profile memory at the page level rather than at the
2224           malloc'd block level. See above for details.
2225
2226       --depth=<number> [default: 30]
2227           Maximum depth of the allocation trees recorded for detailed
2228           snapshots. Increasing it will make Massif run somewhat more slowly,
2229           use more memory, and produce bigger output files.
2230
2231       --alloc-fn=<name>
2232           Functions specified with this option will be treated as though they
2233           were a heap allocation function such as malloc. This is useful for
2234           functions that are wrappers to malloc or new, which can fill up the
2235           allocation trees with uninteresting information. This option can be
2236           specified multiple times on the command line, to name multiple
2237           functions.
2238
2239           Note that the named function will only be treated this way if it is
2240           the top entry in a stack trace, or just below another function
2241           treated this way. For example, if you have a function malloc1 that
2242           wraps malloc, and malloc2 that wraps malloc1, just specifying
2243           --alloc-fn=malloc2 will have no effect. You need to specify
2244           --alloc-fn=malloc1 as well. This is a little inconvenient, but the
2245           reason is that checking for allocation functions is slow, and it
2246           saves a lot of time if Massif can stop looking through the stack
2247           trace entries as soon as it finds one that doesn't match rather
2248           than having to continue through all the entries.
2249
2250           Note that C++ names are demangled. Note also that overloaded C++
2251           names must be written in full. Single quotes may be necessary to
2252           prevent the shell from breaking them up. For example:
2253
2254               --alloc-fn='operator new(unsigned, std::nothrow_t const&)'
2255
2256
2257       --ignore-fn=<name>
2258           Any direct heap allocation (i.e. a call to malloc, new, etc, or a
2259           call to a function named by an --alloc-fn option) that occurs in a
2260           function specified by this option will be ignored. This is mostly
2261           useful for testing purposes. This option can be specified multiple
2262           times on the command line, to name multiple functions.
2263
2264           Any realloc of an ignored block will also be ignored, even if the
2265           realloc call does not occur in an ignored function. This avoids the
2266           possibility of negative heap sizes if ignored blocks are shrunk
2267           with realloc.
2268
2269           The rules for writing C++ function names are the same as for
2270           --alloc-fn above.
2271
2272       --threshold=<m.n> [default: 1.0]
2273           The significance threshold for heap allocations, as a percentage of
2274           total memory size. Allocation tree entries that account for less
2275           than this will be aggregated. Note that this should be specified in
2276           tandem with ms_print's option of the same name.
2277
2278       --peak-inaccuracy=<m.n> [default: 1.0]
2279           Massif does not necessarily record the actual global memory
2280           allocation peak; by default it records a peak only when the global
2281           memory allocation size exceeds the previous peak by at least 1.0%.
2282           This is because there can be many local allocation peaks along the
2283           way, and doing a detailed snapshot for every one would be expensive
2284           and wasteful, as all but one of them will be later discarded. This
2285           inaccuracy can be changed (even to 0.0%) via this option, but
2286           Massif will run drastically slower as the number approaches zero.
2287
2288       --time-unit=<i|ms|B> [default: i]
2289           The time unit used for the profiling. There are three
2290           possibilities: instructions executed (i), which is good for most
2291           cases; real (wallclock) time (ms, i.e. milliseconds), which is
2292           sometimes useful; and bytes allocated/deallocated on the heap
2293           and/or stack (B), which is useful for very short-run programs, and
2294           for testing purposes, because it is the most reproducible across
2295           different machines.
2296
2297       --detailed-freq=<n> [default: 10]
2298           Frequency of detailed snapshots. With --detailed-freq=1, every
2299           snapshot is detailed.
2300
2301       --max-snapshots=<n> [default: 100]
2302           The maximum number of snapshots recorded. If set to N, for all
2303           programs except very short-running ones, the final number of
2304           snapshots will be between N/2 and N.
2305
2306       --massif-out-file=<file> [default: massif.out.%p]
2307           Write the profile data to file rather than to the default output
2308           file, massif.out.<pid>. The %p and %q format specifiers can be used
2309           to embed the process ID and/or the contents of an environment
2310           variable in the name, as is the case for the core option
2311           --log-file.
2312

BBV OPTIONS

2314       --bb-out-file=<name> [default: bb.out.%p]
2315           This option selects the name of the basic block vector file. The %p
2316           and %q format specifiers can be used to embed the process ID and/or
2317           the contents of an environment variable in the name, as is the case
2318           for the core option --log-file.
2319
2320       --pc-out-file=<name> [default: pc.out.%p]
2321           This option selects the name of the PC file. This file holds
2322           program counter addresses and function name info for the various
2323           basic blocks. This can be used in conjunction with the basic block
2324           vector file to fast-forward via function names instead of just
2325           instruction counts. The %p and %q format specifiers can be used to
2326           embed the process ID and/or the contents of an environment variable
2327           in the name, as is the case for the core option --log-file.
2328
2329       --interval-size=<number> [default: 100000000]
2330           This option selects the size of the interval to use. The default is
2331           100 million instructions, which is a commonly used value. Other
2332           sizes can be used; smaller intervals can help programs with
2333           finer-grained phases. However smaller interval size can lead to
2334           accuracy issues due to warm-up effects (When fast-forwarding the
2335           various architectural features will be un-initialized, and it will
2336           take some number of instructions before they "warm up" to the state
2337           a full simulation would be at without the fast-forwarding. Large
2338           interval sizes tend to mitigate this.)
2339
2340       --instr-count-only [default: no]
2341           This option tells the tool to only display instruction count
2342           totals, and to not generate the actual basic block vector file.
2343           This is useful for debugging, and for gathering instruction count
2344           info without generating the large basic block vector files.
2345

LACKEY OPTIONS

2347       --basic-counts=<no|yes> [default: yes]
2348           When enabled, Lackey prints the following statistics and
2349           information about the execution of the client program:
2350
2351            1. The number of calls to the function specified by the --fnname
2352               option (the default is main). If the program has had its
2353               symbols stripped, the count will always be zero.
2354
2355            2. The number of conditional branches encountered and the number
2356               and proportion of those taken.
2357
2358            3. The number of superblocks entered and completed by the program.
2359               Note that due to optimisations done by the JIT, this is not at
2360               all an accurate value.
2361
2362            4. The number of guest (x86, amd64, ppc, etc.) instructions and IR
2363               statements executed. IR is Valgrind's RISC-like intermediate
2364               representation via which all instrumentation is done.
2365
2366            5. Ratios between some of these counts.
2367
2368            6. The exit code of the client program.
2369
2370       --detailed-counts=<no|yes> [default: no]
2371           When enabled, Lackey prints a table containing counts of loads,
2372           stores and ALU operations, differentiated by their IR types. The IR
2373           types are identified by their IR name ("I1", "I8", ... "I128",
2374           "F32", "F64", and "V128").
2375
2376       --trace-mem=<no|yes> [default: no]
2377           When enabled, Lackey prints the size and address of almost every
2378           memory access made by the program. See the comments at the top of
2379           the file lackey/lk_main.c for details about the output format, how
2380           it works, and inaccuracies in the address trace. Note that this
2381           option produces immense amounts of output.
2382
2383       --trace-superblocks=<no|yes> [default: no]
2384           When enabled, Lackey prints out the address of every superblock (a
2385           single entry, multiple exit, linear chunk of code) executed by the
2386           program. This is primarily of interest to Valgrind developers. See
2387           the comments at the top of the file lackey/lk_main.c for details
2388           about the output format. Note that this option produces large
2389           amounts of output.
2390
2391       --fnname=<name> [default: main]
2392           Changes the function for which calls are counted when
2393           --basic-counts=yes is specified.
2394

DEBUGINFOD

2396       Valgrind supports the downloading of debuginfo files via debuginfod, an
2397       HTTP server for distributing ELF/DWARF debugging information. When a
2398       debuginfo file cannot be found locally, Valgrind is able to query
2399       debuginfod servers for the file using its build-id.
2400
2401       In order to use this feature debuginfod-find must be installed and
2402       $DEBUGINFOD_URLS must contain URLs of debuginfod servers. Valgrind does
2403       not support debuginfod-find verbose output that is normally enabled
2404       with $DEBUGINFOD_PROGRESS and $DEBUGINFOD_VERBOSE. These environment
2405       variables will be ignored.
2406
2407       For more information regarding debuginfod, see
2408       https://sourceware.org/elfutils/Debuginfod.html
2409

SEE ALSO

2411       cg_annotate(1), callgrind_annotate(1), callgrind_control(1),
2412       ms_print(1), $INSTALL/share/doc/valgrind/html/index.html or
2413       http://www.valgrind.org/docs/manual/index.html, Debugging your program
2414       using Valgrind's gdbserver and GDB[1] vgdb[2], Valgrind monitor
2415       commands[3], The Commentary[4], Scheduling and Multi-Thread
2416       Performance[5], Cachegrind: a cache and branch-prediction profiler[6].
2417       Execution Trees[7]
2418

AUTHOR

2420       See the AUTHORS file in the valgrind distribution for a comprehensive
2421       list of authors.
2422
2423       This manpage was written by Andres Roldan <aroldan@debian.org> and the
2424       Valgrind developers.
2425

NOTES

2427        1. Debugging your program using Valgrind's gdbserver and GDB
2428           http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.gdbserver
2429
2430        2. vgdb
2431           http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.vgdb
2432
2433        3. Valgrind monitor commands
2434           http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.valgrind-monitor-commands
2435
2436        4. The Commentary
2437           http://www.valgrind.org/docs/manual/manual-core.html#manual-core.comment
2438
2439        5. Scheduling and Multi-Thread Performance
2440           http://www.valgrind.org/docs/manual/manual-core.html#manual-core.pthreads_perf_sched
2441
2442        6. Cachegrind: a cache and branch-prediction profiler
2443           http://www.valgrind.org/docs/manual/cg-manual.html
2444
2445        7. Execution Trees
2446           http://www.valgrind.org/docs/manual/manual-core.html#manual-core.xtree
2447
2448
2449
2450Release 3.18.0                    10/15/2021                       VALGRIND(1)
Impressum