valgrind

VALGRIND(1)                        valgrind                        VALGRIND(1)



NAME
       valgrind - a suite of tools for debugging and profiling programs


SYNOPSIS


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





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


       Some of the options described below work with all Valgrind tools, and
       some only work with a few or one. The section MEMCHECK OPTIONS and
       those below it describe tool-specific options.


       This manual page covers only basic usage and options. For more
       comprehensive information, please see the HTML documentation on your
       system: $INSTALL/share/doc/valgrind/html/index.html, or online:
       http://www.valgrind.org/docs/manual/index.html.






TOOL SELECTION OPTIONS
       The single most important option.





         .PP --tool=<toolname> [default: memcheck]



                 Run the Valgrind tool called toolname, e.g. memcheck,
           cachegrind, callgrind, helgrind, drd, massif, dhat, lackey, none,
           exp-bbv, etc.


             .RE







BASIC OPTIONS
       These options work with all tools.





         .PP -h --help



                 Show help for all options, both for the core and for the
           selected tool. If the option is repeated it is equivalent to giving
           --help-debug.


             .RE

             .PP --help-debug



                     Same as --help, but also lists debugging options which
               usually are only of use to Valgrind's developers.


                 .RE

                 .PP --version



                         Show the version number of the Valgrind core. Tools
                   can have their own version numbers. There is a scheme in
                   place to ensure that tools only execute when the core
                   version is one they are known to work with. This was done
                   to minimise the chances of strange problems arising from
                   tool-vs-core version incompatibilities.


                     .RE

                     .PP -q, --quiet



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


                         .RE

                         .PP -v, --verbose



                                 Be more verbose. Gives extra information on
                           various aspects of your program, such as: the
                           shared objects loaded, the suppressions used, the
                           progress of the instrumentation and execution
                           engines, and warnings about unusual behaviour.
                           Repeating the option increases the verbosity level.


                             .RE

                             .PP --trace-children=<yes|no> [default: no]



                                     When enabled, Valgrind will trace into
                               sub-processes initiated via the exec system
                               call. This is necessary for multi-process
                               programs.


                                     Note that Valgrind does trace into the
                               child of a fork (it would be difficult not to,
                               since fork makes an identical copy of a
                               process), so this option is arguably badly
                               named. However, most children of fork calls
                               immediately call exec anyway.


                                 .RE

                                 .PP --trace-children-skip=patt1,patt2,...



                                         This option only has an effect when
                                   --trace-children=yes is specified. It
                                   allows for some children to be skipped. The
                                   option takes a comma separated list of
                                   patterns for the names of child executables
                                   that Valgrind should not trace into.
                                   Patterns may include the metacharacters ?
                                   and *, which have the usual meaning.


                                         This can be useful for pruning
                                   uninteresting branches from a tree of
                                   processes being run on Valgrind. But you
                                   should be careful when using it. When
                                   Valgrind skips tracing into an executable,
                                   it doesn't just skip tracing that
                                   executable, it also skips tracing any of
                                   that executable's child processes. In other
                                   words, the flag doesn't merely cause
                                   tracing to stop at the specified
                                   executables -- it skips tracing of entire
                                   process subtrees rooted at any of the
                                   specified executables.


                                     .RE

                                     .PP
                                   --trace-children-skip-by-arg=patt1,patt2,...



                                             This is the same as
                                       --trace-children-skip, with one
                                       difference: the decision as to whether
                                       to trace into a child process is made
                                       by examining the arguments to the child
                                       process, rather than the name of its
                                       executable.


                                         .RE

                                         .PP
                                       --child-silent-after-fork=<yes|no>
                                       [default: no]



                                                 When enabled, Valgrind will
                                           not show any debugging or logging
                                           output for the child process
                                           resulting from a fork call. This
                                           can make the output less confusing
                                           (although more misleading) when
                                           dealing with processes that create
                                           children. It is particularly useful
                                           in conjunction with
                                           --trace-children=. Use of this
                                           option is also strongly recommended
                                           if you are requesting XML output
                                           (--xml=yes), since otherwise the
                                           XML from child and parent may
                                           become mixed up, which usually
                                           makes it useless.


                                             .RE

                                             .PP --vgdb=<no|yes|full>
                                           [default: yes]




                                                     Valgrind will provide
                                               "gdbserver" functionality when
                                               --vgdb=yes or --vgdb=full is
                                               specified. This allows an
                                               external GNU GDB debugger to
                                               control and debug your program
                                               when it runs on Valgrind.
                                               --vgdb=full incurs significant
                                               performance overheads, but
                                               provides more precise
                                               breakpoints and watchpoints.
                                               See Debugging your program
                                               using Valgrind's gdbserver and
                                               GDB for a detailed description.



                                                     If the embedded gdbserver
                                               is enabled but no gdb is
                                               currently being used, the vgdb
                                               command line utility can send
                                               "monitor commands" to Valgrind
                                               from a shell. The Valgrind core
                                               provides a set of Valgrind
                                               monitor commands. A tool can
                                               optionally provide tool
                                               specific monitor commands,
                                               which are documented in the
                                               tool specific chapter.



                                                 .RE

                                                 .PP --vgdb-error=<number>
                                               [default: 999999999]



                                                         Use this option when
                                                   the Valgrind gdbserver is
                                                   enabled with --vgdb=yes or
                                                   --vgdb=full. Tools that
                                                   report errors will wait for
                                                   "number" errors to be
                                                   reported before freezing
                                                   the program and waiting for
                                                   you to connect with GDB. It
                                                   follows that a value of
                                                   zero will cause the
                                                   gdbserver to be started
                                                   before your program is
                                                   executed. This is typically
                                                   used to insert GDB
                                                   breakpoints before
                                                   execution, and also works
                                                   with tools that do not
                                                   report errors, such as
                                                   Massif.


                                                     .RE

                                                     .PP --vgdb-stop-at=<set>
                                                   [default: none]



                                                             Use this option
                                                       when the Valgrind
                                                       gdbserver is enabled
                                                       with --vgdb=yes or
                                                       --vgdb=full. The
                                                       Valgrind gdbserver will
                                                       be invoked for each
                                                       error after
                                                       --vgdb-error have been
                                                       reported. You can
                                                       additionally ask the
                                                       Valgrind gdbserver to
                                                       be invoked for other
                                                       events, specified in
                                                       one of the following
                                                       ways:




                                                       •   a comma separated
                                                           list of one or more
                                                           of startup exit
                                                           valgrindabexit.



                                                                     The
                                                           values startup exit
                                                           valgrindabexit
                                                           respectively
                                                           indicate to invoke
                                                           gdbserver before
                                                           your program is
                                                           executed, after the
                                                           last instruction of
                                                           your program, on
                                                           Valgrind abnormal
                                                           exit (e.g. internal
                                                           error, out of
                                                           memory, ...).



                                                                     Note:
                                                           startup and
                                                           --vgdb-error=0 will
                                                           both cause Valgrind
                                                           gdbserver to be
                                                           invoked before your
                                                           program is
                                                           executed. The
                                                           --vgdb-error=0 will
                                                           in addition cause
                                                           your program to
                                                           stop on all
                                                           subsequent errors.


                                                                   .RE



                                                           •   all to specify
                                                               the complete
                                                               set. It is
                                                               equivalent to
                                                               --vgdb-stop-at=startup,exit,valgrindabexit.

                                                                       .RE



                                                               •   none for
                                                                   the empty
                                                                   set.

                                                                           .RE
                                                                         .sp


                                                                     .RE

                                                                     .PP
                                                                   --track-fds=<yes|no>
                                                                   [default:
                                                                   no]



                                                                             When
                                                                       enabled,
                                                                       Valgrind
                                                                       will
                                                                       print
                                                                       out a
                                                                       list of
                                                                       open
                                                                       file
                                                                       descriptors
                                                                       on exit
                                                                       or on
                                                                       request,
                                                                       via the
                                                                       gdbserver
                                                                       monitor
                                                                       command
                                                                       v.info
                                                                       open_fds.
                                                                       Along
                                                                       with
                                                                       each
                                                                       file
                                                                       descriptor
                                                                       is
                                                                       printed
                                                                       a stack
                                                                       backtrace
                                                                       of
                                                                       where
                                                                       the
                                                                       file
                                                                       was
                                                                       opened
                                                                       and any
                                                                       details
                                                                       relating
                                                                       to the
                                                                       file
                                                                       descriptor
                                                                       such as
                                                                       the
                                                                       file
                                                                       name or
                                                                       socket
                                                                       details.


                                                                         .RE

                                                                         .PP
                                                                       --time-stamp=<yes|no>
                                                                       [default:
                                                                       no]



                                                                                 When
                                                                           enabled,
                                                                           each
                                                                           message
                                                                           is
                                                                           preceded
                                                                           with
                                                                           an
                                                                           indication
                                                                           of
                                                                           the
                                                                           elapsed
                                                                           wallclock
                                                                           time
                                                                           since
                                                                           startup,
                                                                           expressed
                                                                           as
                                                                           days,
                                                                           hours,
                                                                           minutes,
                                                                           seconds
                                                                           and
                                                                           milliseconds.


                                                                             .RE

                                                                             .PP
                                                                           --log-fd=<number>
                                                                           [default:
                                                                           2,
                                                                           stderr]



                                                                                     Specifies
                                                                               that
                                                                               Valgrind
                                                                               should
                                                                               send
                                                                               all
                                                                               of
                                                                               its
                                                                               messages
                                                                               to
                                                                               the
                                                                               specified
                                                                               file
                                                                               descriptor.
                                                                               The
                                                                               default,
                                                                               2,
                                                                               is
                                                                               the
                                                                               standard
                                                                               error
                                                                               channel
                                                                               (stderr).
                                                                               Note
                                                                               that
                                                                               this
                                                                               may
                                                                               interfere
                                                                               with
                                                                               the
                                                                               client's
                                                                               own
                                                                               use
                                                                               of
                                                                               stderr,
                                                                               as
                                                                               Valgrind's
                                                                               output
                                                                               will
                                                                               be
                                                                               interleaved
                                                                               with
                                                                               any
                                                                               output
                                                                               that
                                                                               the
                                                                               client
                                                                               sends
                                                                               to
                                                                               stderr.


                                                                                 .RE

                                                                                 .PP
                                                                               --log-file=<filename>



                                                                                         Specifies
                                                                                   that
                                                                                   Valgrind
                                                                                   should
                                                                                   send
                                                                                   all
                                                                                   of
                                                                                   its
                                                                                   messages
                                                                                   to
                                                                                   the
                                                                                   specified
                                                                                   file.
                                                                                   If
                                                                                   the
                                                                                   file
                                                                                   name
                                                                                   is
                                                                                   empty,
                                                                                   it
                                                                                   causes
                                                                                   an
                                                                                   abort.
                                                                                   There
                                                                                   are
                                                                                   three
                                                                                   special
                                                                                   format
                                                                                   specifiers
                                                                                   that
                                                                                   can
                                                                                   be
                                                                                   used
                                                                                   in
                                                                                   the
                                                                                   file
                                                                                   name.



                                                                                         %p
                                                                                   is
                                                                                   replaced
                                                                                   with
                                                                                   the
                                                                                   current
                                                                                   process
                                                                                   ID.
                                                                                   This
                                                                                   is
                                                                                   very
                                                                                   useful
                                                                                   for
                                                                                   program
                                                                                   that
                                                                                   invoke
                                                                                   multiple
                                                                                   processes.
                                                                                   WARNING:
                                                                                   If
                                                                                   you
                                                                                   use
                                                                                   --trace-children=yes
                                                                                   and
                                                                                   your
                                                                                   program
                                                                                   invokes
                                                                                   multiple
                                                                                   processes
                                                                                   OR
                                                                                   your
                                                                                   program
                                                                                   forks
                                                                                   without
                                                                                   calling
                                                                                   exec
                                                                                   afterwards,
                                                                                   and
                                                                                   you
                                                                                   don't
                                                                                   use
                                                                                   this
                                                                                   specifier
                                                                                   (or
                                                                                   the
                                                                                   %q
                                                                                   specifier
                                                                                   below),
                                                                                   the
                                                                                   Valgrind
                                                                                   output
                                                                                   from
                                                                                   all
                                                                                   those
                                                                                   processes
                                                                                   will
                                                                                   go
                                                                                   into
                                                                                   one
                                                                                   file,
                                                                                   possibly
                                                                                   jumbled
                                                                                   up,
                                                                                   and
                                                                                   possibly
                                                                                   incomplete.
                                                                                   Note:
                                                                                   If
                                                                                   the
                                                                                   program
                                                                                   forks
                                                                                   and
                                                                                   calls
                                                                                   exec
                                                                                   afterwards,
                                                                                   Valgrind
                                                                                   output
                                                                                   of
                                                                                   the
                                                                                   child
                                                                                   from
                                                                                   the
                                                                                   period
                                                                                   between
                                                                                   fork
                                                                                   and
                                                                                   exec
                                                                                   will
                                                                                   be
                                                                                   lost.
                                                                                   Fortunately
                                                                                   this
                                                                                   gap
                                                                                   is
                                                                                   really
                                                                                   tiny
                                                                                   for
                                                                                   most
                                                                                   programs;
                                                                                   and
                                                                                   modern
                                                                                   programs
                                                                                   use
                                                                                   posix_spawn
                                                                                   anyway.



                                                                                         %n
                                                                                   is
                                                                                   replaced
                                                                                   with
                                                                                   a
                                                                                   file
                                                                                   sequence
                                                                                   number
                                                                                   unique
                                                                                   for
                                                                                   this
                                                                                   process.
                                                                                   This
                                                                                   is
                                                                                   useful
                                                                                   for
                                                                                   processes
                                                                                   that
                                                                                   produces
                                                                                   several
                                                                                   files
                                                                                   from
                                                                                   the
                                                                                   same
                                                                                   filename
                                                                                   template.




                                                                                         %q{FOO}
                                                                                   is
                                                                                   replaced
                                                                                   with
                                                                                   the
                                                                                   contents
                                                                                   of
                                                                                   the
                                                                                   environment
                                                                                   variable
                                                                                   FOO.
                                                                                   If
                                                                                   the
                                                                                   {FOO}
                                                                                   part
                                                                                   is
                                                                                   malformed,
                                                                                   it
                                                                                   causes
                                                                                   an
                                                                                   abort.
                                                                                   This
                                                                                   specifier
                                                                                   is
                                                                                   rarely
                                                                                   needed,
                                                                                   but
                                                                                   very
                                                                                   useful
                                                                                   in
                                                                                   certain
                                                                                   circumstances
                                                                                   (eg.
                                                                                   when
                                                                                   running
                                                                                   MPI
                                                                                   programs).
                                                                                   The
                                                                                   idea
                                                                                   is
                                                                                   that
                                                                                   you
                                                                                   specify
                                                                                   a
                                                                                   variable
                                                                                   which
                                                                                   will
                                                                                   be
                                                                                   set
                                                                                   differently
                                                                                   for
                                                                                   each
                                                                                   process
                                                                                   in
                                                                                   the
                                                                                   job,
                                                                                   for
                                                                                   example
                                                                                   BPROC_RANK
                                                                                   or
                                                                                   whatever
                                                                                   is
                                                                                   applicable
                                                                                   in
                                                                                   your
                                                                                   MPI
                                                                                   setup.
                                                                                   If
                                                                                   the
                                                                                   named
                                                                                   environment
                                                                                   variable
                                                                                   is
                                                                                   not
                                                                                   set,
                                                                                   it
                                                                                   causes
                                                                                   an
                                                                                   abort.
                                                                                   Note
                                                                                   that
                                                                                   in
                                                                                   some
                                                                                   shells,
                                                                                   the
                                                                                   {
                                                                                   and
                                                                                   }
                                                                                   characters
                                                                                   may
                                                                                   need
                                                                                   to
                                                                                   be
                                                                                   escaped
                                                                                   with
                                                                                   a
                                                                                   backslash.



                                                                                         %%
                                                                                   is
                                                                                   replaced
                                                                                   with
                                                                                   %.



                                                                                         If
                                                                                   an
                                                                                   %
                                                                                   is
                                                                                   followed
                                                                                   by
                                                                                   any
                                                                                   other
                                                                                   character,
                                                                                   it
                                                                                   causes
                                                                                   an
                                                                                   abort.



                                                                                         If
                                                                                   the
                                                                                   file
                                                                                   name
                                                                                   specifies
                                                                                   a
                                                                                   relative
                                                                                   file
                                                                                   name,
                                                                                   it
                                                                                   is
                                                                                   put
                                                                                   in
                                                                                   the
                                                                                   program's
                                                                                   initial
                                                                                   working
                                                                                   directory:
                                                                                   this
                                                                                   is
                                                                                   the
                                                                                   current
                                                                                   directory
                                                                                   when
                                                                                   the
                                                                                   program
                                                                                   started
                                                                                   its
                                                                                   execution
                                                                                   after
                                                                                   the
                                                                                   fork
                                                                                   or
                                                                                   after
                                                                                   the
                                                                                   exec.
                                                                                   If
                                                                                   it
                                                                                   specifies
                                                                                   an
                                                                                   absolute
                                                                                   file
                                                                                   name
                                                                                   (ie.
                                                                                   starts
                                                                                   with
                                                                                   '/')
                                                                                   then
                                                                                   it
                                                                                   is
                                                                                   put
                                                                                   there.


                                                                                     .RE

                                                                                     .PP
                                                                                   --log-socket=<ip-address:port-number>



                                                                                             Specifies
                                                                                       that
                                                                                       Valgrind
                                                                                       should
                                                                                       send
                                                                                       all
                                                                                       of
                                                                                       its
                                                                                       messages
                                                                                       to
                                                                                       the
                                                                                       specified
                                                                                       port
                                                                                       at
                                                                                       the
                                                                                       specified
                                                                                       IP
                                                                                       address.
                                                                                       The
                                                                                       port
                                                                                       may
                                                                                       be
                                                                                       omitted,
                                                                                       in
                                                                                       which
                                                                                       case
                                                                                       port
                                                                                       1500
                                                                                       is
                                                                                       used.
                                                                                       If
                                                                                       a
                                                                                       connection
                                                                                       cannot
                                                                                       be
                                                                                       made
                                                                                       to
                                                                                       the
                                                                                       specified
                                                                                       socket,
                                                                                       Valgrind
                                                                                       falls
                                                                                       back
                                                                                       to
                                                                                       writing
                                                                                       output
                                                                                       to
                                                                                       the
                                                                                       standard
                                                                                       error
                                                                                       (stderr).
                                                                                       This
                                                                                       option
                                                                                       is
                                                                                       intended
                                                                                       to
                                                                                       be
                                                                                       used
                                                                                       in
                                                                                       conjunction
                                                                                       with
                                                                                       the
                                                                                       valgrind-listener
                                                                                       program.
                                                                                       For
                                                                                       further
                                                                                       details,
                                                                                       see
                                                                                       the
                                                                                       commentary
                                                                                       in
                                                                                       the
                                                                                       manual.


                                                                                         .RE







ERROR-RELATED OPTIONS
       These options are used by all tools that can report errors, e.g.
       Memcheck, but not Cachegrind.





         .PP --xml=<yes|no> [default: no]



                 When enabled, the important parts of the output (e.g. tool
           error messages) will be in XML format rather than plain text.
           Furthermore, the XML output will be sent to a different output
           channel than the plain text output. Therefore, you also must use
           one of --xml-fd, --xml-file or --xml-socket to specify where the
           XML is to be sent.



                 Less important messages will still be printed in plain text,
           but because the XML output and plain text output are sent to
           different output channels (the destination of the plain text output
           is still controlled by --log-fd, --log-file and --log-socket) this
           should not cause problems.



                 This option is aimed at making life easier for tools that
           consume Valgrind's output as input, such as GUI front ends.
           Currently this option works with Memcheck, Helgrind and DRD. The
           output format is specified in the file
           docs/internals/xml-output-protocol4.txt in the source tree for
           Valgrind 3.5.0 or later.



                 The recommended options for a GUI to pass, when requesting
           XML output, are: --xml=yes to enable XML output, --xml-file to send
           the XML output to a (presumably GUI-selected) file, --log-file to
           send the plain text output to a second GUI-selected file,
           --child-silent-after-fork=yes, and -q to restrict the plain text
           output to critical error messages created by Valgrind itself. For
           example, failure to read a specified suppressions file counts as a
           critical error message. In this way, for a successful run the text
           output file will be empty. But if it isn't empty, then it will
           contain important information which the GUI user should be made
           aware of.


             .RE

             .PP --xml-fd=<number> [default: -1, disabled]



                     Specifies that Valgrind should send its XML output to the
               specified file descriptor. It must be used in conjunction with
               --xml=yes.


                 .RE

                 .PP --xml-file=<filename>



                         Specifies that Valgrind should send its XML output to
                   the specified file. It must be used in conjunction with
                   --xml=yes. Any %p or %q sequences appearing in the filename
                   are expanded in exactly the same way as they are for
                   --log-file. See the description of --log-file for details.


                     .RE

                     .PP --xml-socket=<ip-address:port-number>



                             Specifies that Valgrind should send its XML
                       output the specified port at the specified IP address.
                       It must be used in conjunction with --xml=yes. The form
                       of the argument is the same as that used by
                       --log-socket. See the description of --log-socket for
                       further details.


                         .RE

                         .PP --xml-user-comment=<string>



                                 Embeds an extra user comment string at the
                           start of the XML output. Only works when --xml=yes
                           is specified; ignored otherwise.


                             .RE

                             .PP --demangle=<yes|no> [default: yes]



                                     Enable/disable automatic demangling
                               (decoding) of C++ names. Enabled by default.
                               When enabled, Valgrind will attempt to
                               translate encoded C++ names back to something
                               approaching the original. The demangler handles
                               symbols mangled by g++ versions 2.X, 3.X and
                               4.X.



                                     An important fact about demangling is
                               that function names mentioned in suppressions
                               files should be in their mangled form. Valgrind
                               does not demangle function names when searching
                               for applicable suppressions, because to do
                               otherwise would make suppression file contents
                               dependent on the state of Valgrind's demangling
                               machinery, and also slow down suppression
                               matching.


                                 .RE

                                 .PP --num-callers=<number> [default: 12]



                                         Specifies the maximum number of
                                   entries shown in stack traces that identify
                                   program locations. Note that errors are
                                   commoned up using only the top four
                                   function locations (the place in the
                                   current function, and that of its three
                                   immediate callers). So this doesn't affect
                                   the total number of errors reported.



                                         The maximum value for this is 500.
                                   Note that higher settings will make
                                   Valgrind run a bit more slowly and take a
                                   bit more memory, but can be useful when
                                   working with programs with deeply-nested
                                   call chains.


                                     .RE

                                     .PP --unw-stack-scan-thresh=<number>
                                   [default: 0] ,
                                   --unw-stack-scan-frames=<number> [default:
                                   5]




                                             Stack-scanning support is
                                       available only on ARM targets.



                                             These flags enable and control
                                       stack unwinding by stack scanning. When
                                       the normal stack unwinding mechanisms
                                       -- usage of Dwarf CFI records, and
                                       frame-pointer following -- fail, stack
                                       scanning may be able to recover a stack
                                       trace.



                                             Note that stack scanning is an
                                       imprecise, heuristic mechanism that may
                                       give very misleading results, or none
                                       at all. It should be used only in
                                       emergencies, when normal unwinding
                                       fails, and it is important to
                                       nevertheless have stack traces.



                                             Stack scanning is a simple
                                       technique: the unwinder reads words
                                       from the stack, and tries to guess
                                       which of them might be return
                                       addresses, by checking to see if they
                                       point just after ARM or Thumb call
                                       instructions. If so, the word is added
                                       to the backtrace.



                                             The main danger occurs when a
                                       function call returns, leaving its
                                       return address exposed, and a new
                                       function is called, but the new
                                       function does not overwrite the old
                                       address. The result of this is that the
                                       backtrace may contain entries for
                                       functions which have already returned,
                                       and so be very confusing.



                                             A second limitation of this
                                       implementation is that it will scan
                                       only the page (4KB, normally)
                                       containing the starting stack pointer.
                                       If the stack frames are large, this may
                                       result in only a few (or not even any)
                                       being present in the trace. Also, if
                                       you are unlucky and have an initial
                                       stack pointer near the end of its
                                       containing page, the scan may miss all
                                       interesting frames.



                                             By default stack scanning is
                                       disabled. The normal use case is to ask
                                       for it when a stack trace would
                                       otherwise be very short. So, to enable
                                       it, use --unw-stack-scan-thresh=number.
                                       This requests Valgrind to try using
                                       stack scanning to "extend" stack traces
                                       which contain fewer than number frames.



                                             If stack scanning does take
                                       place, it will only generate at most
                                       the number of frames specified by
                                       --unw-stack-scan-frames. Typically,
                                       stack scanning generates so many
                                       garbage entries that this value is set
                                       to a low value (5) by default. In no
                                       case will a stack trace larger than the
                                       value specified by --num-callers be
                                       created.


                                         .RE

                                         .PP --error-limit=<yes|no> [default:
                                       yes]



                                                 When enabled, Valgrind stops
                                           reporting errors after 10,000,000
                                           in total, or 1,000 different ones,
                                           have been seen. This is to stop the
                                           error tracking machinery from
                                           becoming a huge performance
                                           overhead in programs with many
                                           errors.


                                             .RE

                                             .PP --error-exitcode=<number>
                                           [default: 0]



                                                     Specifies an alternative
                                               exit code to return if Valgrind
                                               reported any errors in the run.
                                               When set to the default value
                                               (zero), the return value from
                                               Valgrind will always be the
                                               return value of the process
                                               being simulated. When set to a
                                               nonzero value, that value is
                                               returned instead, if Valgrind
                                               detects any errors. This is
                                               useful for using Valgrind as
                                               part of an automated test
                                               suite, since it makes it easy
                                               to detect test cases for which
                                               Valgrind has reported errors,
                                               just by inspecting return
                                               codes.


                                                 .RE

                                                 .PP
                                               --exit-on-first-error=<yes|no>
                                               [default: no]



                                                         If this option is
                                                   enabled, Valgrind exits on
                                                   the first error. A nonzero
                                                   exit value must be defined
                                                   using --error-exitcode
                                                   option. Useful if you are
                                                   running regression tests or
                                                   have some other automated
                                                   test machinery.


                                                     .RE

                                                     .PP
                                                   --error-markers=<begin>,<end>
                                                   [default: none]



                                                             When errors are
                                                       output as plain text
                                                       (i.e. XML not used),
                                                       --error-markers
                                                       instructs to output a
                                                       line containing the
                                                       begin (end) string
                                                       before (after) each
                                                       error.


                                                             Such marker lines
                                                       facilitate searching
                                                       for errors and/or
                                                       extracting errors in an
                                                       output file that
                                                       contain valgrind errors
                                                       mixed with the program
                                                       output.


                                                             Note that empty
                                                       markers are accepted.
                                                       So, only using a begin
                                                       (or an end) marker is
                                                       possible.


                                                         .RE

                                                         .PP
                                                       --show-error-list=no|yes
                                                       [default: no]



                                                                 If this
                                                           option is enabled,
                                                           for tools that
                                                           report errors,
                                                           valgrind will show
                                                           the list of
                                                           detected errors and
                                                           the list of used
                                                           suppressions at
                                                           exit.


                                                                 Note that at
                                                           verbosity 2 and
                                                           above, valgrind
                                                           automatically shows
                                                           the list of
                                                           detected errors and
                                                           the list of used
                                                           suppressions at
                                                           exit, unless
                                                           --show-error-list=no
                                                           is selected.


                                                             .RE

                                                               .PP -s



                                                                     Specifying
                                                               -s is
                                                               equivalent to
                                                               --show-error-list=yes.


                                                                 .RE


                                                                 .PP
                                                               --sigill-diagnostics=<yes|no>
                                                               [default: yes]



                                                                         Enable/disable
                                                                   printing of
                                                                   illegal
                                                                   instruction
                                                                   diagnostics.
                                                                   Enabled by
                                                                   default,
                                                                   but
                                                                   defaults to
                                                                   disabled
                                                                   when
                                                                   --quiet is
                                                                   given. The
                                                                   default can
                                                                   always be
                                                                   explicitly
                                                                   overridden
                                                                   by giving
                                                                   this
                                                                   option.



                                                                         When
                                                                   enabled, a
                                                                   warning
                                                                   message
                                                                   will be
                                                                   printed,
                                                                   along with
                                                                   some
                                                                   diagnostics,
                                                                   whenever an
                                                                   instruction
                                                                   is
                                                                   encountered
                                                                   that
                                                                   Valgrind
                                                                   cannot
                                                                   decode or
                                                                   translate,
                                                                   before the
                                                                   program is
                                                                   given a
                                                                   SIGILL
                                                                   signal.
                                                                   Often an
                                                                   illegal
                                                                   instruction
                                                                   indicates a
                                                                   bug in the
                                                                   program or
                                                                   missing
                                                                   support for
                                                                   the
                                                                   particular
                                                                   instruction
                                                                   in
                                                                   Valgrind.
                                                                   But some
                                                                   programs do
                                                                   deliberately
                                                                   try to
                                                                   execute an
                                                                   instruction
                                                                   that might
                                                                   be missing
                                                                   and trap
                                                                   the SIGILL
                                                                   signal to
                                                                   detect
                                                                   processor
                                                                   features.
                                                                   Using this
                                                                   flag makes
                                                                   it possible
                                                                   to avoid
                                                                   the
                                                                   diagnostic
                                                                   output that
                                                                   you would
                                                                   otherwise
                                                                   get in such
                                                                   cases.


                                                                     .RE

                                                                     .PP
                                                                   --keep-debuginfo=<yes|no>
                                                                   [default:
                                                                   no]



                                                                             When
                                                                       enabled,
                                                                       keep
                                                                       ("archive")
                                                                       symbols
                                                                       and all
                                                                       other
                                                                       debuginfo
                                                                       for
                                                                       unloaded
                                                                       code.
                                                                       This
                                                                       allows
                                                                       saved
                                                                       stack
                                                                       traces
                                                                       to
                                                                       include
                                                                       file/line
                                                                       info
                                                                       for
                                                                       code
                                                                       that
                                                                       has
                                                                       been
                                                                       dlclose'd
                                                                       (or
                                                                       similar).
                                                                       Be
                                                                       careful
                                                                       with
                                                                       this,
                                                                       since
                                                                       it can
                                                                       lead to
                                                                       unbounded
                                                                       memory
                                                                       use for
                                                                       programs
                                                                       which
                                                                       repeatedly
                                                                       load
                                                                       and
                                                                       unload
                                                                       shared
                                                                       objects.


                                                                             Some
                                                                       tools
                                                                       and
                                                                       some
                                                                       functionalities
                                                                       have
                                                                       only
                                                                       limited
                                                                       support
                                                                       for
                                                                       archived
                                                                       debug
                                                                       info.
                                                                       Memcheck
                                                                       fully
                                                                       supports
                                                                       it.
                                                                       Generally,
                                                                       tools
                                                                       that
                                                                       report
                                                                       errors
                                                                       can use
                                                                       archived
                                                                       debug
                                                                       info to
                                                                       show
                                                                       the
                                                                       error
                                                                       stack
                                                                       traces.
                                                                       The
                                                                       known
                                                                       limitations
                                                                       are:
                                                                       Helgrind's
                                                                       past
                                                                       access
                                                                       stack
                                                                       trace
                                                                       of a
                                                                       race
                                                                       condition
                                                                       is does
                                                                       not use
                                                                       archived
                                                                       debug
                                                                       info.
                                                                       Massif
                                                                       (and
                                                                       more
                                                                       generally
                                                                       the
                                                                       xtree
                                                                       Massif
                                                                       output
                                                                       format)
                                                                       does
                                                                       not
                                                                       make
                                                                       use of
                                                                       archived
                                                                       debug
                                                                       info.
                                                                       Only
                                                                       Memcheck
                                                                       has
                                                                       been
                                                                       (somewhat)
                                                                       tested
                                                                       with
                                                                       --keep-debuginfo=yes,
                                                                       so
                                                                       other
                                                                       tools
                                                                       may
                                                                       have
                                                                       unknown
                                                                       limitations.


                                                                         .RE

                                                                         .PP
                                                                       --show-below-main=<yes|no>
                                                                       [default:
                                                                       no]



                                                                                 By
                                                                           default,
                                                                           stack
                                                                           traces
                                                                           for
                                                                           errors
                                                                           do
                                                                           not
                                                                           show
                                                                           any
                                                                           functions
                                                                           that
                                                                           appear
                                                                           beneath
                                                                           main
                                                                           because
                                                                           most
                                                                           of
                                                                           the
                                                                           time
                                                                           it's
                                                                           uninteresting
                                                                           C
                                                                           library
                                                                           stuff
                                                                           and/or
                                                                           gobbledygook.
                                                                           Alternatively,
                                                                           if
                                                                           main
                                                                           is
                                                                           not
                                                                           present
                                                                           in
                                                                           the
                                                                           stack
                                                                           trace,
                                                                           stack
                                                                           traces
                                                                           will
                                                                           not
                                                                           show
                                                                           any
                                                                           functions
                                                                           below
                                                                           main-like
                                                                           functions
                                                                           such
                                                                           as
                                                                           glibc's
                                                                           __libc_start_main.
                                                                           Furthermore,
                                                                           if
                                                                           main-like
                                                                           functions
                                                                           are
                                                                           present
                                                                           in
                                                                           the
                                                                           trace,
                                                                           they
                                                                           are
                                                                           normalised
                                                                           as
                                                                           (below
                                                                           main),
                                                                           in
                                                                           order
                                                                           to
                                                                           make
                                                                           the
                                                                           output
                                                                           more
                                                                           deterministic.



                                                                                 If
                                                                           this
                                                                           option
                                                                           is
                                                                           enabled,
                                                                           all
                                                                           stack
                                                                           trace
                                                                           entries
                                                                           will
                                                                           be
                                                                           shown
                                                                           and
                                                                           main-like
                                                                           functions
                                                                           will
                                                                           not
                                                                           be
                                                                           normalised.


                                                                             .RE

                                                                             .PP
                                                                           --fullpath-after=<string>
                                                                           [default:
                                                                           don't
                                                                           show
                                                                           source
                                                                           paths]



                                                                                     By
                                                                               default
                                                                               Valgrind
                                                                               only
                                                                               shows
                                                                               the
                                                                               filenames
                                                                               in
                                                                               stack
                                                                               traces,
                                                                               but
                                                                               not
                                                                               full
                                                                               paths
                                                                               to
                                                                               source
                                                                               files.
                                                                               When
                                                                               using
                                                                               Valgrind
                                                                               in
                                                                               large
                                                                               projects
                                                                               where
                                                                               the
                                                                               sources
                                                                               reside
                                                                               in
                                                                               multiple
                                                                               different
                                                                               directories,
                                                                               this
                                                                               can
                                                                               be
                                                                               inconvenient.
                                                                               --fullpath-after
                                                                               provides
                                                                               a
                                                                               flexible
                                                                               solution
                                                                               to
                                                                               this
                                                                               problem.
                                                                               When
                                                                               this
                                                                               option
                                                                               is
                                                                               present,
                                                                               the
                                                                               path
                                                                               to
                                                                               each
                                                                               source
                                                                               file
                                                                               is
                                                                               shown,
                                                                               with
                                                                               the
                                                                               following
                                                                               all-important
                                                                               caveat:
                                                                               if
                                                                               string
                                                                               is
                                                                               found
                                                                               in
                                                                               the
                                                                               path,
                                                                               then
                                                                               the
                                                                               path
                                                                               up
                                                                               to
                                                                               and
                                                                               including
                                                                               string
                                                                               is
                                                                               omitted,
                                                                               else
                                                                               the
                                                                               path
                                                                               is
                                                                               shown
                                                                               unmodified.
                                                                               Note
                                                                               that
                                                                               string
                                                                               is
                                                                               not
                                                                               required
                                                                               to
                                                                               be
                                                                               a
                                                                               prefix
                                                                               of
                                                                               the
                                                                               path.



                                                                                     For
                                                                               example,
                                                                               consider
                                                                               a
                                                                               file
                                                                               named
                                                                               /home/janedoe/blah/src/foo/bar/xyzzy.c.
                                                                               Specifying
                                                                               --fullpath-after=/home/janedoe/blah/src/
                                                                               will
                                                                               cause
                                                                               Valgrind
                                                                               to
                                                                               show
                                                                               the
                                                                               name
                                                                               as
                                                                               foo/bar/xyzzy.c.



                                                                                     Because
                                                                               the
                                                                               string
                                                                               is
                                                                               not
                                                                               required
                                                                               to
                                                                               be
                                                                               a
                                                                               prefix,
                                                                               --fullpath-after=src/
                                                                               will
                                                                               produce
                                                                               the
                                                                               same
                                                                               output.
                                                                               This
                                                                               is
                                                                               useful
                                                                               when
                                                                               the
                                                                               path
                                                                               contains
                                                                               arbitrary
                                                                               machine-generated
                                                                               characters.
                                                                               For
                                                                               example,
                                                                               the
                                                                               path
                                                                               /my/build/dir/C32A1B47/blah/src/foo/xyzzy
                                                                               can
                                                                               be
                                                                               pruned
                                                                               to
                                                                               foo/xyzzy
                                                                               using
                                                                               --fullpath-after=/blah/src/.



                                                                                     If
                                                                               you
                                                                               simply
                                                                               want
                                                                               to
                                                                               see
                                                                               the
                                                                               full
                                                                               path,
                                                                               just
                                                                               specify
                                                                               an
                                                                               empty
                                                                               string:
                                                                               --fullpath-after=.
                                                                               This
                                                                               isn't
                                                                               a
                                                                               special
                                                                               case,
                                                                               merely
                                                                               a
                                                                               logical
                                                                               consequence
                                                                               of
                                                                               the
                                                                               above
                                                                               rules.



                                                                                     Finally,
                                                                               you
                                                                               can
                                                                               use
                                                                               --fullpath-after
                                                                               multiple
                                                                               times.
                                                                               Any
                                                                               appearance
                                                                               of
                                                                               it
                                                                               causes
                                                                               Valgrind
                                                                               to
                                                                               switch
                                                                               to
                                                                               producing
                                                                               full
                                                                               paths
                                                                               and
                                                                               applying
                                                                               the
                                                                               above
                                                                               filtering
                                                                               rule.
                                                                               Each
                                                                               produced
                                                                               path
                                                                               is
                                                                               compared
                                                                               against
                                                                               all
                                                                               the
                                                                               --fullpath-after-specified
                                                                               strings,
                                                                               in
                                                                               the
                                                                               order
                                                                               specified.
                                                                               The
                                                                               first
                                                                               string
                                                                               to
                                                                               match
                                                                               causes
                                                                               the
                                                                               path
                                                                               to
                                                                               be
                                                                               truncated
                                                                               as
                                                                               described
                                                                               above.
                                                                               If
                                                                               none
                                                                               match,
                                                                               the
                                                                               full
                                                                               path
                                                                               is
                                                                               shown.
                                                                               This
                                                                               facilitates
                                                                               chopping
                                                                               off
                                                                               prefixes
                                                                               when
                                                                               the
                                                                               sources
                                                                               are
                                                                               drawn
                                                                               from
                                                                               a
                                                                               number
                                                                               of
                                                                               unrelated
                                                                               directories.


                                                                                 .RE

                                                                                 .PP
                                                                               --extra-debuginfo-path=<path>
                                                                               [default:
                                                                               undefined
                                                                               and
                                                                               unused]



                                                                                         By
                                                                                   default
                                                                                   Valgrind
                                                                                   searches
                                                                                   in
                                                                                   several
                                                                                   well-known
                                                                                   paths
                                                                                   for
                                                                                   debug
                                                                                   objects,
                                                                                   such
                                                                                   as
                                                                                   /usr/lib/debug/.



                                                                                         However,
                                                                                   there
                                                                                   may
                                                                                   be
                                                                                   scenarios
                                                                                   where
                                                                                   you
                                                                                   may
                                                                                   wish
                                                                                   to
                                                                                   put
                                                                                   debug
                                                                                   objects
                                                                                   at
                                                                                   an
                                                                                   arbitrary
                                                                                   location,
                                                                                   such
                                                                                   as
                                                                                   external
                                                                                   storage
                                                                                   when
                                                                                   running
                                                                                   Valgrind
                                                                                   on
                                                                                   a
                                                                                   mobile
                                                                                   device
                                                                                   with
                                                                                   limited
                                                                                   local
                                                                                   storage.
                                                                                   Another
                                                                                   example
                                                                                   might
                                                                                   be
                                                                                   a
                                                                                   situation
                                                                                   where
                                                                                   you
                                                                                   do
                                                                                   not
                                                                                   have
                                                                                   permission
                                                                                   to
                                                                                   install
                                                                                   debug
                                                                                   object
                                                                                   packages
                                                                                   on
                                                                                   the
                                                                                   system
                                                                                   where
                                                                                   you
                                                                                   are
                                                                                   running
                                                                                   Valgrind.



                                                                                         In
                                                                                   these
                                                                                   scenarios,
                                                                                   you
                                                                                   may
                                                                                   provide
                                                                                   an
                                                                                   absolute
                                                                                   path
                                                                                   as
                                                                                   an
                                                                                   extra,
                                                                                   final
                                                                                   place
                                                                                   for
                                                                                   Valgrind
                                                                                   to
                                                                                   search
                                                                                   for
                                                                                   debug
                                                                                   objects
                                                                                   by
                                                                                   specifying
                                                                                   --extra-debuginfo-path=/path/to/debug/objects.
                                                                                   The
                                                                                   given
                                                                                   path
                                                                                   will
                                                                                   be
                                                                                   prepended
                                                                                   to
                                                                                   the
                                                                                   absolute
                                                                                   path
                                                                                   name
                                                                                   of
                                                                                   the
                                                                                   searched-for
                                                                                   object.
                                                                                   For
                                                                                   example,
                                                                                   if
                                                                                   Valgrind
                                                                                   is
                                                                                   looking
                                                                                   for
                                                                                   the
                                                                                   debuginfo
                                                                                   for
                                                                                   /w/x/y/zz.so
                                                                                   and
                                                                                   --extra-debuginfo-path=/a/b/c
                                                                                   is
                                                                                   specified,
                                                                                   it
                                                                                   will
                                                                                   look
                                                                                   for
                                                                                   a
                                                                                   debug
                                                                                   object
                                                                                   at
                                                                                   /a/b/c/w/x/y/zz.so.



                                                                                         This
                                                                                   flag
                                                                                   should
                                                                                   only
                                                                                   be
                                                                                   specified
                                                                                   once.
                                                                                   If
                                                                                   it
                                                                                   is
                                                                                   specified
                                                                                   multiple
                                                                                   times,
                                                                                   only
                                                                                   the
                                                                                   last
                                                                                   instance
                                                                                   is
                                                                                   honoured.


                                                                                     .RE

                                                                                     .PP
                                                                                   --debuginfo-server=ipaddr:port
                                                                                   [default:
                                                                                   undefined
                                                                                   and
                                                                                   unused]



                                                                                             This
                                                                                       is
                                                                                       a
                                                                                       new,
                                                                                       experimental,
                                                                                       feature
                                                                                       introduced
                                                                                       in
                                                                                       version
                                                                                       3.9.0.



                                                                                             In
                                                                                       some
                                                                                       scenarios
                                                                                       it
                                                                                       may
                                                                                       be
                                                                                       convenient
                                                                                       to
                                                                                       read
                                                                                       debuginfo
                                                                                       from
                                                                                       objects
                                                                                       stored
                                                                                       on
                                                                                       a
                                                                                       different
                                                                                       machine.
                                                                                       With
                                                                                       this
                                                                                       flag,
                                                                                       Valgrind
                                                                                       will
                                                                                       query
                                                                                       a
                                                                                       debuginfo
                                                                                       server
                                                                                       running
                                                                                       on
                                                                                       ipaddr
                                                                                       and
                                                                                       listening
                                                                                       on
                                                                                       port
                                                                                       port,
                                                                                       if
                                                                                       it
                                                                                       cannot
                                                                                       find
                                                                                       the
                                                                                       debuginfo
                                                                                       object
                                                                                       in
                                                                                       the
                                                                                       local
                                                                                       filesystem.



                                                                                             The
                                                                                       debuginfo
                                                                                       server
                                                                                       must
                                                                                       accept
                                                                                       TCP
                                                                                       connections
                                                                                       on
                                                                                       port
                                                                                       port.
                                                                                       The
                                                                                       debuginfo
                                                                                       server
                                                                                       is
                                                                                       contained
                                                                                       in
                                                                                       the
                                                                                       source
                                                                                       file
                                                                                       auxprogs/valgrind-di-server.c.
                                                                                       It
                                                                                       will
                                                                                       only
                                                                                       serve
                                                                                       from
                                                                                       the
                                                                                       directory
                                                                                       it
                                                                                       is
                                                                                       started
                                                                                       in.
                                                                                       port
                                                                                       defaults
                                                                                       to
                                                                                       1500
                                                                                       in
                                                                                       both
                                                                                       client
                                                                                       and
                                                                                       server
                                                                                       if
                                                                                       not
                                                                                       specified.



                                                                                             If
                                                                                       Valgrind
                                                                                       looks
                                                                                       for
                                                                                       the
                                                                                       debuginfo
                                                                                       for
                                                                                       /w/x/y/zz.so
                                                                                       by
                                                                                       using
                                                                                       the
                                                                                       debuginfo
                                                                                       server,
                                                                                       it
                                                                                       will
                                                                                       strip
                                                                                       the
                                                                                       pathname
                                                                                       components
                                                                                       and
                                                                                       merely
                                                                                       request
                                                                                       zz.so
                                                                                       on
                                                                                       the
                                                                                       server.
                                                                                       That
                                                                                       in
                                                                                       turn
                                                                                       will
                                                                                       look
                                                                                       only
                                                                                       in
                                                                                       its
                                                                                       current
                                                                                       working
                                                                                       directory
                                                                                       for
                                                                                       a
                                                                                       matching
                                                                                       debuginfo
                                                                                       object.



                                                                                             The
                                                                                       debuginfo
                                                                                       data
                                                                                       is
                                                                                       transmitted
                                                                                       in
                                                                                       small
                                                                                       fragments
                                                                                       (8
                                                                                       KB)
                                                                                       as
                                                                                       requested
                                                                                       by
                                                                                       Valgrind.
                                                                                       Each
                                                                                       block
                                                                                       is
                                                                                       compressed
                                                                                       using
                                                                                       LZO
                                                                                       to
                                                                                       reduce
                                                                                       transmission
                                                                                       time.
                                                                                       The
                                                                                       implementation
                                                                                       has
                                                                                       been
                                                                                       tuned
                                                                                       for
                                                                                       best
                                                                                       performance
                                                                                       over
                                                                                       a
                                                                                       single-stage
                                                                                       802.11g
                                                                                       (WiFi)
                                                                                       network
                                                                                       link.



                                                                                             Note
                                                                                       that
                                                                                       checks
                                                                                       for
                                                                                       matching
                                                                                       primary
                                                                                       vs
                                                                                       debug
                                                                                       objects,
                                                                                       using
                                                                                       GNU
                                                                                       debuglink
                                                                                       CRC
                                                                                       scheme,
                                                                                       are
                                                                                       performed
                                                                                       even
                                                                                       when
                                                                                       using
                                                                                       the
                                                                                       debuginfo
                                                                                       server.
                                                                                       To
                                                                                       disable
                                                                                       such
                                                                                       checking,
                                                                                       you
                                                                                       need
                                                                                       to
                                                                                       also
                                                                                       specify
                                                                                       --allow-mismatched-debuginfo=yes.



                                                                                             By
                                                                                       default
                                                                                       the
                                                                                       Valgrind
                                                                                       build
                                                                                       system
                                                                                       will
                                                                                       build
                                                                                       valgrind-di-server
                                                                                       for
                                                                                       the
                                                                                       target
                                                                                       platform,
                                                                                       which
                                                                                       is
                                                                                       almost
                                                                                       certainly
                                                                                       not
                                                                                       what
                                                                                       you
                                                                                       want.
                                                                                       So
                                                                                       far
                                                                                       we
                                                                                       have
                                                                                       been
                                                                                       unable
                                                                                       to
                                                                                       find
                                                                                       out
                                                                                       how
                                                                                       to
                                                                                       get
                                                                                       automake/autoconf
                                                                                       to
                                                                                       build
                                                                                       it
                                                                                       for
                                                                                       the
                                                                                       build
                                                                                       platform.
                                                                                       If
                                                                                       you
                                                                                       want
                                                                                       to
                                                                                       use
                                                                                       it,
                                                                                       you
                                                                                       will
                                                                                       have
                                                                                       to
                                                                                       recompile
                                                                                       it
                                                                                       by
                                                                                       hand
                                                                                       using
                                                                                       the
                                                                                       command
                                                                                       shown
                                                                                       at
                                                                                       the
                                                                                       top
                                                                                       of
                                                                                       auxprogs/valgrind-di-server.c.


                                                                                         .RE

                                                                                         .PP
                                                                                       --allow-mismatched-debuginfo=no|yes
                                                                                       [no]



                                                                                                 When
                                                                                           reading
                                                                                           debuginfo
                                                                                           from
                                                                                           separate
                                                                                           debuginfo
                                                                                           objects,
                                                                                           Valgrind
                                                                                           will
                                                                                           by
                                                                                           default
                                                                                           check
                                                                                           that
                                                                                           the
                                                                                           main
                                                                                           and
                                                                                           debuginfo
                                                                                           objects
                                                                                           match,
                                                                                           using
                                                                                           the
                                                                                           GNU
                                                                                           debuglink
                                                                                           mechanism.
                                                                                           This
                                                                                           guarantees
                                                                                           that
                                                                                           it
                                                                                           does
                                                                                           not
                                                                                           read
                                                                                           debuginfo
                                                                                           from
                                                                                           out
                                                                                           of
                                                                                           date
                                                                                           debuginfo
                                                                                           objects,
                                                                                           and
                                                                                           also
                                                                                           ensures
                                                                                           that
                                                                                           Valgrind
                                                                                           can't
                                                                                           crash
                                                                                           as
                                                                                           a
                                                                                           result
                                                                                           of
                                                                                           mismatches.



                                                                                                 This
                                                                                           check
                                                                                           can
                                                                                           be
                                                                                           overridden
                                                                                           using
                                                                                           --allow-mismatched-debuginfo=yes.
                                                                                           This
                                                                                           may
                                                                                           be
                                                                                           useful
                                                                                           when
                                                                                           the
                                                                                           debuginfo
                                                                                           and
                                                                                           main
                                                                                           objects
                                                                                           have
                                                                                           not
                                                                                           been
                                                                                           split
                                                                                           in
                                                                                           the
                                                                                           proper
                                                                                           way.
                                                                                           Be
                                                                                           careful
                                                                                           when
                                                                                           using
                                                                                           this,
                                                                                           though:
                                                                                           it
                                                                                           disables
                                                                                           all
                                                                                           consistency
                                                                                           checking,
                                                                                           and
                                                                                           Valgrind
                                                                                           has
                                                                                           been
                                                                                           observed
                                                                                           to
                                                                                           crash
                                                                                           when
                                                                                           the
                                                                                           main
                                                                                           and
                                                                                           debuginfo
                                                                                           objects
                                                                                           don't
                                                                                           match.


                                                                                             .RE

                                                                                             .PP
                                                                                           --suppressions=<filename>
                                                                                           [default:
                                                                                           $PREFIX/lib/valgrind/default.supp]



                                                                                                     Specifies
                                                                                               an
                                                                                               extra
                                                                                               file
                                                                                               from
                                                                                               which
                                                                                               to
                                                                                               read
                                                                                               descriptions
                                                                                               of
                                                                                               errors
                                                                                               to
                                                                                               suppress.
                                                                                               You
                                                                                               may
                                                                                               use
                                                                                               up
                                                                                               to
                                                                                               100
                                                                                               extra
                                                                                               suppression
                                                                                               files.


                                                                                                 .RE

                                                                                                 .PP
                                                                                               --gen-suppressions=<yes|no|all>
                                                                                               [default:
                                                                                               no]



                                                                                                         When
                                                                                                   set
                                                                                                   to
                                                                                                   yes,
                                                                                                   Valgrind
                                                                                                   will
                                                                                                   pause
                                                                                                   after
                                                                                                   every
                                                                                                   error
                                                                                                   shown
                                                                                                   and
                                                                                                   print
                                                                                                   the
                                                                                                   line:

                                                                                                           ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ----

                                                                                                   Pressing
                                                                                                   Ret,
                                                                                                   or
                                                                                                   N
                                                                                                   Ret
                                                                                                   or
                                                                                                   n
                                                                                                   Ret,
                                                                                                   causes
                                                                                                   Valgrind
                                                                                                   continue
                                                                                                   execution
                                                                                                   without
                                                                                                   printing
                                                                                                   a
                                                                                                   suppression
                                                                                                   for
                                                                                                   this
                                                                                                   error.



                                                                                                         Pressing
                                                                                                   Y
                                                                                                   Ret
                                                                                                   or
                                                                                                   y
                                                                                                   Ret
                                                                                                   causes
                                                                                                   Valgrind
                                                                                                   to
                                                                                                   write
                                                                                                   a
                                                                                                   suppression
                                                                                                   for
                                                                                                   this
                                                                                                   error.
                                                                                                   You
                                                                                                   can
                                                                                                   then
                                                                                                   cut
                                                                                                   and
                                                                                                   paste
                                                                                                   it
                                                                                                   into
                                                                                                   a
                                                                                                   suppression
                                                                                                   file
                                                                                                   if
                                                                                                   you
                                                                                                   don't
                                                                                                   want
                                                                                                   to
                                                                                                   hear
                                                                                                   about
                                                                                                   the
                                                                                                   error
                                                                                                   in
                                                                                                   the
                                                                                                   future.



                                                                                                         When
                                                                                                   set
                                                                                                   to
                                                                                                   all,
                                                                                                   Valgrind
                                                                                                   will
                                                                                                   print
                                                                                                   a
                                                                                                   suppression
                                                                                                   for
                                                                                                   every
                                                                                                   reported
                                                                                                   error,
                                                                                                   without
                                                                                                   querying
                                                                                                   the
                                                                                                   user.



                                                                                                         This
                                                                                                   option
                                                                                                   is
                                                                                                   particularly
                                                                                                   useful
                                                                                                   with
                                                                                                   C++
                                                                                                   programs,
                                                                                                   as
                                                                                                   it
                                                                                                   prints
                                                                                                   out
                                                                                                   the
                                                                                                   suppressions
                                                                                                   with
                                                                                                   mangled
                                                                                                   names,
                                                                                                   as
                                                                                                   required.



                                                                                                         Note
                                                                                                   that
                                                                                                   the
                                                                                                   suppressions
                                                                                                   printed
                                                                                                   are
                                                                                                   as
                                                                                                   specific
                                                                                                   as
                                                                                                   possible.
                                                                                                   You
                                                                                                   may
                                                                                                   want
                                                                                                   to
                                                                                                   common
                                                                                                   up
                                                                                                   similar
                                                                                                   ones,
                                                                                                   by
                                                                                                   adding
                                                                                                   wildcards
                                                                                                   to
                                                                                                   function
                                                                                                   names,
                                                                                                   and
                                                                                                   by
                                                                                                   using
                                                                                                   frame-level
                                                                                                   wildcards.
                                                                                                   The
                                                                                                   wildcarding
                                                                                                   facilities
                                                                                                   are
                                                                                                   powerful
                                                                                                   yet
                                                                                                   flexible,
                                                                                                   and
                                                                                                   with
                                                                                                   a
                                                                                                   bit
                                                                                                   of
                                                                                                   careful
                                                                                                   editing,
                                                                                                   you
                                                                                                   may
                                                                                                   be
                                                                                                   able
                                                                                                   to
                                                                                                   suppress
                                                                                                   a
                                                                                                   whole
                                                                                                   family
                                                                                                   of
                                                                                                   related
                                                                                                   errors
                                                                                                   with
                                                                                                   only
                                                                                                   a
                                                                                                   few
                                                                                                   suppressions.



                                                                                                         Sometimes
                                                                                                   two
                                                                                                   different
                                                                                                   errors
                                                                                                   are
                                                                                                   suppressed
                                                                                                   by
                                                                                                   the
                                                                                                   same
                                                                                                   suppression,
                                                                                                   in
                                                                                                   which
                                                                                                   case
                                                                                                   Valgrind
                                                                                                   will
                                                                                                   output
                                                                                                   the
                                                                                                   suppression
                                                                                                   more
                                                                                                   than
                                                                                                   once,
                                                                                                   but
                                                                                                   you
                                                                                                   only
                                                                                                   need
                                                                                                   to
                                                                                                   have
                                                                                                   one
                                                                                                   copy
                                                                                                   in
                                                                                                   your
                                                                                                   suppression
                                                                                                   file
                                                                                                   (but
                                                                                                   having
                                                                                                   more
                                                                                                   than
                                                                                                   one
                                                                                                   won't
                                                                                                   cause
                                                                                                   problems).
                                                                                                   Also,
                                                                                                   the
                                                                                                   suppression
                                                                                                   name
                                                                                                   is
                                                                                                   given
                                                                                                   as
                                                                                                   <insert
                                                                                                   a
                                                                                                   suppression
                                                                                                   name
                                                                                                   here>;
                                                                                                   the
                                                                                                   name
                                                                                                   doesn't
                                                                                                   really
                                                                                                   matter,
                                                                                                   it's
                                                                                                   only
                                                                                                   used
                                                                                                   with
                                                                                                   the
                                                                                                   -v
                                                                                                   option
                                                                                                   which
                                                                                                   prints
                                                                                                   out
                                                                                                   all
                                                                                                   used
                                                                                                   suppression
                                                                                                   records.


                                                                                                     .RE

                                                                                                     .PP
                                                                                                   --input-fd=<number>
                                                                                                   [default:
                                                                                                   0,
                                                                                                   stdin]



                                                                                                             When
                                                                                                       using
                                                                                                       --gen-suppressions=yes,
                                                                                                       Valgrind
                                                                                                       will
                                                                                                       stop
                                                                                                       so
                                                                                                       as
                                                                                                       to
                                                                                                       read
                                                                                                       keyboard
                                                                                                       input
                                                                                                       from
                                                                                                       you
                                                                                                       when
                                                                                                       each
                                                                                                       error
                                                                                                       occurs.
                                                                                                       By
                                                                                                       default
                                                                                                       it
                                                                                                       reads
                                                                                                       from
                                                                                                       the
                                                                                                       standard
                                                                                                       input
                                                                                                       (stdin),
                                                                                                       which
                                                                                                       is
                                                                                                       problematic
                                                                                                       for
                                                                                                       programs
                                                                                                       which
                                                                                                       close
                                                                                                       stdin.
                                                                                                       This
                                                                                                       option
                                                                                                       allows
                                                                                                       you
                                                                                                       to
                                                                                                       specify
                                                                                                       an
                                                                                                       alternative
                                                                                                       file
                                                                                                       descriptor
                                                                                                       from
                                                                                                       which
                                                                                                       to
                                                                                                       read
                                                                                                       input.


                                                                                                         .RE

                                                                                                         .PP
                                                                                                       --dsymutil=no|yes
                                                                                                       [yes]



                                                                                                                 This
                                                                                                           option
                                                                                                           is
                                                                                                           only
                                                                                                           relevant
                                                                                                           when
                                                                                                           running
                                                                                                           Valgrind
                                                                                                           on
                                                                                                           Mac
                                                                                                           OS
                                                                                                           X.



                                                                                                                 Mac
                                                                                                           OS
                                                                                                           X
                                                                                                           uses
                                                                                                           a
                                                                                                           deferred
                                                                                                           debug
                                                                                                           information
                                                                                                           (debuginfo)
                                                                                                           linking
                                                                                                           scheme.
                                                                                                           When
                                                                                                           object
                                                                                                           files
                                                                                                           containing
                                                                                                           debuginfo
                                                                                                           are
                                                                                                           linked
                                                                                                           into
                                                                                                           a
                                                                                                           .dylib
                                                                                                           or
                                                                                                           an
                                                                                                           executable,
                                                                                                           the
                                                                                                           debuginfo
                                                                                                           is
                                                                                                           not
                                                                                                           copied
                                                                                                           into
                                                                                                           the
                                                                                                           final
                                                                                                           file.
                                                                                                           Instead,
                                                                                                           the
                                                                                                           debuginfo
                                                                                                           must
                                                                                                           be
                                                                                                           linked
                                                                                                           manually
                                                                                                           by
                                                                                                           running
                                                                                                           dsymutil,
                                                                                                           a
                                                                                                           system-provided
                                                                                                           utility,
                                                                                                           on
                                                                                                           the
                                                                                                           executable
                                                                                                           or
                                                                                                           .dylib.
                                                                                                           The
                                                                                                           resulting
                                                                                                           combined
                                                                                                           debuginfo
                                                                                                           is
                                                                                                           placed
                                                                                                           in
                                                                                                           a
                                                                                                           directory
                                                                                                           alongside
                                                                                                           the
                                                                                                           executable
                                                                                                           or
                                                                                                           .dylib,
                                                                                                           but
                                                                                                           with
                                                                                                           the
                                                                                                           extension
                                                                                                           .dSYM.



                                                                                                                 With
                                                                                                           --dsymutil=no,
                                                                                                           Valgrind
                                                                                                           will
                                                                                                           detect
                                                                                                           cases
                                                                                                           where
                                                                                                           the
                                                                                                           .dSYM
                                                                                                           directory
                                                                                                           is
                                                                                                           either
                                                                                                           missing,
                                                                                                           or
                                                                                                           is
                                                                                                           present
                                                                                                           but
                                                                                                           does
                                                                                                           not
                                                                                                           appear
                                                                                                           to
                                                                                                           match
                                                                                                           the
                                                                                                           associated
                                                                                                           executable
                                                                                                           or
                                                                                                           .dylib,
                                                                                                           most
                                                                                                           likely
                                                                                                           because
                                                                                                           it
                                                                                                           is
                                                                                                           out
                                                                                                           of
                                                                                                           date.
                                                                                                           In
                                                                                                           these
                                                                                                           cases,
                                                                                                           Valgrind
                                                                                                           will
                                                                                                           print
                                                                                                           a
                                                                                                           warning
                                                                                                           message
                                                                                                           but
                                                                                                           take
                                                                                                           no
                                                                                                           further
                                                                                                           action.



                                                                                                                 With
                                                                                                           --dsymutil=yes,
                                                                                                           Valgrind
                                                                                                           will,
                                                                                                           in
                                                                                                           such
                                                                                                           cases,
                                                                                                           automatically
                                                                                                           run
                                                                                                           dsymutil
                                                                                                           as
                                                                                                           necessary
                                                                                                           to
                                                                                                           bring
                                                                                                           the
                                                                                                           debuginfo
                                                                                                           up
                                                                                                           to
                                                                                                           date.
                                                                                                           For
                                                                                                           all
                                                                                                           practical
                                                                                                           purposes,
                                                                                                           if
                                                                                                           you
                                                                                                           always
                                                                                                           use
                                                                                                           --dsymutil=yes,
                                                                                                           then
                                                                                                           there
                                                                                                           is
                                                                                                           never
                                                                                                           any
                                                                                                           need
                                                                                                           to
                                                                                                           run
                                                                                                           dsymutil
                                                                                                           manually
                                                                                                           or
                                                                                                           as
                                                                                                           part
                                                                                                           of
                                                                                                           your
                                                                                                           applications's
                                                                                                           build
                                                                                                           system,
                                                                                                           since
                                                                                                           Valgrind
                                                                                                           will
                                                                                                           run
                                                                                                           it
                                                                                                           as
                                                                                                           necessary.



                                                                                                                 Valgrind
                                                                                                           will
                                                                                                           not
                                                                                                           attempt
                                                                                                           to
                                                                                                           run
                                                                                                           dsymutil
                                                                                                           on
                                                                                                           any
                                                                                                           executable
                                                                                                           or
                                                                                                           library
                                                                                                           in
                                                                                                           /usr/,
                                                                                                           /bin/,
                                                                                                           /sbin/,
                                                                                                           /opt/,
                                                                                                           /sw/,
                                                                                                           /System/,
                                                                                                           /Library/
                                                                                                           or
                                                                                                           /Applications/
                                                                                                           since
                                                                                                           dsymutil
                                                                                                           will
                                                                                                           always
                                                                                                           fail
                                                                                                           in
                                                                                                           such
                                                                                                           situations.
                                                                                                           It
                                                                                                           fails
                                                                                                           both
                                                                                                           because
                                                                                                           the
                                                                                                           debuginfo
                                                                                                           for
                                                                                                           such
                                                                                                           pre-installed
                                                                                                           system
                                                                                                           components
                                                                                                           is
                                                                                                           not
                                                                                                           available
                                                                                                           anywhere,
                                                                                                           and
                                                                                                           also
                                                                                                           because
                                                                                                           it
                                                                                                           would
                                                                                                           require
                                                                                                           write
                                                                                                           privileges
                                                                                                           in
                                                                                                           those
                                                                                                           directories.



                                                                                                                 Be
                                                                                                           careful
                                                                                                           when
                                                                                                           using
                                                                                                           --dsymutil=yes,
                                                                                                           since
                                                                                                           it
                                                                                                           will
                                                                                                           cause
                                                                                                           pre-existing
                                                                                                           .dSYM
                                                                                                           directories
                                                                                                           to
                                                                                                           be
                                                                                                           silently
                                                                                                           deleted
                                                                                                           and
                                                                                                           re-created.
                                                                                                           Also
                                                                                                           note
                                                                                                           that
                                                                                                           dsymutil
                                                                                                           is
                                                                                                           quite
                                                                                                           slow,
                                                                                                           sometimes
                                                                                                           excessively
                                                                                                           so.


                                                                                                             .RE

                                                                                                             .PP
                                                                                                           --max-stackframe=<number>
                                                                                                           [default:
                                                                                                           2000000]



                                                                                                                     The
                                                                                                               maximum
                                                                                                               size
                                                                                                               of
                                                                                                               a
                                                                                                               stack
                                                                                                               frame.
                                                                                                               If
                                                                                                               the
                                                                                                               stack
                                                                                                               pointer
                                                                                                               moves
                                                                                                               by
                                                                                                               more
                                                                                                               than
                                                                                                               this
                                                                                                               amount
                                                                                                               then
                                                                                                               Valgrind
                                                                                                               will
                                                                                                               assume
                                                                                                               that
                                                                                                               the
                                                                                                               program
                                                                                                               is
                                                                                                               switching
                                                                                                               to
                                                                                                               a
                                                                                                               different
                                                                                                               stack.



                                                                                                                     You
                                                                                                               may
                                                                                                               need
                                                                                                               to
                                                                                                               use
                                                                                                               this
                                                                                                               option
                                                                                                               if
                                                                                                               your
                                                                                                               program
                                                                                                               has
                                                                                                               large
                                                                                                               stack-allocated
                                                                                                               arrays.
                                                                                                               Valgrind
                                                                                                               keeps
                                                                                                               track
                                                                                                               of
                                                                                                               your
                                                                                                               program's
                                                                                                               stack
                                                                                                               pointer.
                                                                                                               If
                                                                                                               it
                                                                                                               changes
                                                                                                               by
                                                                                                               more
                                                                                                               than
                                                                                                               the
                                                                                                               threshold
                                                                                                               amount,
                                                                                                               Valgrind
                                                                                                               assumes
                                                                                                               your
                                                                                                               program
                                                                                                               is
                                                                                                               switching
                                                                                                               to
                                                                                                               a
                                                                                                               different
                                                                                                               stack,
                                                                                                               and
                                                                                                               Memcheck
                                                                                                               behaves
                                                                                                               differently
                                                                                                               than
                                                                                                               it
                                                                                                               would
                                                                                                               for
                                                                                                               a
                                                                                                               stack
                                                                                                               pointer
                                                                                                               change
                                                                                                               smaller
                                                                                                               than
                                                                                                               the
                                                                                                               threshold.
                                                                                                               Usually
                                                                                                               this
                                                                                                               heuristic
                                                                                                               works
                                                                                                               well.
                                                                                                               However,
                                                                                                               if
                                                                                                               your
                                                                                                               program
                                                                                                               allocates
                                                                                                               large
                                                                                                               structures
                                                                                                               on
                                                                                                               the
                                                                                                               stack,
                                                                                                               this
                                                                                                               heuristic
                                                                                                               will
                                                                                                               be
                                                                                                               fooled,
                                                                                                               and
                                                                                                               Memcheck
                                                                                                               will
                                                                                                               subsequently
                                                                                                               report
                                                                                                               large
                                                                                                               numbers
                                                                                                               of
                                                                                                               invalid
                                                                                                               stack
                                                                                                               accesses.
                                                                                                               This
                                                                                                               option
                                                                                                               allows
                                                                                                               you
                                                                                                               to
                                                                                                               change
                                                                                                               the
                                                                                                               threshold
                                                                                                               to
                                                                                                               a
                                                                                                               different
                                                                                                               value.



                                                                                                                     You
                                                                                                               should
                                                                                                               only
                                                                                                               consider
                                                                                                               use
                                                                                                               of
                                                                                                               this
                                                                                                               option
                                                                                                               if
                                                                                                               Valgrind's
                                                                                                               debug
                                                                                                               output
                                                                                                               directs
                                                                                                               you
                                                                                                               to
                                                                                                               do
                                                                                                               so.
                                                                                                               In
                                                                                                               that
                                                                                                               case
                                                                                                               it
                                                                                                               will
                                                                                                               tell
                                                                                                               you
                                                                                                               the
                                                                                                               new
                                                                                                               threshold
                                                                                                               you
                                                                                                               should
                                                                                                               specify.



                                                                                                                     In
                                                                                                               general,
                                                                                                               allocating
                                                                                                               large
                                                                                                               structures
                                                                                                               on
                                                                                                               the
                                                                                                               stack
                                                                                                               is
                                                                                                               a
                                                                                                               bad
                                                                                                               idea,
                                                                                                               because
                                                                                                               you
                                                                                                               can
                                                                                                               easily
                                                                                                               run
                                                                                                               out
                                                                                                               of
                                                                                                               stack
                                                                                                               space,
                                                                                                               especially
                                                                                                               on
                                                                                                               systems
                                                                                                               with
                                                                                                               limited
                                                                                                               memory
                                                                                                               or
                                                                                                               which
                                                                                                               expect
                                                                                                               to
                                                                                                               support
                                                                                                               large
                                                                                                               numbers
                                                                                                               of
                                                                                                               threads
                                                                                                               each
                                                                                                               with
                                                                                                               a
                                                                                                               small
                                                                                                               stack,
                                                                                                               and
                                                                                                               also
                                                                                                               because
                                                                                                               the
                                                                                                               error
                                                                                                               checking
                                                                                                               performed
                                                                                                               by
                                                                                                               Memcheck
                                                                                                               is
                                                                                                               more
                                                                                                               effective
                                                                                                               for
                                                                                                               heap-allocated
                                                                                                               data
                                                                                                               than
                                                                                                               for
                                                                                                               stack-allocated
                                                                                                               data.
                                                                                                               If
                                                                                                               you
                                                                                                               have
                                                                                                               to
                                                                                                               use
                                                                                                               this
                                                                                                               option,
                                                                                                               you
                                                                                                               may
                                                                                                               wish
                                                                                                               to
                                                                                                               consider
                                                                                                               rewriting
                                                                                                               your
                                                                                                               code
                                                                                                               to
                                                                                                               allocate
                                                                                                               on
                                                                                                               the
                                                                                                               heap
                                                                                                               rather
                                                                                                               than
                                                                                                               on
                                                                                                               the
                                                                                                               stack.


                                                                                                                 .RE

                                                                                                                 .PP
                                                                                                               --main-stacksize=<number>
                                                                                                               [default:
                                                                                                               use
                                                                                                               current
                                                                                                               'ulimit'
                                                                                                               value]



                                                                                                                         Specifies
                                                                                                                   the
                                                                                                                   size
                                                                                                                   of
                                                                                                                   the
                                                                                                                   main
                                                                                                                   thread's
                                                                                                                   stack.



                                                                                                                         To
                                                                                                                   simplify
                                                                                                                   its
                                                                                                                   memory
                                                                                                                   management,
                                                                                                                   Valgrind
                                                                                                                   reserves
                                                                                                                   all
                                                                                                                   required
                                                                                                                   space
                                                                                                                   for
                                                                                                                   the
                                                                                                                   main
                                                                                                                   thread's
                                                                                                                   stack
                                                                                                                   at
                                                                                                                   startup.
                                                                                                                   That
                                                                                                                   means
                                                                                                                   it
                                                                                                                   needs
                                                                                                                   to
                                                                                                                   know
                                                                                                                   the
                                                                                                                   required
                                                                                                                   stack
                                                                                                                   size
                                                                                                                   at
                                                                                                                   startup.



                                                                                                                         By
                                                                                                                   default,
                                                                                                                   Valgrind
                                                                                                                   uses
                                                                                                                   the
                                                                                                                   current
                                                                                                                   "ulimit"
                                                                                                                   value
                                                                                                                   for
                                                                                                                   the
                                                                                                                   stack
                                                                                                                   size,
                                                                                                                   or
                                                                                                                   16
                                                                                                                   MB,
                                                                                                                   whichever
                                                                                                                   is
                                                                                                                   lower.
                                                                                                                   In
                                                                                                                   many
                                                                                                                   cases
                                                                                                                   this
                                                                                                                   gives
                                                                                                                   a
                                                                                                                   stack
                                                                                                                   size
                                                                                                                   in
                                                                                                                   the
                                                                                                                   range
                                                                                                                   8
                                                                                                                   to
                                                                                                                   16
                                                                                                                   MB,
                                                                                                                   which
                                                                                                                   almost
                                                                                                                   never
                                                                                                                   overflows
                                                                                                                   for
                                                                                                                   most
                                                                                                                   applications.



                                                                                                                         If
                                                                                                                   you
                                                                                                                   need
                                                                                                                   a
                                                                                                                   larger
                                                                                                                   total
                                                                                                                   stack
                                                                                                                   size,
                                                                                                                   use
                                                                                                                   --main-stacksize
                                                                                                                   to
                                                                                                                   specify
                                                                                                                   it.
                                                                                                                   Only
                                                                                                                   set
                                                                                                                   it
                                                                                                                   as
                                                                                                                   high
                                                                                                                   as
                                                                                                                   you
                                                                                                                   need,
                                                                                                                   since
                                                                                                                   reserving
                                                                                                                   far
                                                                                                                   more
                                                                                                                   space
                                                                                                                   than
                                                                                                                   you
                                                                                                                   need
                                                                                                                   (that
                                                                                                                   is,
                                                                                                                   hundreds
                                                                                                                   of
                                                                                                                   megabytes
                                                                                                                   more
                                                                                                                   than
                                                                                                                   you
                                                                                                                   need)
                                                                                                                   constrains
                                                                                                                   Valgrind's
                                                                                                                   memory
                                                                                                                   allocators
                                                                                                                   and
                                                                                                                   may
                                                                                                                   reduce
                                                                                                                   the
                                                                                                                   total
                                                                                                                   amount
                                                                                                                   of
                                                                                                                   memory
                                                                                                                   that
                                                                                                                   Valgrind
                                                                                                                   can
                                                                                                                   use.
                                                                                                                   This
                                                                                                                   is
                                                                                                                   only
                                                                                                                   really
                                                                                                                   of
                                                                                                                   significance
                                                                                                                   on
                                                                                                                   32-bit
                                                                                                                   machines.



                                                                                                                         On
                                                                                                                   Linux,
                                                                                                                   you
                                                                                                                   may
                                                                                                                   request
                                                                                                                   a
                                                                                                                   stack
                                                                                                                   of
                                                                                                                   size
                                                                                                                   up
                                                                                                                   to
                                                                                                                   2GB.
                                                                                                                   Valgrind
                                                                                                                   will
                                                                                                                   stop
                                                                                                                   with
                                                                                                                   a
                                                                                                                   diagnostic
                                                                                                                   message
                                                                                                                   if
                                                                                                                   the
                                                                                                                   stack
                                                                                                                   cannot
                                                                                                                   be
                                                                                                                   allocated.



                                                                                                                         --main-stacksize
                                                                                                                   only
                                                                                                                   affects
                                                                                                                   the
                                                                                                                   stack
                                                                                                                   size
                                                                                                                   for
                                                                                                                   the
                                                                                                                   program's
                                                                                                                   initial
                                                                                                                   thread.
                                                                                                                   It
                                                                                                                   has
                                                                                                                   no
                                                                                                                   bearing
                                                                                                                   on
                                                                                                                   the
                                                                                                                   size
                                                                                                                   of
                                                                                                                   thread
                                                                                                                   stacks,
                                                                                                                   as
                                                                                                                   Valgrind
                                                                                                                   does
                                                                                                                   not
                                                                                                                   allocate
                                                                                                                   those.



                                                                                                                         You
                                                                                                                   may
                                                                                                                   need
                                                                                                                   to
                                                                                                                   use
                                                                                                                   both
                                                                                                                   --main-stacksize
                                                                                                                   and
                                                                                                                   --max-stackframe
                                                                                                                   together.
                                                                                                                   It
                                                                                                                   is
                                                                                                                   important
                                                                                                                   to
                                                                                                                   understand
                                                                                                                   that
                                                                                                                   --main-stacksize
                                                                                                                   sets
                                                                                                                   the
                                                                                                                   maximum
                                                                                                                   total
                                                                                                                   stack
                                                                                                                   size,
                                                                                                                   whilst
                                                                                                                   --max-stackframe
                                                                                                                   specifies
                                                                                                                   the
                                                                                                                   largest
                                                                                                                   size
                                                                                                                   of
                                                                                                                   any
                                                                                                                   one
                                                                                                                   stack
                                                                                                                   frame.
                                                                                                                   You
                                                                                                                   will
                                                                                                                   have
                                                                                                                   to
                                                                                                                   work
                                                                                                                   out
                                                                                                                   the
                                                                                                                   --main-stacksize
                                                                                                                   value
                                                                                                                   for
                                                                                                                   yourself
                                                                                                                   (usually,
                                                                                                                   if
                                                                                                                   your
                                                                                                                   applications
                                                                                                                   segfaults).
                                                                                                                   But
                                                                                                                   Valgrind
                                                                                                                   will
                                                                                                                   tell
                                                                                                                   you
                                                                                                                   the
                                                                                                                   needed
                                                                                                                   --max-stackframe
                                                                                                                   size,
                                                                                                                   if
                                                                                                                   necessary.



                                                                                                                         As
                                                                                                                   discussed
                                                                                                                   further
                                                                                                                   in
                                                                                                                   the
                                                                                                                   description
                                                                                                                   of
                                                                                                                   --max-stackframe,
                                                                                                                   a
                                                                                                                   requirement
                                                                                                                   for
                                                                                                                   a
                                                                                                                   large
                                                                                                                   stack
                                                                                                                   is
                                                                                                                   a
                                                                                                                   sign
                                                                                                                   of
                                                                                                                   potential
                                                                                                                   portability
                                                                                                                   problems.
                                                                                                                   You
                                                                                                                   are
                                                                                                                   best
                                                                                                                   advised
                                                                                                                   to
                                                                                                                   place
                                                                                                                   all
                                                                                                                   large
                                                                                                                   data
                                                                                                                   in
                                                                                                                   heap-allocated
                                                                                                                   memory.


                                                                                                                     .RE

                                                                                                                     .PP
                                                                                                                   --max-threads=<number>
                                                                                                                   [default:
                                                                                                                   500]



                                                                                                                             By
                                                                                                                       default,
                                                                                                                       Valgrind
                                                                                                                       can
                                                                                                                       handle
                                                                                                                       to
                                                                                                                       up
                                                                                                                       to
                                                                                                                       500
                                                                                                                       threads.
                                                                                                                       Occasionally,
                                                                                                                       that
                                                                                                                       number
                                                                                                                       is
                                                                                                                       too
                                                                                                                       small.
                                                                                                                       Use
                                                                                                                       this
                                                                                                                       option
                                                                                                                       to
                                                                                                                       provide
                                                                                                                       a
                                                                                                                       different
                                                                                                                       limit.
                                                                                                                       E.g.
                                                                                                                       --max-threads=3000.


                                                                                                                         .RE







MALLOC()-RELATED OPTIONS
       For tools that use their own version of malloc (e.g. Memcheck, Massif,
       Helgrind, DRD), the following options apply.





         .PP --alignment=<number> [default: 8 or 16, depending on the
       platform]



                 By default Valgrind's malloc, realloc, etc, return a block
           whose starting address is 8-byte aligned or 16-byte aligned (the
           value depends on the platform and matches the platform default).
           This option allows you to specify a different alignment. The
           supplied value must be greater than or equal to the default, less
           than or equal to 4096, and must be a power of two.


             .RE

             .PP --redzone-size=<number> [default: depends on the tool]



                     Valgrind's malloc, realloc, etc, add padding blocks
               before and after each heap block allocated by the program being
               run. Such padding blocks are called redzones. The default value
               for the redzone size depends on the tool. For example, Memcheck
               adds and protects a minimum of 16 bytes before and after each
               block allocated by the client. This allows it to detect block
               underruns or overruns of up to 16 bytes.


                     Increasing the redzone size makes it possible to detect
               overruns of larger distances, but increases the amount of
               memory used by Valgrind. Decreasing the redzone size will
               reduce the memory needed by Valgrind but also reduces the
               chances of detecting over/underruns, so is not recommended.


                 .RE

                 .PP --xtree-memory=none|allocs|full [none]



                         Tools replacing Valgrind's malloc, realloc, etc, can
                   optionally produce an execution tree detailing which piece
                   of code is responsible for heap memory usage. See Execution
                   Trees for a detailed explanation about execution trees.



                         When set to none, no memory execution tree is
                   produced.



                         When set to allocs, the memory execution tree gives
                   the current number of allocated bytes and the current
                   number of allocated blocks.



                         When set to full, the memory execution tree gives 6
                   different measurements : the current number of allocated
                   bytes and blocks (same values as for allocs), the total
                   number of allocated bytes and blocks, the total number of
                   freed bytes and blocks.



                         Note that the overhead in cpu and memory to produce
                   an xtree depends on the tool. The overhead in cpu is small
                   for the value allocs, as the information needed to produce
                   this report is maintained in any case by the tool. For
                   massif and helgrind, specifying full implies to capture a
                   stack trace for each free operation, while normally these
                   tools only capture an allocation stack trace. For Memcheck,
                   the cpu overhead for the value full is small, as this can
                   only be used in combination with
                   --keep-stacktraces=alloc-and-free or
                   --keep-stacktraces=alloc-then-free, which already records a
                   stack trace for each free operation. The memory overhead
                   varies between 5 and 10 words per unique stacktrace in the
                   xtree, plus the memory needed to record the stack trace for
                   the free operations, if needed specifically for the xtree.


                     .RE

                     .PP --xtree-memory-file=<filename> [default:
                   xtmemory.kcg.%p]



                             Specifies that Valgrind should produce the xtree
                       memory report in the specified file. Any %p or %q
                       sequences appearing in the filename are expanded in
                       exactly the same way as they are for --log-file. See
                       the description of --log-file for details.


                             If the filename contains the extension .ms, then
                       the produced file format will be a massif output file
                       format. If the filename contains the extension .kcg or
                       no extension is provided or recognised, then the
                       produced file format will be a callgrind output format.


                             See Execution Trees for a detailed explanation
                       about execution trees formats.


                         .RE







UNCOMMON OPTIONS
       These options apply to all tools, as they affect certain obscure
       workings of the Valgrind core. Most people won't need to use them.





         .PP --smc-check=<none|stack|all|all-non-file> [default: all-non-file
       for x86/amd64/s390x, stack for other archs]



                 This option controls Valgrind's detection of self-modifying
           code. If no checking is done, when a program executes some code,
           then overwrites it with new code, and executes the new code,
           Valgrind will continue to execute the translations it made for the
           old code. This will likely lead to incorrect behaviour and/or
           crashes.


                 For "modern" architectures -- anything that's not x86, amd64
           or s390x -- the default is stack. This is because a correct program
           must take explicit action to reestablish D-I cache coherence
           following code modification. Valgrind observes and honours such
           actions, with the result that self-modifying code is transparently
           handled with zero extra cost.


                  For x86, amd64 and s390x, the program is not required to
           notify the hardware of required D-I coherence syncing. Hence the
           default is all-non-file, which covers the normal case of generating
           code into an anonymous (non-file-backed) mmap'd area.


                  The meanings of the four available settings are as follows.
           No detection (none), detect self-modifying code on the stack (which
           is used by GCC to implement nested functions) (stack), detect
           self-modifying code everywhere (all), and detect self-modifying
           code everywhere except in file-backed mappings (all-non-file).


                  Running with all will slow Valgrind down noticeably. Running
           with none will rarely speed things up, since very little code gets
           dynamically generated in most programs. The
           VALGRIND_DISCARD_TRANSLATIONS client request is an alternative to
           --smc-check=all and --smc-check=all-non-file that requires more
           programmer effort but allows Valgrind to run your program faster,
           by telling it precisely when translations need to be re-made.


                 --smc-check=all-non-file provides a cheaper but more limited
           version of --smc-check=all. It adds checks to any translations that
           do not originate from file-backed memory mappings. Typical
           applications that generate code, for example JITs in web browsers,
           generate code into anonymous mmaped areas, whereas the "fixed" code
           of the browser always lives in file-backed mappings.
           --smc-check=all-non-file takes advantage of this observation,
           limiting the overhead of checking to code which is likely to be JIT
           generated.


             .RE

             .PP --read-inline-info=<yes|no> [default: see below]



                     When enabled, Valgrind will read information about
               inlined function calls from DWARF3 debug info. This slows
               Valgrind startup and makes it use more memory (typically for
               each inlined piece of code, 6 words and space for the function
               name), but it results in more descriptive stacktraces.
               Currently, this functionality is enabled by default only for
               Linux, Android and Solaris targets and only for the tools
               Memcheck, Massif, Helgrind and DRD. Here is an example of some
               stacktraces with --read-inline-info=no:


                   ==15380== Conditional jump or move depends on uninitialised value(s)
                   ==15380==    at 0x80484EA: main (inlinfo.c:6)
                   ==15380==
                   ==15380== Conditional jump or move depends on uninitialised value(s)
                   ==15380==    at 0x8048550: fun_noninline (inlinfo.c:6)
                   ==15380==    by 0x804850E: main (inlinfo.c:34)
                   ==15380==
                   ==15380== Conditional jump or move depends on uninitialised value(s)
                   ==15380==    at 0x8048520: main (inlinfo.c:6)


                     And here are the same errors with --read-inline-info=yes:


                   ==15377== Conditional jump or move depends on uninitialised value(s)
                   ==15377==    at 0x80484EA: fun_d (inlinfo.c:6)
                   ==15377==    by 0x80484EA: fun_c (inlinfo.c:14)
                   ==15377==    by 0x80484EA: fun_b (inlinfo.c:20)
                   ==15377==    by 0x80484EA: fun_a (inlinfo.c:26)
                   ==15377==    by 0x80484EA: main (inlinfo.c:33)
                   ==15377==
                   ==15377== Conditional jump or move depends on uninitialised value(s)
                   ==15377==    at 0x8048550: fun_d (inlinfo.c:6)
                   ==15377==    by 0x8048550: fun_noninline (inlinfo.c:41)
                   ==15377==    by 0x804850E: main (inlinfo.c:34)
                   ==15377==
                   ==15377== Conditional jump or move depends on uninitialised value(s)
                   ==15377==    at 0x8048520: fun_d (inlinfo.c:6)
                   ==15377==    by 0x8048520: main (inlinfo.c:35)



                 .RE

                 .PP --read-var-info=<yes|no> [default: no]



                         When enabled, Valgrind will read information about
                   variable types and locations from DWARF3 debug info. This
                   slows Valgrind startup significantly and makes it use
                   significantly more memory, but for the tools that can take
                   advantage of it (Memcheck, Helgrind, DRD) it can result in
                   more precise error messages. For example, here are some
                   standard errors issued by Memcheck:


                       ==15363== Uninitialised byte(s) found during client check request
                       ==15363==    at 0x80484A9: croak (varinfo1.c:28)
                       ==15363==    by 0x8048544: main (varinfo1.c:55)
                       ==15363==  Address 0x80497f7 is 7 bytes inside data symbol "global_i2"
                       ==15363==
                       ==15363== Uninitialised byte(s) found during client check request
                       ==15363==    at 0x80484A9: croak (varinfo1.c:28)
                       ==15363==    by 0x8048550: main (varinfo1.c:56)
                       ==15363==  Address 0xbea0d0cc is on thread 1's stack
                       ==15363==  in frame #1, created by main (varinfo1.c:45)



                         And here are the same errors with
                   --read-var-info=yes:



                       ==15370== Uninitialised byte(s) found during client check request
                       ==15370==    at 0x80484A9: croak (varinfo1.c:28)
                       ==15370==    by 0x8048544: main (varinfo1.c:55)
                       ==15370==  Location 0x80497f7 is 0 bytes inside global_i2[7],
                       ==15370==  a global variable declared at varinfo1.c:41
                       ==15370==
                       ==15370== Uninitialised byte(s) found during client check request
                       ==15370==    at 0x80484A9: croak (varinfo1.c:28)
                       ==15370==    by 0x8048550: main (varinfo1.c:56)
                       ==15370==  Location 0xbeb4a0cc is 0 bytes inside local var "local"
                       ==15370==  declared at varinfo1.c:46, in frame #1 of thread 1



                     .RE

                     .PP --vgdb-poll=<number> [default: 5000]



                             As part of its main loop, the Valgrind scheduler
                       will poll to check if some activity (such as an
                       external command or some input from a gdb) has to be
                       handled by gdbserver. This activity poll will be done
                       after having run the given number of basic blocks (or
                       slightly more than the given number of basic blocks).
                       This poll is quite cheap so the default value is set
                       relatively low. You might further decrease this value
                       if vgdb cannot use ptrace system call to interrupt
                       Valgrind if all threads are (most of the time) blocked
                       in a system call.


                         .RE

                         .PP --vgdb-shadow-registers=no|yes [default: no]



                                 When activated, gdbserver will expose the
                           Valgrind shadow registers to GDB. With this, the
                           value of the Valgrind shadow registers can be
                           examined or changed using GDB. Exposing shadow
                           registers only works with GDB version 7.1 or later.


                             .RE

                             .PP --vgdb-prefix=<prefix> [default:
                           /tmp/vgdb-pipe]



                                     To communicate with gdb/vgdb, the
                               Valgrind gdbserver creates 3 files (2 named
                               FIFOs and a mmap shared memory file). The
                               prefix option controls the directory and prefix
                               for the creation of these files.


                                 .RE

                                 .PP --run-libc-freeres=<yes|no> [default:
                               yes]



                                         This option is only relevant when
                                   running Valgrind on Linux.



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



                                         The glibc authors realised that this
                                   behaviour causes leak checkers, such as
                                   Valgrind, to falsely report leaks in glibc,
                                   when a leak check is done at exit. In order
                                   to avoid this, they provided a routine
                                   called __libc_freeres specifically to make
                                   glibc release all memory it has allocated.
                                   Memcheck therefore tries to run
                                   __libc_freeres at exit.



                                         Unfortunately, in some very old
                                   versions of glibc, __libc_freeres is
                                   sufficiently buggy to cause segmentation
                                   faults. This was particularly noticeable on
                                   Red Hat 7.1. So this option is provided in
                                   order to inhibit the run of __libc_freeres.
                                   If your program seems to run fine on
                                   Valgrind, but segfaults at exit, you may
                                   find that --run-libc-freeres=no fixes that,
                                   although at the cost of possibly falsely
                                   reporting space leaks in libc.so.


                                     .RE

                                     .PP --run-cxx-freeres=<yes|no> [default:
                                   yes]



                                             This option is only relevant when
                                       running Valgrind on Linux or Solaris
                                       C++ programs.



                                             The GNU Standard C++ library
                                       (libstdc++.so), which is used by all
                                       C++ programs compiled with g++, may
                                       allocate memory for its own uses.
                                       Usually it doesn't bother to free that
                                       memory when the program ends—there
                                       would be no point, since the kernel
                                       reclaims all process resources when a
                                       process exits anyway, so it would just
                                       slow things down.



                                             The gcc authors realised that
                                       this behaviour causes leak checkers,
                                       such as Valgrind, to falsely report
                                       leaks in libstdc++, when a leak check
                                       is done at exit. In order to avoid
                                       this, they provided a routine called
                                       __gnu_cxx::__freeres specifically to
                                       make libstdc++ release all memory it
                                       has allocated. Memcheck therefore tries
                                       to run __gnu_cxx::__freeres at exit.



                                             For the sake of flexibility and
                                       unforeseen problems with
                                       __gnu_cxx::__freeres, option
                                       --run-cxx-freeres=no exists, although
                                       at the cost of possibly falsely
                                       reporting space leaks in libstdc++.so.


                                         .RE

                                         .PP --sim-hints=hint1,hint2,...



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





                                           •
                                                         lax-ioctls: Be very
                                               lax about ioctl handling; the
                                               only assumption is that the
                                               size is correct. Doesn't
                                               require the full buffer to be
                                               initialised when writing.
                                               Without this, using some device
                                               drivers with a large number of
                                               strange ioctl commands becomes
                                               very tiresome.

                                                       .RE



                                               •
                                                             fuse-compatible:
                                                   Enable special handling for
                                                   certain system calls that
                                                   may block in a FUSE
                                                   file-system. This may be
                                                   necessary when running
                                                   Valgrind on a
                                                   multi-threaded program that
                                                   uses one thread to manage a
                                                   FUSE file-system and
                                                   another thread to access
                                                   that file-system.

                                                           .RE



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

                                                               .RE



                                                       •
                                                                     no-inner-prefix:
                                                           Disable printing a
                                                           prefix > in front
                                                           of each stdout or
                                                           stderr output line
                                                           in an inner
                                                           Valgrind being run
                                                           by an outer
                                                           Valgrind. This is
                                                           useful when running
                                                           Valgrind regression
                                                           tests in an
                                                           outer/inner setup.
                                                           Note that the
                                                           prefix > will
                                                           always be printed
                                                           in front of the
                                                           inner debug logging
                                                           lines.

                                                                   .RE


                                                           •
                                                                         no-nptl-pthread-stackcache:
                                                               This hint is
                                                               only relevant
                                                               when running
                                                               Valgrind on
                                                               Linux; it is
                                                               ignored on
                                                               Solaris and Mac
                                                               OS X.



                                                                         The
                                                               GNU glibc
                                                               pthread library
                                                               (libpthread.so),
                                                               which is used
                                                               by pthread
                                                               programs,
                                                               maintains a
                                                               cache of
                                                               pthread stacks.
                                                               When a pthread
                                                               terminates, the
                                                               memory used for
                                                               the pthread
                                                               stack and some
                                                               thread local
                                                               storage related
                                                               data structure
                                                               are not always
                                                               directly
                                                               released. This
                                                               memory is kept
                                                               in a cache (up
                                                               to a certain
                                                               size), and is
                                                               re-used if a
                                                               new thread is
                                                               started.



                                                                         This
                                                               cache causes
                                                               the helgrind
                                                               tool to report
                                                               some false
                                                               positive race
                                                               condition
                                                               errors on this
                                                               cached memory,
                                                               as helgrind
                                                               does not
                                                               understand the
                                                               internal glibc
                                                               cache
                                                               synchronisation
                                                               primitives. So,
                                                               when using
                                                               helgrind,
                                                               disabling the
                                                               cache helps to
                                                               avoid false
                                                               positive race
                                                               conditions, in
                                                               particular when
                                                               using thread
                                                               local storage
                                                               variables (e.g.
                                                               variables using
                                                               the __thread
                                                               qualifier).



                                                                         When
                                                               using the
                                                               memcheck tool,
                                                               disabling the
                                                               cache ensures
                                                               the memory used
                                                               by glibc to
                                                               handle __thread
                                                               variables is
                                                               directly
                                                               released when a
                                                               thread
                                                               terminates.



                                                                         Note:
                                                               Valgrind
                                                               disables the
                                                               cache using
                                                               some internal
                                                               knowledge of
                                                               the glibc stack
                                                               cache
                                                               implementation
                                                               and by
                                                               examining the
                                                               debug
                                                               information of
                                                               the pthread
                                                               library. This
                                                               technique is
                                                               thus somewhat
                                                               fragile and
                                                               might not work
                                                               for all glibc
                                                               versions. This
                                                               has been
                                                               successfully
                                                               tested with
                                                               various glibc
                                                               versions (e.g.
                                                               2.11, 2.16,
                                                               2.18) on
                                                               various
                                                               platforms.

                                                                       .RE


                                                               •
                                                                             lax-doors:
                                                                   (Solaris
                                                                   only) Be
                                                                   very lax
                                                                   about door
                                                                   syscall
                                                                   handling
                                                                   over
                                                                   unrecognised
                                                                   door file
                                                                   descriptors.
                                                                   Does not
                                                                   require
                                                                   that full
                                                                   buffer is
                                                                   initialised
                                                                   when
                                                                   writing.
                                                                   Without
                                                                   this,
                                                                   programs
                                                                   using
                                                                   libdoor(3LIB)
                                                                   functionality
                                                                   with
                                                                   completely
                                                                   proprietary
                                                                   semantics
                                                                   may report
                                                                   large
                                                                   number of
                                                                   false
                                                                   positives.

                                                                           .RE


                                                                   •
                                                                                 fallback-llsc:
                                                                       (MIPS
                                                                       and
                                                                       ARM64
                                                                       only):
                                                                       Enables
                                                                       an
                                                                       alternative
                                                                       implementation
                                                                       of
                                                                       Load-Linked
                                                                       (LL)
                                                                       and
                                                                       Store-Conditional
                                                                       (SC)
                                                                       instructions.
                                                                       The
                                                                       standard
                                                                       implementation
                                                                       gives
                                                                       more
                                                                       correct
                                                                       behaviour,
                                                                       but can
                                                                       cause
                                                                       indefinite
                                                                       looping
                                                                       on
                                                                       certain
                                                                       processor
                                                                       implementations
                                                                       that
                                                                       are
                                                                       intolerant
                                                                       of
                                                                       extra
                                                                       memory
                                                                       references
                                                                       between
                                                                       LL and
                                                                       SC. So
                                                                       far
                                                                       this is
                                                                       known
                                                                       only to
                                                                       happen
                                                                       on
                                                                       Cavium
                                                                       3
                                                                       cores.
                                                                       You
                                                                       should
                                                                       not
                                                                       need to
                                                                       use
                                                                       this
                                                                       flag,
                                                                       since
                                                                       the
                                                                       relevant
                                                                       cores
                                                                       are
                                                                       detected
                                                                       at
                                                                       startup
                                                                       and the
                                                                       alternative
                                                                       implementation
                                                                       is
                                                                       automatically
                                                                       enabled
                                                                       if
                                                                       necessary.
                                                                       There
                                                                       is no
                                                                       equivalent
                                                                       anti-flag:
                                                                       you
                                                                       cannot
                                                                       force-disable
                                                                       the
                                                                       alternative
                                                                       implementation,
                                                                       if it
                                                                       is
                                                                       automatically
                                                                       enabled.
                                                                       The
                                                                       underlying
                                                                       problem
                                                                       exists
                                                                       because
                                                                       the
                                                                       "standard"
                                                                       implementation
                                                                       of LL
                                                                       and SC
                                                                       is done
                                                                       by
                                                                       copying
                                                                       through
                                                                       LL and
                                                                       SC
                                                                       instructions
                                                                       into
                                                                       the
                                                                       instrumented
                                                                       code.
                                                                       However,
                                                                       tools
                                                                       may
                                                                       insert
                                                                       extra
                                                                       instrumentation
                                                                       memory
                                                                       references
                                                                       in
                                                                       between
                                                                       the LL
                                                                       and SC
                                                                       instructions.
                                                                       These
                                                                       memory
                                                                       references
                                                                       are not
                                                                       present
                                                                       in the
                                                                       original
                                                                       uninstrumented
                                                                       code,
                                                                       and
                                                                       their
                                                                       presence
                                                                       in the
                                                                       instrumented
                                                                       code
                                                                       can
                                                                       cause
                                                                       the SC
                                                                       instructions
                                                                       to
                                                                       persistently
                                                                       fail,
                                                                       leading
                                                                       to
                                                                       indefinite
                                                                       looping
                                                                       in
                                                                       LL-SC
                                                                       blocks.
                                                                       The
                                                                       alternative
                                                                       implementation
                                                                       gives
                                                                       correct
                                                                       behaviour
                                                                       of LL
                                                                       and SC
                                                                       instructions
                                                                       between
                                                                       threads
                                                                       in a
                                                                       process,
                                                                       up to
                                                                       and
                                                                       including
                                                                       the ABA
                                                                       scenario.
                                                                       It also
                                                                       gives
                                                                       correct
                                                                       behaviour
                                                                       between
                                                                       a
                                                                       Valgrinded
                                                                       thread
                                                                       and a
                                                                       non-Valgrinded
                                                                       thread
                                                                       running
                                                                       in a
                                                                       different
                                                                       process,
                                                                       that
                                                                       communicate
                                                                       via
                                                                       shared
                                                                       memory,
                                                                       but
                                                                       only up
                                                                       to and
                                                                       including
                                                                       correct
                                                                       CAS
                                                                       behaviour
                                                                       -- in
                                                                       this
                                                                       case
                                                                       the ABA
                                                                       scenario
                                                                       may not
                                                                       be
                                                                       correctly
                                                                       handled.

                                                                               .RE
                                                                             .sp


                                                                         .RE

                                                                         .PP
                                                                       --fair-sched=<no|yes|try>
                                                                       [default:
                                                                       no]



                                                                                The
                                                                           --fair-sched
                                                                           option
                                                                           controls
                                                                           the
                                                                           locking
                                                                           mechanism
                                                                           used
                                                                           by
                                                                           Valgrind
                                                                           to
                                                                           serialise
                                                                           thread
                                                                           execution.
                                                                           The
                                                                           locking
                                                                           mechanism
                                                                           controls
                                                                           the
                                                                           way
                                                                           the
                                                                           threads
                                                                           are
                                                                           scheduled,
                                                                           and
                                                                           different
                                                                           settings
                                                                           give
                                                                           different
                                                                           trade-offs
                                                                           between
                                                                           fairness
                                                                           and
                                                                           performance.
                                                                           For
                                                                           more
                                                                           details
                                                                           about
                                                                           the
                                                                           Valgrind
                                                                           thread
                                                                           serialisation
                                                                           scheme
                                                                           and
                                                                           its
                                                                           impact
                                                                           on
                                                                           performance
                                                                           and
                                                                           thread
                                                                           scheduling,
                                                                           see
                                                                           Scheduling
                                                                           and
                                                                           Multi-
                                                                           Thread
                                                                           Performance.





                                                                           •
                                                                               The
                                                                               value
                                                                               --fair-sched=yes
                                                                               activates
                                                                               a
                                                                               fair
                                                                               scheduler.
                                                                               In
                                                                               short,
                                                                               if
                                                                               multiple
                                                                               threads
                                                                               are
                                                                               ready
                                                                               to
                                                                               run,
                                                                               the
                                                                               threads
                                                                               will
                                                                               be
                                                                               scheduled
                                                                               in
                                                                               a
                                                                               round
                                                                               robin
                                                                               fashion.
                                                                               This
                                                                               mechanism
                                                                               is
                                                                               not
                                                                               available
                                                                               on
                                                                               all
                                                                               platforms
                                                                               or
                                                                               Linux
                                                                               versions.
                                                                               If
                                                                               not
                                                                               available,
                                                                               using
                                                                               --fair-sched=yes
                                                                               will
                                                                               cause
                                                                               Valgrind
                                                                               to
                                                                               terminate
                                                                               with
                                                                               an
                                                                               error.


                                                                                       You
                                                                               may
                                                                               find
                                                                               this
                                                                               setting
                                                                               improves
                                                                               overall
                                                                               responsiveness
                                                                               if
                                                                               you
                                                                               are
                                                                               running
                                                                               an
                                                                               interactive
                                                                               multithreaded
                                                                               program,
                                                                               for
                                                                               example
                                                                               a
                                                                               web
                                                                               browser,
                                                                               on
                                                                               Valgrind.

                                                                                       .RE



                                                                               •
                                                                                   The
                                                                                   value
                                                                                   --fair-sched=try
                                                                                   activates
                                                                                   fair
                                                                                   scheduling
                                                                                   if
                                                                                   available
                                                                                   on
                                                                                   the
                                                                                   platform.
                                                                                   Otherwise,
                                                                                   it
                                                                                   will
                                                                                   automatically
                                                                                   fall
                                                                                   back
                                                                                   to
                                                                                   --fair-sched=no.

                                                                                           .RE



                                                                                   •
                                                                                       The
                                                                                       value
                                                                                       --fair-sched=no
                                                                                       activates
                                                                                       a
                                                                                       scheduler
                                                                                       which
                                                                                       does
                                                                                       not
                                                                                       guarantee
                                                                                       fairness
                                                                                       between
                                                                                       threads
                                                                                       ready
                                                                                       to
                                                                                       run,
                                                                                       but
                                                                                       which
                                                                                       in
                                                                                       general
                                                                                       gives
                                                                                       the
                                                                                       highest
                                                                                       performance.

                                                                                               .RE
                                                                                             .sp



                                                                                         .RE

                                                                                         .PP
                                                                                       --kernel-variant=variant1,variant2,...



                                                                                                 Handle
                                                                                           system
                                                                                           calls
                                                                                           and
                                                                                           ioctls
                                                                                           arising
                                                                                           from
                                                                                           minor
                                                                                           variants
                                                                                           of
                                                                                           the
                                                                                           default
                                                                                           kernel
                                                                                           for
                                                                                           this
                                                                                           platform.
                                                                                           This
                                                                                           is
                                                                                           useful
                                                                                           for
                                                                                           running
                                                                                           on
                                                                                           hacked
                                                                                           kernels
                                                                                           or
                                                                                           with
                                                                                           kernel
                                                                                           modules
                                                                                           which
                                                                                           support
                                                                                           nonstandard
                                                                                           ioctls,
                                                                                           for
                                                                                           example.
                                                                                           Use
                                                                                           with
                                                                                           caution.
                                                                                           If
                                                                                           you
                                                                                           don't
                                                                                           understand
                                                                                           what
                                                                                           this
                                                                                           option
                                                                                           does
                                                                                           then
                                                                                           you
                                                                                           almost
                                                                                           certainly
                                                                                           don't
                                                                                           need
                                                                                           it.
                                                                                           Currently
                                                                                           known
                                                                                           variants
                                                                                           are:




                                                                                           •
                                                                                                         bproc:
                                                                                               support
                                                                                               the
                                                                                               sys_broc
                                                                                               system
                                                                                               call
                                                                                               on
                                                                                               x86.
                                                                                               This
                                                                                               is
                                                                                               for
                                                                                               running
                                                                                               on
                                                                                               BProc,
                                                                                               which
                                                                                               is
                                                                                               a
                                                                                               minor
                                                                                               variant
                                                                                               of
                                                                                               standard
                                                                                               Linux
                                                                                               which
                                                                                               is
                                                                                               sometimes
                                                                                               used
                                                                                               for
                                                                                               building
                                                                                               clusters.

                                                                                                       .RE


                                                                                               •
                                                                                                             android-no-hw-tls:
                                                                                                   some
                                                                                                   versions
                                                                                                   of
                                                                                                   the
                                                                                                   Android
                                                                                                   emulator
                                                                                                   for
                                                                                                   ARM
                                                                                                   do
                                                                                                   not
                                                                                                   provide
                                                                                                   a
                                                                                                   hardware
                                                                                                   TLS
                                                                                                   (thread-local
                                                                                                   state)
                                                                                                   register,
                                                                                                   and
                                                                                                   Valgrind
                                                                                                   crashes
                                                                                                   at
                                                                                                   startup.
                                                                                                   Use
                                                                                                   this
                                                                                                   variant
                                                                                                   to
                                                                                                   select
                                                                                                   software
                                                                                                   support
                                                                                                   for
                                                                                                   TLS.

                                                                                                           .RE


                                                                                                   •
                                                                                                                 android-gpu-sgx5xx:
                                                                                                       use
                                                                                                       this
                                                                                                       to
                                                                                                       support
                                                                                                       handling
                                                                                                       of
                                                                                                       proprietary
                                                                                                       ioctls
                                                                                                       for
                                                                                                       the
                                                                                                       PowerVR
                                                                                                       SGX
                                                                                                       5XX
                                                                                                       series
                                                                                                       of
                                                                                                       GPUs
                                                                                                       on
                                                                                                       Android
                                                                                                       devices.
                                                                                                       Failure
                                                                                                       to
                                                                                                       select
                                                                                                       this
                                                                                                       does
                                                                                                       not
                                                                                                       cause
                                                                                                       stability
                                                                                                       problems,
                                                                                                       but
                                                                                                       may
                                                                                                       cause
                                                                                                       Memcheck
                                                                                                       to
                                                                                                       report
                                                                                                       false
                                                                                                       errors
                                                                                                       after
                                                                                                       the
                                                                                                       program
                                                                                                       performs
                                                                                                       GPU-specific
                                                                                                       ioctls.

                                                                                                               .RE


                                                                                                       •
                                                                                                                     android-gpu-adreno3xx:
                                                                                                           similarly,
                                                                                                           use
                                                                                                           this
                                                                                                           to
                                                                                                           support
                                                                                                           handling
                                                                                                           of
                                                                                                           proprietary
                                                                                                           ioctls
                                                                                                           for
                                                                                                           the
                                                                                                           Qualcomm
                                                                                                           Adreno
                                                                                                           3XX
                                                                                                           series
                                                                                                           of
                                                                                                           GPUs
                                                                                                           on
                                                                                                           Android
                                                                                                           devices.

                                                                                                                   .RE
                                                                                                                 .sp


                                                                                                             .RE

                                                                                                             .PP
                                                                                                           --merge-recursive-frames=<number>
                                                                                                           [default:
                                                                                                           0]



                                                                                                                     Some
                                                                                                               recursive
                                                                                                               algorithms,
                                                                                                               for
                                                                                                               example
                                                                                                               balanced
                                                                                                               binary
                                                                                                               tree
                                                                                                               implementations,
                                                                                                               create
                                                                                                               many
                                                                                                               different
                                                                                                               stack
                                                                                                               traces,
                                                                                                               each
                                                                                                               containing
                                                                                                               cycles
                                                                                                               of
                                                                                                               calls.
                                                                                                               A
                                                                                                               cycle
                                                                                                               is
                                                                                                               defined
                                                                                                               as
                                                                                                               two
                                                                                                               identical
                                                                                                               program
                                                                                                               counter
                                                                                                               values
                                                                                                               separated
                                                                                                               by
                                                                                                               zero
                                                                                                               or
                                                                                                               more
                                                                                                               other
                                                                                                               program
                                                                                                               counter
                                                                                                               values.
                                                                                                               Valgrind
                                                                                                               may
                                                                                                               then
                                                                                                               use
                                                                                                               a
                                                                                                               lot
                                                                                                               of
                                                                                                               memory
                                                                                                               to
                                                                                                               store
                                                                                                               all
                                                                                                               these
                                                                                                               stack
                                                                                                               traces.
                                                                                                               This
                                                                                                               is
                                                                                                               a
                                                                                                               poor
                                                                                                               use
                                                                                                               of
                                                                                                               memory
                                                                                                               considering
                                                                                                               that
                                                                                                               such
                                                                                                               stack
                                                                                                               traces
                                                                                                               contain
                                                                                                               repeated
                                                                                                               uninteresting
                                                                                                               recursive
                                                                                                               calls
                                                                                                               instead
                                                                                                               of
                                                                                                               more
                                                                                                               interesting
                                                                                                               information
                                                                                                               such
                                                                                                               as
                                                                                                               the
                                                                                                               function
                                                                                                               that
                                                                                                               has
                                                                                                               initiated
                                                                                                               the
                                                                                                               recursive
                                                                                                               call.


                                                                                                                     The
                                                                                                               option
                                                                                                               --merge-recursive-frames=<number>
                                                                                                               instructs
                                                                                                               Valgrind
                                                                                                               to
                                                                                                               detect
                                                                                                               and
                                                                                                               merge
                                                                                                               recursive
                                                                                                               call
                                                                                                               cycles
                                                                                                               having
                                                                                                               a
                                                                                                               size
                                                                                                               of
                                                                                                               up
                                                                                                               to
                                                                                                               <number>
                                                                                                               frames.
                                                                                                               When
                                                                                                               such
                                                                                                               a
                                                                                                               cycle
                                                                                                               is
                                                                                                               detected,
                                                                                                               Valgrind
                                                                                                               records
                                                                                                               the
                                                                                                               cycle
                                                                                                               in
                                                                                                               the
                                                                                                               stack
                                                                                                               trace
                                                                                                               as
                                                                                                               a
                                                                                                               unique
                                                                                                               program
                                                                                                               counter.


                                                                                                                     The
                                                                                                               value
                                                                                                               0
                                                                                                               (the
                                                                                                               default)
                                                                                                               causes
                                                                                                               no
                                                                                                               recursive
                                                                                                               call
                                                                                                               merging.
                                                                                                               A
                                                                                                               value
                                                                                                               of
                                                                                                               1
                                                                                                               will
                                                                                                               cause
                                                                                                               stack
                                                                                                               traces
                                                                                                               of
                                                                                                               simple
                                                                                                               recursive
                                                                                                               algorithms
                                                                                                               (for
                                                                                                               example,
                                                                                                               a
                                                                                                               factorial
                                                                                                               implementation)
                                                                                                               to
                                                                                                               be
                                                                                                               collapsed.
                                                                                                               A
                                                                                                               value
                                                                                                               of
                                                                                                               2
                                                                                                               will
                                                                                                               usually
                                                                                                               be
                                                                                                               needed
                                                                                                               to
                                                                                                               collapse
                                                                                                               stack
                                                                                                               traces
                                                                                                               produced
                                                                                                               by
                                                                                                               recursive
                                                                                                               algorithms
                                                                                                               such
                                                                                                               as
                                                                                                               binary
                                                                                                               trees,
                                                                                                               quick
                                                                                                               sort,
                                                                                                               etc.
                                                                                                               Higher
                                                                                                               values
                                                                                                               might
                                                                                                               be
                                                                                                               needed
                                                                                                               for
                                                                                                               more
                                                                                                               complex
                                                                                                               recursive
                                                                                                               algorithms.


                                                                                                                     Note:
                                                                                                               recursive
                                                                                                               calls
                                                                                                               are
                                                                                                               detected
                                                                                                               by
                                                                                                               analysis
                                                                                                               of
                                                                                                               program
                                                                                                               counter
                                                                                                               values.
                                                                                                               They
                                                                                                               are
                                                                                                               not
                                                                                                               detected
                                                                                                               by
                                                                                                               looking
                                                                                                               at
                                                                                                               function
                                                                                                               names.


                                                                                                                 .RE

                                                                                                                 .PP
                                                                                                               --num-transtab-sectors=<number>
                                                                                                               [default:
                                                                                                               6
                                                                                                               for
                                                                                                               Android
                                                                                                               platforms,
                                                                                                               16
                                                                                                               for
                                                                                                               all
                                                                                                               others]



                                                                                                                         Valgrind
                                                                                                                   translates
                                                                                                                   and
                                                                                                                   instruments
                                                                                                                   your
                                                                                                                   program's
                                                                                                                   machine
                                                                                                                   code
                                                                                                                   in
                                                                                                                   small
                                                                                                                   fragments
                                                                                                                   (basic
                                                                                                                   blocks).
                                                                                                                   The
                                                                                                                   translations
                                                                                                                   are
                                                                                                                   stored
                                                                                                                   in
                                                                                                                   a
                                                                                                                   translation
                                                                                                                   cache
                                                                                                                   that
                                                                                                                   is
                                                                                                                   divided
                                                                                                                   into
                                                                                                                   a
                                                                                                                   number
                                                                                                                   of
                                                                                                                   sections
                                                                                                                   (sectors).
                                                                                                                   If
                                                                                                                   the
                                                                                                                   cache
                                                                                                                   is
                                                                                                                   full,
                                                                                                                   the
                                                                                                                   sector
                                                                                                                   containing
                                                                                                                   the
                                                                                                                   oldest
                                                                                                                   translations
                                                                                                                   is
                                                                                                                   emptied
                                                                                                                   and
                                                                                                                   reused.
                                                                                                                   If
                                                                                                                   these
                                                                                                                   old
                                                                                                                   translations
                                                                                                                   are
                                                                                                                   needed
                                                                                                                   again,
                                                                                                                   Valgrind
                                                                                                                   must
                                                                                                                   re-translate
                                                                                                                   and
                                                                                                                   re-instrument
                                                                                                                   the
                                                                                                                   corresponding
                                                                                                                   machine
                                                                                                                   code,
                                                                                                                   which
                                                                                                                   is
                                                                                                                   expensive.
                                                                                                                   If
                                                                                                                   the
                                                                                                                   "executed
                                                                                                                   instructions"
                                                                                                                   working
                                                                                                                   set
                                                                                                                   of
                                                                                                                   a
                                                                                                                   program
                                                                                                                   is
                                                                                                                   big,
                                                                                                                   increasing
                                                                                                                   the
                                                                                                                   number
                                                                                                                   of
                                                                                                                   sectors
                                                                                                                   may
                                                                                                                   improve
                                                                                                                   performance
                                                                                                                   by
                                                                                                                   reducing
                                                                                                                   the
                                                                                                                   number
                                                                                                                   of
                                                                                                                   re-translations
                                                                                                                   needed.
                                                                                                                   Sectors
                                                                                                                   are
                                                                                                                   allocated
                                                                                                                   on
                                                                                                                   demand.
                                                                                                                   Once
                                                                                                                   allocated,
                                                                                                                   a
                                                                                                                   sector
                                                                                                                   can
                                                                                                                   never
                                                                                                                   be
                                                                                                                   freed,
                                                                                                                   and
                                                                                                                   occupies
                                                                                                                   considerable
                                                                                                                   space,
                                                                                                                   depending
                                                                                                                   on
                                                                                                                   the
                                                                                                                   tool
                                                                                                                   and
                                                                                                                   the
                                                                                                                   value
                                                                                                                   of
                                                                                                                   --avg-transtab-entry-size
                                                                                                                   (about
                                                                                                                   40
                                                                                                                   MB
                                                                                                                   per
                                                                                                                   sector
                                                                                                                   for
                                                                                                                   Memcheck).
                                                                                                                   Use
                                                                                                                   the
                                                                                                                   option
                                                                                                                   --stats=yes
                                                                                                                   to
                                                                                                                   obtain
                                                                                                                   precise
                                                                                                                   information
                                                                                                                   about
                                                                                                                   the
                                                                                                                   memory
                                                                                                                   used
                                                                                                                   by
                                                                                                                   a
                                                                                                                   sector
                                                                                                                   and
                                                                                                                   the
                                                                                                                   allocation
                                                                                                                   and
                                                                                                                   recycling
                                                                                                                   of
                                                                                                                   sectors.


                                                                                                                     .RE

                                                                                                                     .PP
                                                                                                                   --avg-transtab-entry-size=<number>
                                                                                                                   [default:
                                                                                                                   0,
                                                                                                                   meaning
                                                                                                                   use
                                                                                                                   tool
                                                                                                                   provided
                                                                                                                   default]



                                                                                                                             Average
                                                                                                                       size
                                                                                                                       of
                                                                                                                       translated
                                                                                                                       basic
                                                                                                                       block.
                                                                                                                       This
                                                                                                                       average
                                                                                                                       size
                                                                                                                       is
                                                                                                                       used
                                                                                                                       to
                                                                                                                       dimension
                                                                                                                       the
                                                                                                                       size
                                                                                                                       of
                                                                                                                       a
                                                                                                                       sector.
                                                                                                                       Each
                                                                                                                       tool
                                                                                                                       provides
                                                                                                                       a
                                                                                                                       default
                                                                                                                       value
                                                                                                                       to
                                                                                                                       be
                                                                                                                       used.
                                                                                                                       If
                                                                                                                       this
                                                                                                                       default
                                                                                                                       value
                                                                                                                       is
                                                                                                                       too
                                                                                                                       small,
                                                                                                                       the
                                                                                                                       translation
                                                                                                                       sectors
                                                                                                                       will
                                                                                                                       become
                                                                                                                       full
                                                                                                                       too
                                                                                                                       quickly.
                                                                                                                       If
                                                                                                                       this
                                                                                                                       default
                                                                                                                       value
                                                                                                                       is
                                                                                                                       too
                                                                                                                       big,
                                                                                                                       a
                                                                                                                       significant
                                                                                                                       part
                                                                                                                       of
                                                                                                                       the
                                                                                                                       translation
                                                                                                                       sector
                                                                                                                       memory
                                                                                                                       will
                                                                                                                       be
                                                                                                                       unused.
                                                                                                                       Note
                                                                                                                       that
                                                                                                                       the
                                                                                                                       average
                                                                                                                       size
                                                                                                                       of
                                                                                                                       a
                                                                                                                       basic
                                                                                                                       block
                                                                                                                       translation
                                                                                                                       depends
                                                                                                                       on
                                                                                                                       the
                                                                                                                       tool,
                                                                                                                       and
                                                                                                                       might
                                                                                                                       depend
                                                                                                                       on
                                                                                                                       tool
                                                                                                                       options.
                                                                                                                       For
                                                                                                                       example,
                                                                                                                       the
                                                                                                                       memcheck
                                                                                                                       option
                                                                                                                       --track-origins=yes
                                                                                                                       increases
                                                                                                                       the
                                                                                                                       size
                                                                                                                       of
                                                                                                                       the
                                                                                                                       basic
                                                                                                                       block
                                                                                                                       translations.
                                                                                                                       Use
                                                                                                                       --avg-transtab-entry-size
                                                                                                                       to
                                                                                                                       tune
                                                                                                                       the
                                                                                                                       size
                                                                                                                       of
                                                                                                                       the
                                                                                                                       sectors,
                                                                                                                       either
                                                                                                                       to
                                                                                                                       gain
                                                                                                                       memory
                                                                                                                       or
                                                                                                                       to
                                                                                                                       avoid
                                                                                                                       too
                                                                                                                       many
                                                                                                                       retranslations.


                                                                                                                         .RE

                                                                                                                         .PP
                                                                                                                       --aspace-minaddr=<address>
                                                                                                                       [default:
                                                                                                                       depends
                                                                                                                       on
                                                                                                                       the
                                                                                                                       platform]



                                                                                                                                 To
                                                                                                                           avoid
                                                                                                                           potential
                                                                                                                           conflicts
                                                                                                                           with
                                                                                                                           some
                                                                                                                           system
                                                                                                                           libraries,
                                                                                                                           Valgrind
                                                                                                                           does
                                                                                                                           not
                                                                                                                           use
                                                                                                                           the
                                                                                                                           address
                                                                                                                           space
                                                                                                                           below
                                                                                                                           --aspace-minaddr
                                                                                                                           value,
                                                                                                                           keeping
                                                                                                                           it
                                                                                                                           reserved
                                                                                                                           in
                                                                                                                           case
                                                                                                                           a
                                                                                                                           library
                                                                                                                           specifically
                                                                                                                           requests
                                                                                                                           memory
                                                                                                                           in
                                                                                                                           this
                                                                                                                           region.
                                                                                                                           So,
                                                                                                                           some
                                                                                                                           "pessimistic"
                                                                                                                           value
                                                                                                                           is
                                                                                                                           guessed
                                                                                                                           by
                                                                                                                           Valgrind
                                                                                                                           depending
                                                                                                                           on
                                                                                                                           the
                                                                                                                           platform.
                                                                                                                           On
                                                                                                                           linux,
                                                                                                                           by
                                                                                                                           default,
                                                                                                                           Valgrind
                                                                                                                           avoids
                                                                                                                           using
                                                                                                                           the
                                                                                                                           first
                                                                                                                           64MB
                                                                                                                           even
                                                                                                                           if
                                                                                                                           typically
                                                                                                                           there
                                                                                                                           is
                                                                                                                           no
                                                                                                                           conflict
                                                                                                                           in
                                                                                                                           this
                                                                                                                           complete
                                                                                                                           zone.
                                                                                                                           You
                                                                                                                           can
                                                                                                                           use
                                                                                                                           the
                                                                                                                           option
                                                                                                                           --aspace-minaddr
                                                                                                                           to
                                                                                                                           have
                                                                                                                           your
                                                                                                                           memory
                                                                                                                           hungry
                                                                                                                           application
                                                                                                                           benefitting
                                                                                                                           from
                                                                                                                           more
                                                                                                                           of
                                                                                                                           this
                                                                                                                           lower
                                                                                                                           memory.
                                                                                                                           On
                                                                                                                           the
                                                                                                                           other
                                                                                                                           hand,
                                                                                                                           if
                                                                                                                           you
                                                                                                                           encounter
                                                                                                                           a
                                                                                                                           conflict,
                                                                                                                           increasing
                                                                                                                           aspace-minaddr
                                                                                                                           value
                                                                                                                           might
                                                                                                                           solve
                                                                                                                           it.
                                                                                                                           Conflicts
                                                                                                                           will
                                                                                                                           typically
                                                                                                                           manifest
                                                                                                                           themselves
                                                                                                                           with
                                                                                                                           mmap
                                                                                                                           failures
                                                                                                                           in
                                                                                                                           the
                                                                                                                           low
                                                                                                                           range
                                                                                                                           of
                                                                                                                           the
                                                                                                                           address
                                                                                                                           space.
                                                                                                                           The
                                                                                                                           provided
                                                                                                                           address
                                                                                                                           must
                                                                                                                           be
                                                                                                                           page
                                                                                                                           aligned
                                                                                                                           and
                                                                                                                           must
                                                                                                                           be
                                                                                                                           equal
                                                                                                                           or
                                                                                                                           bigger
                                                                                                                           to
                                                                                                                           0x1000
                                                                                                                           (4KB).
                                                                                                                           To
                                                                                                                           find
                                                                                                                           the
                                                                                                                           default
                                                                                                                           value
                                                                                                                           on
                                                                                                                           your
                                                                                                                           platform,
                                                                                                                           do
                                                                                                                           something
                                                                                                                           such
                                                                                                                           as
                                                                                                                           valgrind
                                                                                                                           -d
                                                                                                                           -d
                                                                                                                           date
                                                                                                                           2>&1
                                                                                                                           |
                                                                                                                           grep
                                                                                                                           -i
                                                                                                                           minaddr.
                                                                                                                           Values
                                                                                                                           lower
                                                                                                                           than
                                                                                                                           0x10000
                                                                                                                           (64KB)
                                                                                                                           are
                                                                                                                           known
                                                                                                                           to
                                                                                                                           create
                                                                                                                           problems
                                                                                                                           on
                                                                                                                           some
                                                                                                                           distributions.


                                                                                                                             .RE

                                                                                                                             .PP
                                                                                                                           --valgrind-stacksize=<number>
                                                                                                                           [default:
                                                                                                                           1MB]



                                                                                                                                     For
                                                                                                                               each
                                                                                                                               thread,
                                                                                                                               Valgrind
                                                                                                                               needs
                                                                                                                               its
                                                                                                                               own
                                                                                                                               'private'
                                                                                                                               stack.
                                                                                                                               The
                                                                                                                               default
                                                                                                                               size
                                                                                                                               for
                                                                                                                               these
                                                                                                                               stacks
                                                                                                                               is
                                                                                                                               largely
                                                                                                                               dimensioned,
                                                                                                                               and
                                                                                                                               so
                                                                                                                               should
                                                                                                                               be
                                                                                                                               sufficient
                                                                                                                               in
                                                                                                                               most
                                                                                                                               cases.
                                                                                                                               In
                                                                                                                               case
                                                                                                                               the
                                                                                                                               size
                                                                                                                               is
                                                                                                                               too
                                                                                                                               small,
                                                                                                                               Valgrind
                                                                                                                               will
                                                                                                                               segfault.
                                                                                                                               Before
                                                                                                                               segfaulting,
                                                                                                                               a
                                                                                                                               warning
                                                                                                                               might
                                                                                                                               be
                                                                                                                               produced
                                                                                                                               by
                                                                                                                               Valgrind
                                                                                                                               when
                                                                                                                               approaching
                                                                                                                               the
                                                                                                                               limit.


                                                                                                                                     Use
                                                                                                                               the
                                                                                                                               option
                                                                                                                               --valgrind-stacksize
                                                                                                                               if
                                                                                                                               such
                                                                                                                               an
                                                                                                                               (unlikely)
                                                                                                                               warning
                                                                                                                               is
                                                                                                                               produced,
                                                                                                                               or
                                                                                                                               Valgrind
                                                                                                                               dies
                                                                                                                               due
                                                                                                                               to
                                                                                                                               a
                                                                                                                               segmentation
                                                                                                                               violation.
                                                                                                                               Such
                                                                                                                               segmentation
                                                                                                                               violations
                                                                                                                               have
                                                                                                                               been
                                                                                                                               seen
                                                                                                                               when
                                                                                                                               demangling
                                                                                                                               huge
                                                                                                                               C++
                                                                                                                               symbols.


                                                                                                                                     If
                                                                                                                               your
                                                                                                                               application
                                                                                                                               uses
                                                                                                                               many
                                                                                                                               threads
                                                                                                                               and
                                                                                                                               needs
                                                                                                                               a
                                                                                                                               lot
                                                                                                                               of
                                                                                                                               memory,
                                                                                                                               you
                                                                                                                               can
                                                                                                                               gain
                                                                                                                               some
                                                                                                                               memory
                                                                                                                               by
                                                                                                                               reducing
                                                                                                                               the
                                                                                                                               size
                                                                                                                               of
                                                                                                                               these
                                                                                                                               Valgrind
                                                                                                                               stacks
                                                                                                                               using
                                                                                                                               the
                                                                                                                               option
                                                                                                                               --valgrind-stacksize.


                                                                                                                                 .RE

                                                                                                                                 .PP
                                                                                                                               --show-emwarns=<yes|no>
                                                                                                                               [default:
                                                                                                                               no]



                                                                                                                                         When
                                                                                                                                   enabled,
                                                                                                                                   Valgrind
                                                                                                                                   will
                                                                                                                                   emit
                                                                                                                                   warnings
                                                                                                                                   about
                                                                                                                                   its
                                                                                                                                   CPU
                                                                                                                                   emulation
                                                                                                                                   in
                                                                                                                                   certain
                                                                                                                                   cases.
                                                                                                                                   These
                                                                                                                                   are
                                                                                                                                   usually
                                                                                                                                   not
                                                                                                                                   interesting.


                                                                                                                                     .RE

                                                                                                                                     .PP
                                                                                                                                   --require-text-symbol=:sonamepatt:fnnamepatt



                                                                                                                                             When
                                                                                                                                       a
                                                                                                                                       shared
                                                                                                                                       object
                                                                                                                                       whose
                                                                                                                                       soname
                                                                                                                                       matches
                                                                                                                                       sonamepatt
                                                                                                                                       is
                                                                                                                                       loaded
                                                                                                                                       into
                                                                                                                                       the
                                                                                                                                       process,
                                                                                                                                       examine
                                                                                                                                       all
                                                                                                                                       the
                                                                                                                                       text
                                                                                                                                       symbols
                                                                                                                                       it
                                                                                                                                       exports.
                                                                                                                                       If
                                                                                                                                       none
                                                                                                                                       of
                                                                                                                                       those
                                                                                                                                       match
                                                                                                                                       fnnamepatt,
                                                                                                                                       print
                                                                                                                                       an
                                                                                                                                       error
                                                                                                                                       message
                                                                                                                                       and
                                                                                                                                       abandon
                                                                                                                                       the
                                                                                                                                       run.
                                                                                                                                       This
                                                                                                                                       makes
                                                                                                                                       it
                                                                                                                                       possible
                                                                                                                                       to
                                                                                                                                       ensure
                                                                                                                                       that
                                                                                                                                       the
                                                                                                                                       run
                                                                                                                                       does
                                                                                                                                       not
                                                                                                                                       continue
                                                                                                                                       unless
                                                                                                                                       a
                                                                                                                                       given
                                                                                                                                       shared
                                                                                                                                       object
                                                                                                                                       contains
                                                                                                                                       a
                                                                                                                                       particular
                                                                                                                                       function
                                                                                                                                       name.


                                                                                                                                             Both
                                                                                                                                       sonamepatt
                                                                                                                                       and
                                                                                                                                       fnnamepatt
                                                                                                                                       can
                                                                                                                                       be
                                                                                                                                       written
                                                                                                                                       using
                                                                                                                                       the
                                                                                                                                       usual
                                                                                                                                       ?
                                                                                                                                       and
                                                                                                                                       *
                                                                                                                                       wildcards.
                                                                                                                                       For
                                                                                                                                       example:
                                                                                                                                       ":*libc.so*:foo?bar".
                                                                                                                                       You
                                                                                                                                       may
                                                                                                                                       use
                                                                                                                                       characters
                                                                                                                                       other
                                                                                                                                       than
                                                                                                                                       a
                                                                                                                                       colon
                                                                                                                                       to
                                                                                                                                       separate
                                                                                                                                       the
                                                                                                                                       two
                                                                                                                                       patterns.
                                                                                                                                       It
                                                                                                                                       is
                                                                                                                                       only
                                                                                                                                       important
                                                                                                                                       that
                                                                                                                                       the
                                                                                                                                       first
                                                                                                                                       character
                                                                                                                                       and
                                                                                                                                       the
                                                                                                                                       separator
                                                                                                                                       character
                                                                                                                                       are
                                                                                                                                       the
                                                                                                                                       same.
                                                                                                                                       For
                                                                                                                                       example,
                                                                                                                                       the
                                                                                                                                       above
                                                                                                                                       example
                                                                                                                                       could
                                                                                                                                       also
                                                                                                                                       be
                                                                                                                                       written
                                                                                                                                       "Q*libc.so*Qfoo?bar".
                                                                                                                                       Multiple
                                                                                                                                        --require-text-symbol
                                                                                                                                       flags
                                                                                                                                       are
                                                                                                                                       allowed,
                                                                                                                                       in
                                                                                                                                       which
                                                                                                                                       case
                                                                                                                                       shared
                                                                                                                                       objects
                                                                                                                                       that
                                                                                                                                       are
                                                                                                                                       loaded
                                                                                                                                       into
                                                                                                                                       the
                                                                                                                                       process
                                                                                                                                       will
                                                                                                                                       be
                                                                                                                                       checked
                                                                                                                                       against
                                                                                                                                       all
                                                                                                                                       of
                                                                                                                                       them.


                                                                                                                                             The
                                                                                                                                       purpose
                                                                                                                                       of
                                                                                                                                       this
                                                                                                                                       is
                                                                                                                                       to
                                                                                                                                       support
                                                                                                                                       reliable
                                                                                                                                       usage
                                                                                                                                       of
                                                                                                                                       marked-up
                                                                                                                                       libraries.
                                                                                                                                       For
                                                                                                                                       example,
                                                                                                                                       suppose
                                                                                                                                       we
                                                                                                                                       have
                                                                                                                                       a
                                                                                                                                       version
                                                                                                                                       of
                                                                                                                                       GCC's
                                                                                                                                       libgomp.so
                                                                                                                                       which
                                                                                                                                       has
                                                                                                                                       been
                                                                                                                                       marked
                                                                                                                                       up
                                                                                                                                       with
                                                                                                                                       annotations
                                                                                                                                       to
                                                                                                                                       support
                                                                                                                                       Helgrind.
                                                                                                                                       It
                                                                                                                                       is
                                                                                                                                       only
                                                                                                                                       too
                                                                                                                                       easy
                                                                                                                                       and
                                                                                                                                       confusing
                                                                                                                                       to
                                                                                                                                       load
                                                                                                                                       the
                                                                                                                                       wrong,
                                                                                                                                       un-annotated
                                                                                                                                       libgomp.so
                                                                                                                                       into
                                                                                                                                       the
                                                                                                                                       application.
                                                                                                                                       So
                                                                                                                                       the
                                                                                                                                       idea
                                                                                                                                       is:
                                                                                                                                       add
                                                                                                                                       a
                                                                                                                                       text
                                                                                                                                       symbol
                                                                                                                                       in
                                                                                                                                       the
                                                                                                                                       marked-up
                                                                                                                                       library,
                                                                                                                                       for
                                                                                                                                       example
                                                                                                                                       annotated_for_helgrind_3_6,
                                                                                                                                       and
                                                                                                                                       then
                                                                                                                                       give
                                                                                                                                       the
                                                                                                                                       flag
                                                                                                                                       --require-text-symbol=:*libgomp*so*:annotated_for_helgrind_3_6
                                                                                                                                       so
                                                                                                                                       that
                                                                                                                                       when
                                                                                                                                       libgomp.so
                                                                                                                                       is
                                                                                                                                       loaded,
                                                                                                                                       Valgrind
                                                                                                                                       scans
                                                                                                                                       its
                                                                                                                                       symbol
                                                                                                                                       table,
                                                                                                                                       and
                                                                                                                                       if
                                                                                                                                       the
                                                                                                                                       symbol
                                                                                                                                       isn't
                                                                                                                                       present
                                                                                                                                       the
                                                                                                                                       run
                                                                                                                                       is
                                                                                                                                       aborted,
                                                                                                                                       rather
                                                                                                                                       than
                                                                                                                                       continuing
                                                                                                                                       silently
                                                                                                                                       with
                                                                                                                                       the
                                                                                                                                       un-marked-up
                                                                                                                                       library.
                                                                                                                                       Note
                                                                                                                                       that
                                                                                                                                       you
                                                                                                                                       should
                                                                                                                                       put
                                                                                                                                       the
                                                                                                                                       entire
                                                                                                                                       flag
                                                                                                                                       in
                                                                                                                                       quotes
                                                                                                                                       to
                                                                                                                                       stop
                                                                                                                                       shells
                                                                                                                                       expanding
                                                                                                                                       up
                                                                                                                                       the
                                                                                                                                       *
                                                                                                                                       and
                                                                                                                                       ?
                                                                                                                                       wildcards.


                                                                                                                                         .RE

                                                                                                                                         .PP
                                                                                                                                       --soname-synonyms=syn1=pattern1,syn2=pattern2,...



                                                                                                                                                 When
                                                                                                                                           a
                                                                                                                                           shared
                                                                                                                                           library
                                                                                                                                           is
                                                                                                                                           loaded,
                                                                                                                                           Valgrind
                                                                                                                                           checks
                                                                                                                                           for
                                                                                                                                           functions
                                                                                                                                           in
                                                                                                                                           the
                                                                                                                                           library
                                                                                                                                           that
                                                                                                                                           must
                                                                                                                                           be
                                                                                                                                           replaced
                                                                                                                                           or
                                                                                                                                           wrapped.
                                                                                                                                           For
                                                                                                                                           example,
                                                                                                                                           Memcheck
                                                                                                                                           replaces
                                                                                                                                           some
                                                                                                                                           string
                                                                                                                                           and
                                                                                                                                           memory
                                                                                                                                           functions
                                                                                                                                           (strchr,
                                                                                                                                           strlen,
                                                                                                                                           strcpy,
                                                                                                                                           memchr,
                                                                                                                                           memcpy,
                                                                                                                                           memmove,
                                                                                                                                           etc.)
                                                                                                                                           with
                                                                                                                                           its
                                                                                                                                           own
                                                                                                                                           versions.
                                                                                                                                           Such
                                                                                                                                           replacements
                                                                                                                                           are
                                                                                                                                           normally
                                                                                                                                           done
                                                                                                                                           only
                                                                                                                                           in
                                                                                                                                           shared
                                                                                                                                           libraries
                                                                                                                                           whose
                                                                                                                                           soname
                                                                                                                                           matches
                                                                                                                                           a
                                                                                                                                           predefined
                                                                                                                                           soname
                                                                                                                                           pattern
                                                                                                                                           (e.g.
                                                                                                                                           libc.so*
                                                                                                                                           on
                                                                                                                                           linux).
                                                                                                                                           By
                                                                                                                                           default,
                                                                                                                                           no
                                                                                                                                           replacement
                                                                                                                                           is
                                                                                                                                           done
                                                                                                                                           for
                                                                                                                                           a
                                                                                                                                           statically
                                                                                                                                           linked
                                                                                                                                           binary
                                                                                                                                           or
                                                                                                                                           for
                                                                                                                                           alternative
                                                                                                                                           libraries,
                                                                                                                                           except
                                                                                                                                           for
                                                                                                                                           the
                                                                                                                                           allocation
                                                                                                                                           functions
                                                                                                                                           (malloc,
                                                                                                                                           free,
                                                                                                                                           calloc,
                                                                                                                                           memalign,
                                                                                                                                           realloc,
                                                                                                                                           operator
                                                                                                                                           new,
                                                                                                                                           operator
                                                                                                                                           delete,
                                                                                                                                           etc.)
                                                                                                                                           Such
                                                                                                                                           allocation
                                                                                                                                           functions
                                                                                                                                           are
                                                                                                                                           intercepted
                                                                                                                                           by
                                                                                                                                           default
                                                                                                                                           in
                                                                                                                                           any
                                                                                                                                           shared
                                                                                                                                           library
                                                                                                                                           or
                                                                                                                                           in
                                                                                                                                           the
                                                                                                                                           executable
                                                                                                                                           if
                                                                                                                                           they
                                                                                                                                           are
                                                                                                                                           exported
                                                                                                                                           as
                                                                                                                                           global
                                                                                                                                           symbols.
                                                                                                                                           This
                                                                                                                                           means
                                                                                                                                           that
                                                                                                                                           if
                                                                                                                                           a
                                                                                                                                           replacement
                                                                                                                                           allocation
                                                                                                                                           library
                                                                                                                                           such
                                                                                                                                           as
                                                                                                                                           tcmalloc
                                                                                                                                           is
                                                                                                                                           found,
                                                                                                                                           its
                                                                                                                                           functions
                                                                                                                                           are
                                                                                                                                           also
                                                                                                                                           intercepted
                                                                                                                                           by
                                                                                                                                           default.
                                                                                                                                           In
                                                                                                                                           some
                                                                                                                                           cases,
                                                                                                                                           the
                                                                                                                                           replacements
                                                                                                                                           allow
                                                                                                                                           --soname-synonyms
                                                                                                                                           to
                                                                                                                                           specify
                                                                                                                                           one
                                                                                                                                           additional
                                                                                                                                           synonym
                                                                                                                                           pattern,
                                                                                                                                           giving
                                                                                                                                           flexibility
                                                                                                                                           in
                                                                                                                                           the
                                                                                                                                           replacement.
                                                                                                                                           Or
                                                                                                                                           to
                                                                                                                                           prevent
                                                                                                                                           interception
                                                                                                                                           of
                                                                                                                                           all
                                                                                                                                           public
                                                                                                                                           allocation
                                                                                                                                           symbols.



                                                                                                                                                 Currently,
                                                                                                                                           this
                                                                                                                                           flexibility
                                                                                                                                           is
                                                                                                                                           only
                                                                                                                                           allowed
                                                                                                                                           for
                                                                                                                                           the
                                                                                                                                           malloc
                                                                                                                                           related
                                                                                                                                           functions,
                                                                                                                                           using
                                                                                                                                           the
                                                                                                                                           synonym
                                                                                                                                           somalloc.
                                                                                                                                           This
                                                                                                                                           synonym
                                                                                                                                           is
                                                                                                                                           usable
                                                                                                                                           for
                                                                                                                                           all
                                                                                                                                           tools
                                                                                                                                           doing
                                                                                                                                           standard
                                                                                                                                           replacement
                                                                                                                                           of
                                                                                                                                           malloc
                                                                                                                                           related
                                                                                                                                           functions
                                                                                                                                           (e.g.
                                                                                                                                           memcheck,
                                                                                                                                           helgrind,
                                                                                                                                           drd,
                                                                                                                                           massif,
                                                                                                                                           dhat).





                                                                                                                                           •

                                                                                                                                                         Alternate
                                                                                                                                               malloc
                                                                                                                                               library:
                                                                                                                                               to
                                                                                                                                               replace
                                                                                                                                               the
                                                                                                                                               malloc
                                                                                                                                               related
                                                                                                                                               functions
                                                                                                                                               in
                                                                                                                                               a
                                                                                                                                               specific
                                                                                                                                               alternate
                                                                                                                                               library
                                                                                                                                               with
                                                                                                                                               soname
                                                                                                                                               mymalloclib.so
                                                                                                                                               (and
                                                                                                                                               not
                                                                                                                                               in
                                                                                                                                               any
                                                                                                                                               others),
                                                                                                                                               give
                                                                                                                                               the
                                                                                                                                               option
                                                                                                                                               --soname-synonyms=somalloc=mymalloclib.so.
                                                                                                                                               A
                                                                                                                                               pattern
                                                                                                                                               can
                                                                                                                                               be
                                                                                                                                               used
                                                                                                                                               to
                                                                                                                                               match
                                                                                                                                               multiple
                                                                                                                                               libraries
                                                                                                                                               sonames.
                                                                                                                                               For
                                                                                                                                               example,
                                                                                                                                               --soname-synonyms=somalloc=*tcmalloc*
                                                                                                                                               will
                                                                                                                                               match
                                                                                                                                               the
                                                                                                                                               soname
                                                                                                                                               of
                                                                                                                                               all
                                                                                                                                               variants
                                                                                                                                               of
                                                                                                                                               the
                                                                                                                                               tcmalloc
                                                                                                                                               library
                                                                                                                                               (native,
                                                                                                                                               debug,
                                                                                                                                               profiled,
                                                                                                                                               ...
                                                                                                                                               tcmalloc
                                                                                                                                               variants).


                                                                                                                                                         Note:
                                                                                                                                               the
                                                                                                                                               soname
                                                                                                                                               of
                                                                                                                                               a
                                                                                                                                               elf
                                                                                                                                               shared
                                                                                                                                               library
                                                                                                                                               can
                                                                                                                                               be
                                                                                                                                               retrieved
                                                                                                                                               using
                                                                                                                                               the
                                                                                                                                               readelf
                                                                                                                                               utility.


                                                                                                                                                       .RE



                                                                                                                                               •
                                                                                                                                                             Replacements
                                                                                                                                                   in
                                                                                                                                                   a
                                                                                                                                                   statically
                                                                                                                                                   linked
                                                                                                                                                   library
                                                                                                                                                   are
                                                                                                                                                   done
                                                                                                                                                   by
                                                                                                                                                   using
                                                                                                                                                   the
                                                                                                                                                   NONE
                                                                                                                                                   pattern.
                                                                                                                                                   For
                                                                                                                                                   example,
                                                                                                                                                   if
                                                                                                                                                   you
                                                                                                                                                   link
                                                                                                                                                   with
                                                                                                                                                   libtcmalloc.a,
                                                                                                                                                   and
                                                                                                                                                   only
                                                                                                                                                   want
                                                                                                                                                   to
                                                                                                                                                   intercept
                                                                                                                                                   the
                                                                                                                                                   malloc
                                                                                                                                                   related
                                                                                                                                                   functions
                                                                                                                                                   in
                                                                                                                                                   the
                                                                                                                                                   executable
                                                                                                                                                   (and
                                                                                                                                                   standard
                                                                                                                                                   libraries)
                                                                                                                                                   themselves,
                                                                                                                                                   but
                                                                                                                                                   not
                                                                                                                                                   any
                                                                                                                                                   other
                                                                                                                                                   shared
                                                                                                                                                   libraries,
                                                                                                                                                   you
                                                                                                                                                   can
                                                                                                                                                   give
                                                                                                                                                   the
                                                                                                                                                   option
                                                                                                                                                   --soname-synonyms=somalloc=NONE.
                                                                                                                                                   Note
                                                                                                                                                   that
                                                                                                                                                   a
                                                                                                                                                   NONE
                                                                                                                                                   pattern
                                                                                                                                                   will
                                                                                                                                                   match
                                                                                                                                                   the
                                                                                                                                                   main
                                                                                                                                                   executable
                                                                                                                                                   and
                                                                                                                                                   any
                                                                                                                                                   shared
                                                                                                                                                   library
                                                                                                                                                   having
                                                                                                                                                   no
                                                                                                                                                   soname.

                                                                                                                                                           .RE



                                                                                                                                                   •
                                                                                                                                                                 To
                                                                                                                                                       run
                                                                                                                                                       a
                                                                                                                                                       "default"
                                                                                                                                                       Firefox
                                                                                                                                                       build
                                                                                                                                                       for
                                                                                                                                                       Linux,
                                                                                                                                                       in
                                                                                                                                                       which
                                                                                                                                                       JEMalloc
                                                                                                                                                       is
                                                                                                                                                       linked
                                                                                                                                                       in
                                                                                                                                                       to
                                                                                                                                                       the
                                                                                                                                                       main
                                                                                                                                                       executable,
                                                                                                                                                       use
                                                                                                                                                       --soname-synonyms=somalloc=NONE.

                                                                                                                                                               .RE



                                                                                                                                                       •

                                                                                                                                                           To
                                                                                                                                                           only
                                                                                                                                                           intercept
                                                                                                                                                           allocation
                                                                                                                                                           symbols
                                                                                                                                                           in
                                                                                                                                                           the
                                                                                                                                                           default
                                                                                                                                                           system
                                                                                                                                                           libraries,
                                                                                                                                                           but
                                                                                                                                                           not
                                                                                                                                                           in
                                                                                                                                                           any
                                                                                                                                                           other
                                                                                                                                                           shared
                                                                                                                                                           library
                                                                                                                                                           or
                                                                                                                                                           the
                                                                                                                                                           executable
                                                                                                                                                           defining
                                                                                                                                                           public
                                                                                                                                                           malloc
                                                                                                                                                           or
                                                                                                                                                           operator
                                                                                                                                                           new
                                                                                                                                                           related
                                                                                                                                                           functions
                                                                                                                                                           use
                                                                                                                                                           a
                                                                                                                                                           non-existing
                                                                                                                                                           library
                                                                                                                                                           name
                                                                                                                                                           like
                                                                                                                                                           --soname-synonyms=somalloc=nouserintercepts
                                                                                                                                                           (where
                                                                                                                                                           nouserintercepts
                                                                                                                                                           can
                                                                                                                                                           be
                                                                                                                                                           any
                                                                                                                                                           non-existing
                                                                                                                                                           library
                                                                                                                                                           name).

                                                                                                                                                                .RE



                                                                                                                                                           •
                                                                                                                                                                        Shared
                                                                                                                                                               library
                                                                                                                                                               of
                                                                                                                                                               the
                                                                                                                                                               dynamic
                                                                                                                                                               (runtime)
                                                                                                                                                               linker
                                                                                                                                                               is
                                                                                                                                                               excluded
                                                                                                                                                               from
                                                                                                                                                               searching
                                                                                                                                                               for
                                                                                                                                                               global
                                                                                                                                                               public
                                                                                                                                                               symbols,
                                                                                                                                                               such
                                                                                                                                                               as
                                                                                                                                                               those
                                                                                                                                                               for
                                                                                                                                                               the
                                                                                                                                                               malloc
                                                                                                                                                               related
                                                                                                                                                               functions
                                                                                                                                                               (identified
                                                                                                                                                               by
                                                                                                                                                               somalloc
                                                                                                                                                               synonym).

                                                                                                                                                                     .RE

                                                                                                                                                                     .sp


                                                                                                                                                                 .RE

                                                                                                                                                                 .PP
                                                                                                                                                               --progress-interval=<number>
                                                                                                                                                               [default:
                                                                                                                                                               0,
                                                                                                                                                               meaning
                                                                                                                                                               'disabled']



                                                                                                                                                                         This
                                                                                                                                                                   is
                                                                                                                                                                   an
                                                                                                                                                                   enhancement
                                                                                                                                                                   to
                                                                                                                                                                   Valgrind's
                                                                                                                                                                   debugging
                                                                                                                                                                   output.
                                                                                                                                                                   It
                                                                                                                                                                   is
                                                                                                                                                                   unlikely
                                                                                                                                                                   to
                                                                                                                                                                   be
                                                                                                                                                                   of
                                                                                                                                                                   interest
                                                                                                                                                                   to
                                                                                                                                                                   end
                                                                                                                                                                   users.


                                                                                                                                                                         When
                                                                                                                                                                   number
                                                                                                                                                                   is
                                                                                                                                                                   set
                                                                                                                                                                   to
                                                                                                                                                                   a
                                                                                                                                                                   non-zero
                                                                                                                                                                   value,
                                                                                                                                                                   Valgrind
                                                                                                                                                                   will
                                                                                                                                                                   print
                                                                                                                                                                   a
                                                                                                                                                                   one-line
                                                                                                                                                                   progress
                                                                                                                                                                   summary
                                                                                                                                                                   every
                                                                                                                                                                   number
                                                                                                                                                                   seconds.
                                                                                                                                                                   Valid
                                                                                                                                                                   settings
                                                                                                                                                                   for
                                                                                                                                                                   number
                                                                                                                                                                   are
                                                                                                                                                                   between
                                                                                                                                                                   0
                                                                                                                                                                   and
                                                                                                                                                                   3600
                                                                                                                                                                   inclusive.
                                                                                                                                                                   Here's
                                                                                                                                                                   some
                                                                                                                                                                   example
                                                                                                                                                                   output
                                                                                                                                                                   with
                                                                                                                                                                   number
                                                                                                                                                                   set
                                                                                                                                                                   to
                                                                                                                                                                   10:

                                                                                                                                                                       PROGRESS: U 110s, W 113s, 97.3% CPU, EvC 414.79M, TIn 616.7k, TOut 0.5k, #thr 67
                                                                                                                                                                       PROGRESS: U 120s, W 124s, 96.8% CPU, EvC 505.27M, TIn 636.6k, TOut 3.0k, #thr 64
                                                                                                                                                                       PROGRESS: U 130s, W 134s, 97.0% CPU, EvC 574.90M, TIn 657.5k, TOut 3.0k, #thr 63

                                                                                                                                                                   Each
                                                                                                                                                                   line
                                                                                                                                                                   shows:



                                                                                                                                                                   •   U:
                                                                                                                                                                       total
                                                                                                                                                                       user
                                                                                                                                                                       time


                                                                                                                                                                   •   W:
                                                                                                                                                                       total
                                                                                                                                                                       wallclock
                                                                                                                                                                       time


                                                                                                                                                                   •   CPU:
                                                                                                                                                                       overall
                                                                                                                                                                       average
                                                                                                                                                                       cpu
                                                                                                                                                                       use


                                                                                                                                                                   •   EvC:
                                                                                                                                                                       number
                                                                                                                                                                       of
                                                                                                                                                                       event
                                                                                                                                                                       checks.
                                                                                                                                                                       An
                                                                                                                                                                       event
                                                                                                                                                                       check
                                                                                                                                                                       is
                                                                                                                                                                       a
                                                                                                                                                                       backwards
                                                                                                                                                                       branch
                                                                                                                                                                       in
                                                                                                                                                                       the
                                                                                                                                                                       simulated
                                                                                                                                                                       program,
                                                                                                                                                                       so
                                                                                                                                                                       this
                                                                                                                                                                       is
                                                                                                                                                                       a
                                                                                                                                                                       measure
                                                                                                                                                                       of
                                                                                                                                                                       forward
                                                                                                                                                                       progress
                                                                                                                                                                       of
                                                                                                                                                                       the
                                                                                                                                                                       program


                                                                                                                                                                   •   TIn:
                                                                                                                                                                       number
                                                                                                                                                                       of
                                                                                                                                                                       code
                                                                                                                                                                       blocks
                                                                                                                                                                       instrumented
                                                                                                                                                                       by
                                                                                                                                                                       the
                                                                                                                                                                       JIT


                                                                                                                                                                   •   TOut:
                                                                                                                                                                       number
                                                                                                                                                                       of
                                                                                                                                                                       instrumented
                                                                                                                                                                       code
                                                                                                                                                                       blocks
                                                                                                                                                                       that
                                                                                                                                                                       have
                                                                                                                                                                       been
                                                                                                                                                                       thrown
                                                                                                                                                                       away


                                                                                                                                                                   •   #thr:
                                                                                                                                                                       number
                                                                                                                                                                       of
                                                                                                                                                                       threads
                                                                                                                                                                       in
                                                                                                                                                                       the
                                                                                                                                                                       program
                                                                                                                                                                         .sp
                                                                                                                                                                   From
                                                                                                                                                                   the
                                                                                                                                                                   progress
                                                                                                                                                                   of
                                                                                                                                                                   these,
                                                                                                                                                                   it
                                                                                                                                                                   is
                                                                                                                                                                   possible
                                                                                                                                                                   to
                                                                                                                                                                   observe:



                                                                                                                                                                   •   when
                                                                                                                                                                       the
                                                                                                                                                                       program
                                                                                                                                                                       is
                                                                                                                                                                       compute
                                                                                                                                                                       bound
                                                                                                                                                                       (TIn
                                                                                                                                                                       rises
                                                                                                                                                                       slowly,
                                                                                                                                                                       EvC
                                                                                                                                                                       rises
                                                                                                                                                                       rapidly)


                                                                                                                                                                   •   when
                                                                                                                                                                       the
                                                                                                                                                                       program
                                                                                                                                                                       is
                                                                                                                                                                       in
                                                                                                                                                                       a
                                                                                                                                                                       spinloop
                                                                                                                                                                       (TIn/TOut
                                                                                                                                                                       fixed,
                                                                                                                                                                       EvC
                                                                                                                                                                       rises
                                                                                                                                                                       rapidly)


                                                                                                                                                                   •   when
                                                                                                                                                                       the
                                                                                                                                                                       program
                                                                                                                                                                       is
                                                                                                                                                                       JIT-bound
                                                                                                                                                                       (TIn
                                                                                                                                                                       rises
                                                                                                                                                                       rapidly)


                                                                                                                                                                   •   when
                                                                                                                                                                       the
                                                                                                                                                                       program
                                                                                                                                                                       is
                                                                                                                                                                       rapidly
                                                                                                                                                                       discarding
                                                                                                                                                                       code
                                                                                                                                                                       (TOut
                                                                                                                                                                       rises
                                                                                                                                                                       rapidly)


                                                                                                                                                                   •   when
                                                                                                                                                                       the
                                                                                                                                                                       program
                                                                                                                                                                       is
                                                                                                                                                                       about
                                                                                                                                                                       to
                                                                                                                                                                       achieve
                                                                                                                                                                       some
                                                                                                                                                                       expected
                                                                                                                                                                       state
                                                                                                                                                                       (EvC
                                                                                                                                                                       arrives
                                                                                                                                                                       at
                                                                                                                                                                       some
                                                                                                                                                                       value
                                                                                                                                                                       you
                                                                                                                                                                       expect)


                                                                                                                                                                   •   when
                                                                                                                                                                       the
                                                                                                                                                                       program
                                                                                                                                                                       is
                                                                                                                                                                       idling
                                                                                                                                                                       (U
                                                                                                                                                                       rises
                                                                                                                                                                       more
                                                                                                                                                                       slowly
                                                                                                                                                                       than
                                                                                                                                                                       W)
                                                                                                                                                                         .sp



                                                                                                                                                                     .RE







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






MEMCHECK OPTIONS
         .PP --leak-check=<no|summary|yes|full> [default: summary]



                 When enabled, search for memory leaks when the client program
           finishes. If set to summary, it says how many leaks occurred. If
           set to full or yes, each individual leak will be shown in detail
           and/or counted as an error, as specified by the options
           --show-leak-kinds and --errors-for-leak-kinds.


                 If --xml=yes is given, memcheck will automatically use the
           value --leak-check=full. You can use --show-leak-kinds=none to
           reduce the size of the xml output if you are not interested in the
           leak results.


             .RE

             .PP --leak-resolution=<low|med|high> [default: high]



                     When doing leak checking, determines how willing Memcheck
               is to consider different backtraces to be the same for the
               purposes of merging multiple leaks into a single leak report.
               When set to low, only the first two entries need match. When
               med, four entries have to match. When high, all entries need to
               match.



                     For hardcore leak debugging, you probably want to use
               --leak-resolution=high together with --num-callers=40 or some
               such large number.



                     Note that the --leak-resolution setting does not affect
               Memcheck's ability to find leaks. It only changes how the
               results are presented.


                 .RE

                 .PP --show-leak-kinds=<set> [default: definite,possible]



                         Specifies the leak kinds to show in a full leak
                   search, in one of the following ways:





                   •   a comma separated list of one or more of definite
                       indirect possible reachable.

                               .RE



                       •   all to specify the complete set (all leak kinds).
                           It is equivalent to
                           --show-leak-kinds=definite,indirect,possible,reachable.

                                   .RE



                           •   none for the empty set.

                                       .RE
                                     .sp


                                 .RE


                                 .PP --errors-for-leak-kinds=<set> [default:
                               definite,possible]



                                         Specifies the leak kinds to count as
                                   errors in a full leak search. The <set> is
                                   specified similarly to --show-leak-kinds


                                     .RE


                                     .PP --leak-check-heuristics=<set>
                                   [default: all]



                                             Specifies the set of leak check
                                       heuristics to be used during leak
                                       searches. The heuristics control which
                                       interior pointers to a block cause it
                                       to be considered as reachable. The
                                       heuristic set is specified in one of
                                       the following ways:





                                       •   a comma separated list of one or
                                           more of stdstring length64 newarray
                                           multipleinheritance.

                                                   .RE



                                           •   all to activate the complete
                                               set of heuristics. It is
                                               equivalent to
                                               --leak-check-heuristics=stdstring,length64,newarray,multipleinheritance.

                                                       .RE



                                               •   none for the empty set.

                                                           .RE
                                                         .sp

                                                         Note that these
                                                   heuristics are dependent on
                                                   the layout of the objects
                                                   produced by the C++
                                                   compiler. They have been
                                                   tested with some gcc
                                                   versions (e.g. 4.4 and
                                                   4.7). They might not work
                                                   properly with other C++
                                                   compilers.


                                                     .RE

                                                     .PP
                                                   --show-reachable=<yes|no> ,
                                                   --show-possibly-lost=<yes|no>




                                                             These options
                                                       provide an alternative
                                                       way to specify the leak
                                                       kinds to show:




                                                       •
                                                           --show-reachable=no
                                                           --show-possibly-lost=yes
                                                           is equivalent to
                                                           --show-leak-kinds=definite,possible.

                                                                   .RE


                                                           •
                                                               --show-reachable=no
                                                               --show-possibly-lost=no
                                                               is equivalent
                                                               to
                                                               --show-leak-kinds=definite.

                                                                       .RE


                                                               •
                                                                   --show-reachable=yes
                                                                   is
                                                                   equivalent
                                                                   to
                                                                   --show-leak-kinds=all.

                                                                           .RE
                                                                         .sp

                                                                         Note
                                                                   that
                                                                   --show-possibly-lost=no
                                                                   has no
                                                                   effect if
                                                                   --show-reachable=yes
                                                                   is
                                                                   specified.


                                                                     .RE

                                                                     .PP
                                                                   --xtree-leak=<no|yes>
                                                                   [no]



                                                                             If
                                                                       set to
                                                                       yes,
                                                                       the
                                                                       results
                                                                       for the
                                                                       leak
                                                                       search
                                                                       done at
                                                                       exit
                                                                       will be
                                                                       output
                                                                       in a
                                                                       'Callgrind
                                                                       Format'
                                                                       execution
                                                                       tree
                                                                       file.
                                                                       Note
                                                                       that
                                                                       this
                                                                       automatically
                                                                       sets
                                                                       the
                                                                       options
                                                                       --leak-check=full
                                                                       and
                                                                       --show-leak-kinds=all,
                                                                       to
                                                                       allow
                                                                       xtree
                                                                       visualisation
                                                                       tools
                                                                       such as
                                                                       kcachegrind
                                                                       to
                                                                       select
                                                                       what
                                                                       kind to
                                                                       leak to
                                                                       visualise.
                                                                       The
                                                                       produced
                                                                       file
                                                                       will
                                                                       contain
                                                                       the
                                                                       following
                                                                       events:




                                                                       •   RB
                                                                           :
                                                                           Reachable
                                                                           Bytes



                                                                       •   PB
                                                                           :
                                                                           Possibly
                                                                           lost
                                                                           Bytes


                                                                       •   IB
                                                                           :
                                                                           Indirectly
                                                                           lost
                                                                           Bytes


                                                                       •   DB
                                                                           :
                                                                           Definitely
                                                                           lost
                                                                           Bytes
                                                                           (direct
                                                                           plus
                                                                           indirect)


                                                                       •   DIB
                                                                           :
                                                                           Definitely
                                                                           Indirectly
                                                                           lost
                                                                           Bytes
                                                                           (subset
                                                                           of
                                                                           DB)


                                                                       •   RBk
                                                                           :
                                                                           reachable
                                                                           Blocks


                                                                       •   PBk
                                                                           :
                                                                           Possibly
                                                                           lost
                                                                           Blocks


                                                                       •   IBk
                                                                           :
                                                                           Indirectly
                                                                           lost
                                                                           Blocks


                                                                       •   DBk
                                                                           :
                                                                           Definitely
                                                                           lost
                                                                           Blocks
                                                                             .sp


                                                                             The
                                                                       increase
                                                                       or
                                                                       decrease
                                                                       for all
                                                                       events
                                                                       above
                                                                       will
                                                                       also be
                                                                       output
                                                                       in the
                                                                       file to
                                                                       provide
                                                                       the
                                                                       delta
                                                                       (increase
                                                                       or
                                                                       decrease)
                                                                       between
                                                                       2
                                                                       successive
                                                                       leak
                                                                       searches.
                                                                       For
                                                                       example,
                                                                       iRB is
                                                                       the
                                                                       increase
                                                                       of the
                                                                       RB
                                                                       event,
                                                                       dPBk is
                                                                       the
                                                                       decrease
                                                                       of PBk
                                                                       event.
                                                                       The
                                                                       values
                                                                       for the
                                                                       increase
                                                                       and
                                                                       decrease
                                                                       events
                                                                       will be
                                                                       zero
                                                                       for the
                                                                       first
                                                                       leak
                                                                       search
                                                                       done.



                                                                             See
                                                                       Execution
                                                                       Trees
                                                                       for a
                                                                       detailed
                                                                       explanation
                                                                       about
                                                                       execution
                                                                       trees.


                                                                         .RE

                                                                         .PP
                                                                       --xtree-leak-file=<filename>
                                                                       [default:
                                                                       xtleak.kcg.%p]



                                                                                 Specifies
                                                                           that
                                                                           Valgrind
                                                                           should
                                                                           produce
                                                                           the
                                                                           xtree
                                                                           leak
                                                                           report
                                                                           in
                                                                           the
                                                                           specified
                                                                           file.
                                                                           Any
                                                                           %p,
                                                                           %q
                                                                           or
                                                                           %n
                                                                           sequences
                                                                           appearing
                                                                           in
                                                                           the
                                                                           filename
                                                                           are
                                                                           expanded
                                                                           in
                                                                           exactly
                                                                           the
                                                                           same
                                                                           way
                                                                           as
                                                                           they
                                                                           are
                                                                           for
                                                                           --log-file.
                                                                           See
                                                                           the
                                                                           description
                                                                           of
                                                                           --log-
                                                                           file
                                                                           for
                                                                           details.


                                                                                 See
                                                                           Execution
                                                                           Trees
                                                                           for
                                                                           a
                                                                           detailed
                                                                           explanation
                                                                           about
                                                                           execution
                                                                           trees
                                                                           formats.


                                                                             .RE

                                                                             .PP
                                                                           --undef-value-errors=<yes|no>
                                                                           [default:
                                                                           yes]



                                                                                     Controls
                                                                               whether
                                                                               Memcheck
                                                                               reports
                                                                               uses
                                                                               of
                                                                               undefined
                                                                               value
                                                                               errors.
                                                                               Set
                                                                               this
                                                                               to
                                                                               no
                                                                               if
                                                                               you
                                                                               don't
                                                                               want
                                                                               to
                                                                               see
                                                                               undefined
                                                                               value
                                                                               errors.
                                                                               It
                                                                               also
                                                                               has
                                                                               the
                                                                               side
                                                                               effect
                                                                               of
                                                                               speeding
                                                                               up
                                                                               Memcheck
                                                                               somewhat.
                                                                               AddrCheck
                                                                               (removed
                                                                               in
                                                                               Valgrind
                                                                               3.1.0)
                                                                               functioned
                                                                               like
                                                                               Memcheck
                                                                               with
                                                                               --undef-value-errors=no.


                                                                                 .RE

                                                                                 .PP
                                                                               --track-origins=<yes|no>
                                                                               [default:
                                                                               no]



                                                                                           Controls
                                                                                   whether
                                                                                   Memcheck
                                                                                   tracks
                                                                                   the
                                                                                   origin
                                                                                   of
                                                                                   uninitialised
                                                                                   values.
                                                                                   By
                                                                                   default,
                                                                                   it
                                                                                   does
                                                                                   not,
                                                                                   which
                                                                                   means
                                                                                   that
                                                                                   although
                                                                                   it
                                                                                   can
                                                                                   tell
                                                                                   you
                                                                                   that
                                                                                   an
                                                                                   uninitialised
                                                                                   value
                                                                                   is
                                                                                   being
                                                                                   used
                                                                                   in
                                                                                   a
                                                                                   dangerous
                                                                                   way,
                                                                                   it
                                                                                   cannot
                                                                                   tell
                                                                                   you
                                                                                   where
                                                                                   the
                                                                                   uninitialised
                                                                                   value
                                                                                   came
                                                                                   from.
                                                                                   This
                                                                                   often
                                                                                   makes
                                                                                   it
                                                                                   difficult
                                                                                   to
                                                                                   track
                                                                                   down
                                                                                   the
                                                                                   root
                                                                                   problem.


                                                                                           When
                                                                                   set
                                                                                   to
                                                                                   yes,
                                                                                   Memcheck
                                                                                   keeps
                                                                                   track
                                                                                   of
                                                                                   the
                                                                                   origins
                                                                                   of
                                                                                   all
                                                                                   uninitialised
                                                                                   values.
                                                                                   Then,
                                                                                   when
                                                                                   an
                                                                                   uninitialised
                                                                                   value
                                                                                   error
                                                                                   is
                                                                                   reported,
                                                                                   Memcheck
                                                                                   will
                                                                                   try
                                                                                   to
                                                                                   show
                                                                                   the
                                                                                   origin
                                                                                   of
                                                                                   the
                                                                                   value.
                                                                                   An
                                                                                   origin
                                                                                   can
                                                                                   be
                                                                                   one
                                                                                   of
                                                                                   the
                                                                                   following
                                                                                   four
                                                                                   places:
                                                                                   a
                                                                                   heap
                                                                                   block,
                                                                                   a
                                                                                   stack
                                                                                   allocation,
                                                                                   a
                                                                                   client
                                                                                   request,
                                                                                   or
                                                                                   miscellaneous
                                                                                   other
                                                                                   sources
                                                                                   (eg,
                                                                                   a
                                                                                   call
                                                                                   to
                                                                                   brk).


                                                                                           For
                                                                                   uninitialised
                                                                                   values
                                                                                   originating
                                                                                   from
                                                                                   a
                                                                                   heap
                                                                                   block,
                                                                                   Memcheck
                                                                                   shows
                                                                                   where
                                                                                   the
                                                                                   block
                                                                                   was
                                                                                   allocated.
                                                                                   For
                                                                                   uninitialised
                                                                                   values
                                                                                   originating
                                                                                   from
                                                                                   a
                                                                                   stack
                                                                                   allocation,
                                                                                   Memcheck
                                                                                   can
                                                                                   tell
                                                                                   you
                                                                                   which
                                                                                   function
                                                                                   allocated
                                                                                   the
                                                                                   value,
                                                                                   but
                                                                                   no
                                                                                   more
                                                                                   than
                                                                                   that
                                                                                   --
                                                                                   typically
                                                                                   it
                                                                                   shows
                                                                                   you
                                                                                   the
                                                                                   source
                                                                                   location
                                                                                   of
                                                                                   the
                                                                                   opening
                                                                                   brace
                                                                                   of
                                                                                   the
                                                                                   function.
                                                                                   So
                                                                                   you
                                                                                   should
                                                                                   carefully
                                                                                   check
                                                                                   that
                                                                                   all
                                                                                   of
                                                                                   the
                                                                                   function's
                                                                                   local
                                                                                   variables
                                                                                   are
                                                                                   initialised
                                                                                   properly.


                                                                                           Performance
                                                                                   overhead:
                                                                                   origin
                                                                                   tracking
                                                                                   is
                                                                                   expensive.
                                                                                   It
                                                                                   halves
                                                                                   Memcheck's
                                                                                   speed
                                                                                   and
                                                                                   increases
                                                                                   memory
                                                                                   use
                                                                                   by
                                                                                   a
                                                                                   minimum
                                                                                   of
                                                                                   100MB,
                                                                                   and
                                                                                   possibly
                                                                                   more.
                                                                                   Nevertheless
                                                                                   it
                                                                                   can
                                                                                   drastically
                                                                                   reduce
                                                                                   the
                                                                                   effort
                                                                                   required
                                                                                   to
                                                                                   identify
                                                                                   the
                                                                                   root
                                                                                   cause
                                                                                   of
                                                                                   uninitialised
                                                                                   value
                                                                                   errors,
                                                                                   and
                                                                                   so
                                                                                   is
                                                                                   often
                                                                                   a
                                                                                   programmer
                                                                                   productivity
                                                                                   win,
                                                                                   despite
                                                                                   running
                                                                                   more
                                                                                   slowly.


                                                                                           Accuracy:
                                                                                   Memcheck
                                                                                   tracks
                                                                                   origins
                                                                                   quite
                                                                                   accurately.
                                                                                   To
                                                                                   avoid
                                                                                   very
                                                                                   large
                                                                                   space
                                                                                   and
                                                                                   time
                                                                                   overheads,
                                                                                   some
                                                                                   approximations
                                                                                   are
                                                                                   made.
                                                                                   It
                                                                                   is
                                                                                   possible,
                                                                                   although
                                                                                   unlikely,
                                                                                   that
                                                                                   Memcheck
                                                                                   will
                                                                                   report
                                                                                   an
                                                                                   incorrect
                                                                                   origin,
                                                                                   or
                                                                                   not
                                                                                   be
                                                                                   able
                                                                                   to
                                                                                   identify
                                                                                   any
                                                                                   origin.


                                                                                           Note
                                                                                   that
                                                                                   the
                                                                                   combination
                                                                                   --track-origins=yes
                                                                                   and
                                                                                   --undef-value-errors=no
                                                                                   is
                                                                                   nonsensical.
                                                                                   Memcheck
                                                                                   checks
                                                                                   for
                                                                                   and
                                                                                   rejects
                                                                                   this
                                                                                   combination
                                                                                   at
                                                                                   startup.


                                                                                     .RE

                                                                                     .PP
                                                                                   --partial-loads-ok=<yes|no>
                                                                                   [default:
                                                                                   yes]



                                                                                             Controls
                                                                                       how
                                                                                       Memcheck
                                                                                       handles
                                                                                       32-,
                                                                                       64-,
                                                                                       128-
                                                                                       and
                                                                                       256-bit
                                                                                       naturally
                                                                                       aligned
                                                                                       loads
                                                                                       from
                                                                                       addresses
                                                                                       for
                                                                                       which
                                                                                       some
                                                                                       bytes
                                                                                       are
                                                                                       addressable
                                                                                       and
                                                                                       others
                                                                                       are
                                                                                       not.
                                                                                       When
                                                                                       yes,
                                                                                       such
                                                                                       loads
                                                                                       do
                                                                                       not
                                                                                       produce
                                                                                       an
                                                                                       address
                                                                                       error.
                                                                                       Instead,
                                                                                       loaded
                                                                                       bytes
                                                                                       originating
                                                                                       from
                                                                                       illegal
                                                                                       addresses
                                                                                       are
                                                                                       marked
                                                                                       as
                                                                                       uninitialised,
                                                                                       and
                                                                                       those
                                                                                       corresponding
                                                                                       to
                                                                                       legal
                                                                                       addresses
                                                                                       are
                                                                                       handled
                                                                                       in
                                                                                       the
                                                                                       normal
                                                                                       way.



                                                                                             When
                                                                                       no,
                                                                                       loads
                                                                                       from
                                                                                       partially
                                                                                       invalid
                                                                                       addresses
                                                                                       are
                                                                                       treated
                                                                                       the
                                                                                       same
                                                                                       as
                                                                                       loads
                                                                                       from
                                                                                       completely
                                                                                       invalid
                                                                                       addresses:
                                                                                       an
                                                                                       illegal-address
                                                                                       error
                                                                                       is
                                                                                       issued,
                                                                                       and
                                                                                       the
                                                                                       resulting
                                                                                       bytes
                                                                                       are
                                                                                       marked
                                                                                       as
                                                                                       initialised.



                                                                                             Note
                                                                                       that
                                                                                       code
                                                                                       that
                                                                                       behaves
                                                                                       in
                                                                                       this
                                                                                       way
                                                                                       is
                                                                                       in
                                                                                       violation
                                                                                       of
                                                                                       the
                                                                                       ISO
                                                                                       C/C++
                                                                                       standards,
                                                                                       and
                                                                                       should
                                                                                       be
                                                                                       considered
                                                                                       broken.
                                                                                       If
                                                                                       at
                                                                                       all
                                                                                       possible,
                                                                                       such
                                                                                       code
                                                                                       should
                                                                                       be
                                                                                       fixed.


                                                                                         .RE

                                                                                         .PP
                                                                                       --expensive-definedness-checks=<no|auto|yes>
                                                                                       [default:
                                                                                       auto]



                                                                                                 Controls
                                                                                           whether
                                                                                           Memcheck
                                                                                           should
                                                                                           employ
                                                                                           more
                                                                                           precise
                                                                                           but
                                                                                           also
                                                                                           more
                                                                                           expensive
                                                                                           (time
                                                                                           consuming)
                                                                                           instrumentation
                                                                                           when
                                                                                           checking
                                                                                           the
                                                                                           definedness
                                                                                           of
                                                                                           certain
                                                                                           values.
                                                                                           In
                                                                                           particular,
                                                                                           this
                                                                                           affects
                                                                                           the
                                                                                           instrumentation
                                                                                           of
                                                                                           integer
                                                                                           adds,
                                                                                           subtracts
                                                                                           and
                                                                                           equality
                                                                                           comparisons.


                                                                                                 Selecting
                                                                                           --expensive-definedness-checks=yes
                                                                                           causes
                                                                                           Memcheck
                                                                                           to
                                                                                           use
                                                                                           the
                                                                                           most
                                                                                           accurate
                                                                                           analysis
                                                                                           possible.
                                                                                           This
                                                                                           minimises
                                                                                           false
                                                                                           error
                                                                                           rates
                                                                                           but
                                                                                           can
                                                                                           cause
                                                                                           up
                                                                                           to
                                                                                           30%
                                                                                           performance
                                                                                           degradation.


                                                                                                 Selecting
                                                                                           --expensive-definedness-checks=no
                                                                                           causes
                                                                                           Memcheck
                                                                                           to
                                                                                           use
                                                                                           the
                                                                                           cheapest
                                                                                           instrumentation
                                                                                           possible.
                                                                                           This
                                                                                           maximises
                                                                                           performance
                                                                                           but
                                                                                           will
                                                                                           normally
                                                                                           give
                                                                                           an
                                                                                           unusably
                                                                                           high
                                                                                           false
                                                                                           error
                                                                                           rate.


                                                                                                 The
                                                                                           default
                                                                                           setting,
                                                                                           --expensive-definedness-checks=auto,
                                                                                           is
                                                                                           strongly
                                                                                           recommended.
                                                                                           This
                                                                                           causes
                                                                                           Memcheck
                                                                                           to
                                                                                           use
                                                                                           the
                                                                                           minimum
                                                                                           of
                                                                                           expensive
                                                                                           instrumentation
                                                                                           needed
                                                                                           to
                                                                                           achieve
                                                                                           the
                                                                                           same
                                                                                           false
                                                                                           error
                                                                                           rate
                                                                                           as
                                                                                           --expensive-definedness-checks=yes.
                                                                                           It
                                                                                           also
                                                                                           enables
                                                                                           an
                                                                                           instrumentation-time
                                                                                           analysis
                                                                                           pass
                                                                                           which
                                                                                           aims
                                                                                           to
                                                                                           further
                                                                                           reduce
                                                                                           the
                                                                                           costs
                                                                                           of
                                                                                           accurate
                                                                                           instrumentation.
                                                                                           Overall,
                                                                                           the
                                                                                           performance
                                                                                           loss
                                                                                           is
                                                                                           generally
                                                                                           around
                                                                                           5%
                                                                                           relative
                                                                                           to
                                                                                           --expensive-definedness-checks=no,
                                                                                           although
                                                                                           this
                                                                                           is
                                                                                           strongly
                                                                                           workload
                                                                                           dependent.
                                                                                           Note
                                                                                           that
                                                                                           the
                                                                                           exact
                                                                                           instrumentation
                                                                                           settings
                                                                                           in
                                                                                           this
                                                                                           mode
                                                                                           are
                                                                                           architecture
                                                                                           dependent.


                                                                                             .RE

                                                                                             .PP
                                                                                           --keep-stacktraces=alloc|free|alloc-and-free|alloc-then-free|none
                                                                                           [default:
                                                                                           alloc-and-free]



                                                                                                     Controls
                                                                                               which
                                                                                               stack
                                                                                               trace(s)
                                                                                               to
                                                                                               keep
                                                                                               for
                                                                                               malloc'd
                                                                                               and/or
                                                                                               free'd
                                                                                               blocks.



                                                                                                     With
                                                                                               alloc-then-free,
                                                                                               a
                                                                                               stack
                                                                                               trace
                                                                                               is
                                                                                               recorded
                                                                                               at
                                                                                               allocation
                                                                                               time,
                                                                                               and
                                                                                               is
                                                                                               associated
                                                                                               with
                                                                                               the
                                                                                               block.
                                                                                               When
                                                                                               the
                                                                                               block
                                                                                               is
                                                                                               freed,
                                                                                               a
                                                                                               second
                                                                                               stack
                                                                                               trace
                                                                                               is
                                                                                               recorded,
                                                                                               and
                                                                                               this
                                                                                               replaces
                                                                                               the
                                                                                               allocation
                                                                                               stack
                                                                                               trace.
                                                                                               As
                                                                                               a
                                                                                               result,
                                                                                               any
                                                                                               "use
                                                                                               after
                                                                                               free"
                                                                                               errors
                                                                                               relating
                                                                                               to
                                                                                               this
                                                                                               block
                                                                                               can
                                                                                               only
                                                                                               show
                                                                                               a
                                                                                               stack
                                                                                               trace
                                                                                               for
                                                                                               where
                                                                                               the
                                                                                               block
                                                                                               was
                                                                                               freed.



                                                                                                     With
                                                                                               alloc-and-free,
                                                                                               both
                                                                                               allocation
                                                                                               and
                                                                                               the
                                                                                               deallocation
                                                                                               stack
                                                                                               traces
                                                                                               for
                                                                                               the
                                                                                               block
                                                                                               are
                                                                                               stored.
                                                                                               Hence
                                                                                               a
                                                                                               "use
                                                                                               after
                                                                                               free"
                                                                                               error
                                                                                               will
                                                                                               show
                                                                                               both,
                                                                                               which
                                                                                               may
                                                                                               make
                                                                                               the
                                                                                               error
                                                                                               easier
                                                                                               to
                                                                                               diagnose.
                                                                                               Compared
                                                                                               to
                                                                                               alloc-then-free,
                                                                                               this
                                                                                               setting
                                                                                               slightly
                                                                                               increases
                                                                                               Valgrind's
                                                                                               memory
                                                                                               use
                                                                                               as
                                                                                               the
                                                                                               block
                                                                                               contains
                                                                                               two
                                                                                               references
                                                                                               instead
                                                                                               of
                                                                                               one.



                                                                                                     With
                                                                                               alloc,
                                                                                               only
                                                                                               the
                                                                                               allocation
                                                                                               stack
                                                                                               trace
                                                                                               is
                                                                                               recorded
                                                                                               (and
                                                                                               reported).
                                                                                               With
                                                                                               free,
                                                                                               only
                                                                                               the
                                                                                               deallocation
                                                                                               stack
                                                                                               trace
                                                                                               is
                                                                                               recorded
                                                                                               (and
                                                                                               reported).
                                                                                               These
                                                                                               values
                                                                                               somewhat
                                                                                               decrease
                                                                                               Valgrind's
                                                                                               memory
                                                                                               and
                                                                                               cpu
                                                                                               usage.
                                                                                               They
                                                                                               can
                                                                                               be
                                                                                               useful
                                                                                               depending
                                                                                               on
                                                                                               the
                                                                                               error
                                                                                               types
                                                                                               you
                                                                                               are
                                                                                               searching
                                                                                               for
                                                                                               and
                                                                                               the
                                                                                               level
                                                                                               of
                                                                                               detail
                                                                                               you
                                                                                               need
                                                                                               to
                                                                                               analyse
                                                                                               them.
                                                                                               For
                                                                                               example,
                                                                                               if
                                                                                               you
                                                                                               are
                                                                                               only
                                                                                               interested
                                                                                               in
                                                                                               memory
                                                                                               leak
                                                                                               errors,
                                                                                               it
                                                                                               is
                                                                                               sufficient
                                                                                               to
                                                                                               record
                                                                                               the
                                                                                               allocation
                                                                                               stack
                                                                                               traces.



                                                                                                     With
                                                                                               none,
                                                                                               no
                                                                                               stack
                                                                                               traces
                                                                                               are
                                                                                               recorded
                                                                                               for
                                                                                               malloc
                                                                                               and
                                                                                               free
                                                                                               operations.
                                                                                               If
                                                                                               your
                                                                                               program
                                                                                               allocates
                                                                                               a
                                                                                               lot
                                                                                               of
                                                                                               blocks
                                                                                               and/or
                                                                                               allocates/frees
                                                                                               from
                                                                                               many
                                                                                               different
                                                                                               stack
                                                                                               traces,
                                                                                               this
                                                                                               can
                                                                                               significantly
                                                                                               decrease
                                                                                               cpu
                                                                                               and/or
                                                                                               memory
                                                                                               required.
                                                                                               Of
                                                                                               course,
                                                                                               few
                                                                                               details
                                                                                               will
                                                                                               be
                                                                                               reported
                                                                                               for
                                                                                               errors
                                                                                               related
                                                                                               to
                                                                                               heap
                                                                                               blocks.



                                                                                                     Note
                                                                                               that
                                                                                               once
                                                                                               a
                                                                                               stack
                                                                                               trace
                                                                                               is
                                                                                               recorded,
                                                                                               Valgrind
                                                                                               keeps
                                                                                               the
                                                                                               stack
                                                                                               trace
                                                                                               in
                                                                                               memory
                                                                                               even
                                                                                               if
                                                                                               it
                                                                                               is
                                                                                               not
                                                                                               referenced
                                                                                               by
                                                                                               any
                                                                                               block.
                                                                                               Some
                                                                                               programs
                                                                                               (for
                                                                                               example,
                                                                                               recursive
                                                                                               algorithms)
                                                                                               can
                                                                                               generate
                                                                                               a
                                                                                               huge
                                                                                               number
                                                                                               of
                                                                                               stack
                                                                                               traces.
                                                                                               If
                                                                                               Valgrind
                                                                                               uses
                                                                                               too
                                                                                               much
                                                                                               memory
                                                                                               in
                                                                                               such
                                                                                               circumstances,
                                                                                               you
                                                                                               can
                                                                                               reduce
                                                                                               the
                                                                                               memory
                                                                                               required
                                                                                               with
                                                                                               the
                                                                                               options
                                                                                               --keep-stacktraces
                                                                                               and/or
                                                                                               by
                                                                                               using
                                                                                               a
                                                                                               smaller
                                                                                               value
                                                                                               for
                                                                                               the
                                                                                               option
                                                                                               --num-callers.



                                                                                                     If
                                                                                               you
                                                                                               want
                                                                                               to
                                                                                               use
                                                                                               --xtree-memory=full
                                                                                               memory
                                                                                               profiling
                                                                                               (see
                                                                                               Execution
                                                                                               Trees),
                                                                                               then
                                                                                               you
                                                                                               cannot
                                                                                               specify
                                                                                               --keep-stacktraces=free
                                                                                               or
                                                                                               --keep-stacktraces=none.



                                                                                                 .RE

                                                                                                 .PP
                                                                                               --freelist-vol=<number>
                                                                                               [default:
                                                                                               20000000]



                                                                                                         When
                                                                                                   the
                                                                                                   client
                                                                                                   program
                                                                                                   releases
                                                                                                   memory
                                                                                                   using
                                                                                                   free
                                                                                                   (in
                                                                                                   C)
                                                                                                   or
                                                                                                   delete
                                                                                                   (C++),
                                                                                                   that
                                                                                                   memory
                                                                                                   is
                                                                                                   not
                                                                                                   immediately
                                                                                                   made
                                                                                                   available
                                                                                                   for
                                                                                                   re-allocation.
                                                                                                   Instead,
                                                                                                   it
                                                                                                   is
                                                                                                   marked
                                                                                                   inaccessible
                                                                                                   and
                                                                                                   placed
                                                                                                   in
                                                                                                   a
                                                                                                   queue
                                                                                                   of
                                                                                                   freed
                                                                                                   blocks.
                                                                                                   The
                                                                                                   purpose
                                                                                                   is
                                                                                                   to
                                                                                                   defer
                                                                                                   as
                                                                                                   long
                                                                                                   as
                                                                                                   possible
                                                                                                   the
                                                                                                   point
                                                                                                   at
                                                                                                   which
                                                                                                   freed-up
                                                                                                   memory
                                                                                                   comes
                                                                                                   back
                                                                                                   into
                                                                                                   circulation.
                                                                                                   This
                                                                                                   increases
                                                                                                   the
                                                                                                   chance
                                                                                                   that
                                                                                                   Memcheck
                                                                                                   will
                                                                                                   be
                                                                                                   able
                                                                                                   to
                                                                                                   detect
                                                                                                   invalid
                                                                                                   accesses
                                                                                                   to
                                                                                                   blocks
                                                                                                   for
                                                                                                   some
                                                                                                   significant
                                                                                                   period
                                                                                                   of
                                                                                                   time
                                                                                                   after
                                                                                                   they
                                                                                                   have
                                                                                                   been
                                                                                                   freed.



                                                                                                         This
                                                                                                   option
                                                                                                   specifies
                                                                                                   the
                                                                                                   maximum
                                                                                                   total
                                                                                                   size,
                                                                                                   in
                                                                                                   bytes,
                                                                                                   of
                                                                                                   the
                                                                                                   blocks
                                                                                                   in
                                                                                                   the
                                                                                                   queue.
                                                                                                   The
                                                                                                   default
                                                                                                   value
                                                                                                   is
                                                                                                   twenty
                                                                                                   million
                                                                                                   bytes.
                                                                                                   Increasing
                                                                                                   this
                                                                                                   increases
                                                                                                   the
                                                                                                   total
                                                                                                   amount
                                                                                                   of
                                                                                                   memory
                                                                                                   used
                                                                                                   by
                                                                                                   Memcheck
                                                                                                   but
                                                                                                   may
                                                                                                   detect
                                                                                                   invalid
                                                                                                   uses
                                                                                                   of
                                                                                                   freed
                                                                                                   blocks
                                                                                                   which
                                                                                                   would
                                                                                                   otherwise
                                                                                                   go
                                                                                                   undetected.


                                                                                                     .RE

                                                                                                     .PP
                                                                                                   --freelist-big-blocks=<number>
                                                                                                   [default:
                                                                                                   1000000]



                                                                                                             When
                                                                                                       making
                                                                                                       blocks
                                                                                                       from
                                                                                                       the
                                                                                                       queue
                                                                                                       of
                                                                                                       freed
                                                                                                       blocks
                                                                                                       available
                                                                                                       for
                                                                                                       re-allocation,
                                                                                                       Memcheck
                                                                                                       will
                                                                                                       in
                                                                                                       priority
                                                                                                       re-circulate
                                                                                                       the
                                                                                                       blocks
                                                                                                       with
                                                                                                       a
                                                                                                       size
                                                                                                       greater
                                                                                                       or
                                                                                                       equal
                                                                                                       to
                                                                                                       --freelist-big-blocks.
                                                                                                       This
                                                                                                       ensures
                                                                                                       that
                                                                                                       freeing
                                                                                                       big
                                                                                                       blocks
                                                                                                       (in
                                                                                                       particular
                                                                                                       freeing
                                                                                                       blocks
                                                                                                       bigger
                                                                                                       than
                                                                                                       --freelist-vol)
                                                                                                       does
                                                                                                       not
                                                                                                       immediately
                                                                                                       lead
                                                                                                       to
                                                                                                       a
                                                                                                       re-circulation
                                                                                                       of
                                                                                                       all
                                                                                                       (or
                                                                                                       a
                                                                                                       lot
                                                                                                       of)
                                                                                                       the
                                                                                                       small
                                                                                                       blocks
                                                                                                       in
                                                                                                       the
                                                                                                       free
                                                                                                       list.
                                                                                                       In
                                                                                                       other
                                                                                                       words,
                                                                                                       this
                                                                                                       option
                                                                                                       increases
                                                                                                       the
                                                                                                       likelihood
                                                                                                       to
                                                                                                       discover
                                                                                                       dangling
                                                                                                       pointers
                                                                                                       for
                                                                                                       the
                                                                                                       "small"
                                                                                                       blocks,
                                                                                                       even
                                                                                                       when
                                                                                                       big
                                                                                                       blocks
                                                                                                       are
                                                                                                       freed.


                                                                                                             Setting
                                                                                                       a
                                                                                                       value
                                                                                                       of
                                                                                                       0
                                                                                                       means
                                                                                                       that
                                                                                                       all
                                                                                                       the
                                                                                                       blocks
                                                                                                       are
                                                                                                       re-circulated
                                                                                                       in
                                                                                                       a
                                                                                                       FIFO
                                                                                                       order.


                                                                                                         .RE

                                                                                                         .PP
                                                                                                       --workaround-gcc296-bugs=<yes|no>
                                                                                                       [default:
                                                                                                       no]



                                                                                                                 When
                                                                                                           enabled,
                                                                                                           assume
                                                                                                           that
                                                                                                           reads
                                                                                                           and
                                                                                                           writes
                                                                                                           some
                                                                                                           small
                                                                                                           distance
                                                                                                           below
                                                                                                           the
                                                                                                           stack
                                                                                                           pointer
                                                                                                           are
                                                                                                           due
                                                                                                           to
                                                                                                           bugs
                                                                                                           in
                                                                                                           GCC
                                                                                                           2.96,
                                                                                                           and
                                                                                                           does
                                                                                                           not
                                                                                                           report
                                                                                                           them.
                                                                                                           The
                                                                                                           "small
                                                                                                           distance"
                                                                                                           is
                                                                                                           256
                                                                                                           bytes
                                                                                                           by
                                                                                                           default.
                                                                                                           Note
                                                                                                           that
                                                                                                           GCC
                                                                                                           2.96
                                                                                                           is
                                                                                                           the
                                                                                                           default
                                                                                                           compiler
                                                                                                           on
                                                                                                           some
                                                                                                           ancient
                                                                                                           Linux
                                                                                                           distributions
                                                                                                           (RedHat
                                                                                                           7.X)
                                                                                                           and
                                                                                                           so
                                                                                                           you
                                                                                                           may
                                                                                                           need
                                                                                                           to
                                                                                                           use
                                                                                                           this
                                                                                                           option.
                                                                                                           Do
                                                                                                           not
                                                                                                           use
                                                                                                           it
                                                                                                           if
                                                                                                           you
                                                                                                           do
                                                                                                           not
                                                                                                           have
                                                                                                           to,
                                                                                                           as
                                                                                                           it
                                                                                                           can
                                                                                                           cause
                                                                                                           real
                                                                                                           errors
                                                                                                           to
                                                                                                           be
                                                                                                           overlooked.
                                                                                                           A
                                                                                                           better
                                                                                                           alternative
                                                                                                           is
                                                                                                           to
                                                                                                           use
                                                                                                           a
                                                                                                           more
                                                                                                           recent
                                                                                                           GCC
                                                                                                           in
                                                                                                           which
                                                                                                           this
                                                                                                           bug
                                                                                                           is
                                                                                                           fixed.



                                                                                                                 You
                                                                                                           may
                                                                                                           also
                                                                                                           need
                                                                                                           to
                                                                                                           use
                                                                                                           this
                                                                                                           option
                                                                                                           when
                                                                                                           working
                                                                                                           with
                                                                                                           GCC
                                                                                                           3.X
                                                                                                           or
                                                                                                           4.X
                                                                                                           on
                                                                                                           32-bit
                                                                                                           PowerPC
                                                                                                           Linux.
                                                                                                           This
                                                                                                           is
                                                                                                           because
                                                                                                           GCC
                                                                                                           generates
                                                                                                           code
                                                                                                           which
                                                                                                           occasionally
                                                                                                           accesses
                                                                                                           below
                                                                                                           the
                                                                                                           stack
                                                                                                           pointer,
                                                                                                           particularly
                                                                                                           for
                                                                                                           floating-point
                                                                                                           to/from
                                                                                                           integer
                                                                                                           conversions.
                                                                                                           This
                                                                                                           is
                                                                                                           in
                                                                                                           violation
                                                                                                           of
                                                                                                           the
                                                                                                           32-bit
                                                                                                           PowerPC
                                                                                                           ELF
                                                                                                           specification,
                                                                                                           which
                                                                                                           makes
                                                                                                           no
                                                                                                           provision
                                                                                                           for
                                                                                                           locations
                                                                                                           below
                                                                                                           the
                                                                                                           stack
                                                                                                           pointer
                                                                                                           to
                                                                                                           be
                                                                                                           accessible.



                                                                                                                 This
                                                                                                           option
                                                                                                           is
                                                                                                           deprecated
                                                                                                           as
                                                                                                           of
                                                                                                           version
                                                                                                           3.12
                                                                                                           and
                                                                                                           may
                                                                                                           be
                                                                                                           removed
                                                                                                           from
                                                                                                           future
                                                                                                           versions.
                                                                                                           You
                                                                                                           should
                                                                                                           instead
                                                                                                           use
                                                                                                           --ignore-range-below-sp
                                                                                                           to
                                                                                                           specify
                                                                                                           the
                                                                                                           exact
                                                                                                           range
                                                                                                           of
                                                                                                           offsets
                                                                                                           below
                                                                                                           the
                                                                                                           stack
                                                                                                           pointer
                                                                                                           that
                                                                                                           should
                                                                                                           be
                                                                                                           ignored.
                                                                                                           A
                                                                                                           suitable
                                                                                                           equivalent
                                                                                                           is
                                                                                                           --ignore-range-below-sp=1024-1.


                                                                                                             .RE

                                                                                                             .PP
                                                                                                           --ignore-range-below-sp=<number>-<number>



                                                                                                                     This
                                                                                                               is
                                                                                                               a
                                                                                                               more
                                                                                                               general
                                                                                                               replacement
                                                                                                               for
                                                                                                               the
                                                                                                               deprecated
                                                                                                               --workaround-gcc296-bugs
                                                                                                               option.
                                                                                                               When
                                                                                                               specified,
                                                                                                               it
                                                                                                               causes
                                                                                                               Memcheck
                                                                                                               not
                                                                                                               to
                                                                                                               report
                                                                                                               errors
                                                                                                               for
                                                                                                               accesses
                                                                                                               at
                                                                                                               the
                                                                                                               specified
                                                                                                               offsets
                                                                                                               below
                                                                                                               the
                                                                                                               stack
                                                                                                               pointer.
                                                                                                               The
                                                                                                               two
                                                                                                               offsets
                                                                                                               must
                                                                                                               be
                                                                                                               positive
                                                                                                               decimal
                                                                                                               numbers
                                                                                                               and
                                                                                                               --
                                                                                                               somewhat
                                                                                                               counterintuitively
                                                                                                               --
                                                                                                               the
                                                                                                               first
                                                                                                               one
                                                                                                               must
                                                                                                               be
                                                                                                               larger,
                                                                                                               in
                                                                                                               order
                                                                                                               to
                                                                                                               imply
                                                                                                               a
                                                                                                               non-wraparound
                                                                                                               address
                                                                                                               range
                                                                                                               to
                                                                                                               ignore.
                                                                                                               For
                                                                                                               example,
                                                                                                               to
                                                                                                               ignore
                                                                                                               4
                                                                                                               byte
                                                                                                               accesses
                                                                                                               at
                                                                                                               8192
                                                                                                               bytes
                                                                                                               below
                                                                                                               the
                                                                                                               stack
                                                                                                               pointer,
                                                                                                               use
                                                                                                               --ignore-range-below-sp=8192-8189.
                                                                                                               Only
                                                                                                               one
                                                                                                               range
                                                                                                               may
                                                                                                               be
                                                                                                               specified.


                                                                                                                 .RE

                                                                                                                 .PP
                                                                                                               --show-mismatched-frees=<yes|no>
                                                                                                               [default:
                                                                                                               yes]



                                                                                                                         When
                                                                                                                   enabled,
                                                                                                                   Memcheck
                                                                                                                   checks
                                                                                                                   that
                                                                                                                   heap
                                                                                                                   blocks
                                                                                                                   are
                                                                                                                   deallocated
                                                                                                                   using
                                                                                                                   a
                                                                                                                   function
                                                                                                                   that
                                                                                                                   matches
                                                                                                                   the
                                                                                                                   allocating
                                                                                                                   function.
                                                                                                                   That
                                                                                                                   is,
                                                                                                                   it
                                                                                                                   expects
                                                                                                                   free
                                                                                                                   to
                                                                                                                   be
                                                                                                                   used
                                                                                                                   to
                                                                                                                   deallocate
                                                                                                                   blocks
                                                                                                                   allocated
                                                                                                                   by
                                                                                                                   malloc,
                                                                                                                   delete
                                                                                                                   for
                                                                                                                   blocks
                                                                                                                   allocated
                                                                                                                   by
                                                                                                                   new,
                                                                                                                   and
                                                                                                                   delete[]
                                                                                                                   for
                                                                                                                   blocks
                                                                                                                   allocated
                                                                                                                   by
                                                                                                                   new[].
                                                                                                                   If
                                                                                                                   a
                                                                                                                   mismatch
                                                                                                                   is
                                                                                                                   detected,
                                                                                                                   an
                                                                                                                   error
                                                                                                                   is
                                                                                                                   reported.
                                                                                                                   This
                                                                                                                   is
                                                                                                                   in
                                                                                                                   general
                                                                                                                   important
                                                                                                                   because
                                                                                                                   in
                                                                                                                   some
                                                                                                                   environments,
                                                                                                                   freeing
                                                                                                                   with
                                                                                                                   a
                                                                                                                   non-matching
                                                                                                                   function
                                                                                                                   can
                                                                                                                   cause
                                                                                                                   crashes.



                                                                                                                         There
                                                                                                                   is
                                                                                                                   however
                                                                                                                   a
                                                                                                                   scenario
                                                                                                                   where
                                                                                                                   such
                                                                                                                   mismatches
                                                                                                                   cannot
                                                                                                                   be
                                                                                                                   avoided.
                                                                                                                   That
                                                                                                                   is
                                                                                                                   when
                                                                                                                   the
                                                                                                                   user
                                                                                                                   provides
                                                                                                                   implementations
                                                                                                                   of
                                                                                                                   new/new[]
                                                                                                                   that
                                                                                                                   call
                                                                                                                   malloc
                                                                                                                   and
                                                                                                                   of
                                                                                                                   delete/delete[]
                                                                                                                   that
                                                                                                                   call
                                                                                                                   free,
                                                                                                                   and
                                                                                                                   these
                                                                                                                   functions
                                                                                                                   are
                                                                                                                   asymmetrically
                                                                                                                   inlined.
                                                                                                                   For
                                                                                                                   example,
                                                                                                                   imagine
                                                                                                                   that
                                                                                                                   delete[]
                                                                                                                   is
                                                                                                                   inlined
                                                                                                                   but
                                                                                                                   new[]
                                                                                                                   is
                                                                                                                   not.
                                                                                                                   The
                                                                                                                   result
                                                                                                                   is
                                                                                                                   that
                                                                                                                   Memcheck
                                                                                                                   "sees"
                                                                                                                   all
                                                                                                                   delete[]
                                                                                                                   calls
                                                                                                                   as
                                                                                                                   direct
                                                                                                                   calls
                                                                                                                   to
                                                                                                                   free,
                                                                                                                   even
                                                                                                                   when
                                                                                                                   the
                                                                                                                   program
                                                                                                                   source
                                                                                                                   contains
                                                                                                                   no
                                                                                                                   mismatched
                                                                                                                   calls.



                                                                                                                         This
                                                                                                                   causes
                                                                                                                   a
                                                                                                                   lot
                                                                                                                   of
                                                                                                                   confusing
                                                                                                                   and
                                                                                                                   irrelevant
                                                                                                                   error
                                                                                                                   reports.
                                                                                                                   --show-mismatched-frees=no
                                                                                                                   disables
                                                                                                                   these
                                                                                                                   checks.
                                                                                                                   It
                                                                                                                   is
                                                                                                                   not
                                                                                                                   generally
                                                                                                                   advisable
                                                                                                                   to
                                                                                                                   disable
                                                                                                                   them,
                                                                                                                   though,
                                                                                                                   because
                                                                                                                   you
                                                                                                                   may
                                                                                                                   miss
                                                                                                                   real
                                                                                                                   errors
                                                                                                                   as
                                                                                                                   a
                                                                                                                   result.


                                                                                                                     .RE

                                                                                                                     .PP
                                                                                                                   --ignore-ranges=0xPP-0xQQ[,0xRR-0xSS]



                                                                                                                           Any
                                                                                                                       ranges
                                                                                                                       listed
                                                                                                                       in
                                                                                                                       this
                                                                                                                       option
                                                                                                                       (and
                                                                                                                       multiple
                                                                                                                       ranges
                                                                                                                       can
                                                                                                                       be
                                                                                                                       specified,
                                                                                                                       separated
                                                                                                                       by
                                                                                                                       commas)
                                                                                                                       will
                                                                                                                       be
                                                                                                                       ignored
                                                                                                                       by
                                                                                                                       Memcheck's
                                                                                                                       addressability
                                                                                                                       checking.


                                                                                                                         .RE

                                                                                                                         .PP
                                                                                                                       --malloc-fill=<hexnumber>



                                                                                                                                 Fills
                                                                                                                           blocks
                                                                                                                           allocated
                                                                                                                           by
                                                                                                                           malloc,
                                                                                                                           new,
                                                                                                                           etc,
                                                                                                                           but
                                                                                                                           not
                                                                                                                           by
                                                                                                                           calloc,
                                                                                                                           with
                                                                                                                           the
                                                                                                                           specified
                                                                                                                           byte.
                                                                                                                           This
                                                                                                                           can
                                                                                                                           be
                                                                                                                           useful
                                                                                                                           when
                                                                                                                           trying
                                                                                                                           to
                                                                                                                           shake
                                                                                                                           out
                                                                                                                           obscure
                                                                                                                           memory
                                                                                                                           corruption
                                                                                                                           problems.
                                                                                                                           The
                                                                                                                           allocated
                                                                                                                           area
                                                                                                                           is
                                                                                                                           still
                                                                                                                           regarded
                                                                                                                           by
                                                                                                                           Memcheck
                                                                                                                           as
                                                                                                                           undefined
                                                                                                                           --
                                                                                                                           this
                                                                                                                           option
                                                                                                                           only
                                                                                                                           affects
                                                                                                                           its
                                                                                                                           contents.
                                                                                                                           Note
                                                                                                                           that
                                                                                                                           --malloc-fill
                                                                                                                           does
                                                                                                                           not
                                                                                                                           affect
                                                                                                                           a
                                                                                                                           block
                                                                                                                           of
                                                                                                                           memory
                                                                                                                           when
                                                                                                                           it
                                                                                                                           is
                                                                                                                           used
                                                                                                                           as
                                                                                                                           argument
                                                                                                                           to
                                                                                                                           client
                                                                                                                           requests
                                                                                                                           VALGRIND_MEMPOOL_ALLOC
                                                                                                                           or
                                                                                                                           VALGRIND_MALLOCLIKE_BLOCK.


                                                                                                                             .RE

                                                                                                                             .PP
                                                                                                                           --free-fill=<hexnumber>



                                                                                                                                     Fills
                                                                                                                               blocks
                                                                                                                               freed
                                                                                                                               by
                                                                                                                               free,
                                                                                                                               delete,
                                                                                                                               etc,
                                                                                                                               with
                                                                                                                               the
                                                                                                                               specified
                                                                                                                               byte
                                                                                                                               value.
                                                                                                                               This
                                                                                                                               can
                                                                                                                               be
                                                                                                                               useful
                                                                                                                               when
                                                                                                                               trying
                                                                                                                               to
                                                                                                                               shake
                                                                                                                               out
                                                                                                                               obscure
                                                                                                                               memory
                                                                                                                               corruption
                                                                                                                               problems.
                                                                                                                               The
                                                                                                                               freed
                                                                                                                               area
                                                                                                                               is
                                                                                                                               still
                                                                                                                               regarded
                                                                                                                               by
                                                                                                                               Memcheck
                                                                                                                               as
                                                                                                                               not
                                                                                                                               valid
                                                                                                                               for
                                                                                                                               access
                                                                                                                               --
                                                                                                                               this
                                                                                                                               option
                                                                                                                               only
                                                                                                                               affects
                                                                                                                               its
                                                                                                                               contents.
                                                                                                                               Note
                                                                                                                               that
                                                                                                                               --free-fill
                                                                                                                               does
                                                                                                                               not
                                                                                                                               affect
                                                                                                                               a
                                                                                                                               block
                                                                                                                               of
                                                                                                                               memory
                                                                                                                               when
                                                                                                                               it
                                                                                                                               is
                                                                                                                               used
                                                                                                                               as
                                                                                                                               argument
                                                                                                                               to
                                                                                                                               client
                                                                                                                               requests
                                                                                                                               VALGRIND_MEMPOOL_FREE
                                                                                                                               or
                                                                                                                               VALGRIND_FREELIKE_BLOCK.


                                                                                                                                 .RE







CACHEGRIND OPTIONS
         .PP --I1=<size>,<associativity>,<line size>



                 Specify the size, associativity and line size of the level 1
           instruction cache.


             .RE

             .PP --D1=<size>,<associativity>,<line size>



                     Specify the size, associativity and line size of the
               level 1 data cache.


                 .RE

                 .PP --LL=<size>,<associativity>,<line size>



                         Specify the size, associativity and line size of the
                   last-level cache.


                     .RE

                     .PP --cache-sim=no|yes [yes]



                             Enables or disables collection of cache access
                       and miss counts.


                         .RE

                         .PP --branch-sim=no|yes [no]



                                 Enables or disables collection of branch
                           instruction and misprediction counts. By default
                           this is disabled as it slows Cachegrind down by
                           approximately 25%. Note that you cannot specify
                           --cache-sim=no and --branch-sim=no together, as
                           that would leave Cachegrind with no information to
                           collect.


                             .RE

                             .PP --cachegrind-out-file=<file>



                                     Write the profile data to file rather
                               than to the default output file,
                               cachegrind.out.<pid>. The %p and %q format
                               specifiers can be used to embed the process ID
                               and/or the contents of an environment variable
                               in the name, as is the case for the core option
                               --log-file.


                                 .RE







CALLGRIND OPTIONS
         .PP --callgrind-out-file=<file>



                 Write the profile data to file rather than to the default
           output file, callgrind.out.<pid>. The %p and %q format specifiers
           can be used to embed the process ID and/or the contents of an
           environment variable in the name, as is the case for the core
           option --log-file. When multiple dumps are made, the file name is
           modified further; see below.


             .RE

             .PP --dump-line=<no|yes> [default: yes]



                     This specifies that event counting should be performed at
               source line granularity. This allows source annotation for
               sources which are compiled with debug information (-g).


                 .RE

                 .PP --dump-instr=<no|yes> [default: no]



                         This specifies that event counting should be
                   performed at per-instruction granularity. This allows for
                   assembly code annotation. Currently the results can only be
                   displayed by KCachegrind.


                     .RE

                     .PP --compress-strings=<no|yes> [default: yes]



                             This option influences the output format of the
                       profile data. It specifies whether strings (file and
                       function names) should be identified by numbers. This
                       shrinks the file, but makes it more difficult for
                       humans to read (which is not recommended in any case).


                         .RE

                         .PP --compress-pos=<no|yes> [default: yes]



                                 This option influences the output format of
                           the profile data. It specifies whether numerical
                           positions are always specified as absolute values
                           or are allowed to be relative to previous numbers.
                           This shrinks the file size.


                             .RE

                             .PP --combine-dumps=<no|yes> [default: no]



                                     When enabled, when multiple profile data
                               parts are to be generated these parts are
                               appended to the same output file. Not
                               recommended.


                                 .RE





                                 .PP --dump-every-bb=<count> [default: 0,
                               never]



                                         Dump profile data every count basic
                                   blocks. Whether a dump is needed is only
                                   checked when Valgrind's internal scheduler
                                   is run. Therefore, the minimum setting
                                   useful is about 100000. The count is a
                                   64-bit value to make long dump periods
                                   possible.


                                     .RE

                                     .PP --dump-before=<function>



                                             Dump when entering function.


                                         .RE

                                         .PP --zero-before=<function>



                                                 Zero all costs when entering
                                           function.


                                             .RE

                                             .PP --dump-after=<function>



                                                     Dump when leaving
                                               function.


                                                 .RE





                                                 .PP --instr-atstart=<yes|no>
                                               [default: yes]



                                                         Specify if you want
                                                   Callgrind to start
                                                   simulation and profiling
                                                   from the beginning of the
                                                   program. When set to no,
                                                   Callgrind will not be able
                                                   to collect any information,
                                                   including calls, but it
                                                   will have at most a
                                                   slowdown of around 4, which
                                                   is the minimum Valgrind
                                                   overhead. Instrumentation
                                                   can be interactively
                                                   enabled via
                                                   callgrind_control -i on.


                                                         Note that the
                                                   resulting call graph will
                                                   most probably not contain
                                                   main, but will contain all
                                                   the functions executed
                                                   after instrumentation was
                                                   enabled. Instrumentation
                                                   can also be
                                                   programmatically
                                                   enabled/disabled. See the
                                                   Callgrind include file
                                                   callgrind.h for the macro
                                                   you have to use in your
                                                   source code.

                                                    For cache simulation,
                                                   results will be less
                                                   accurate when switching on
                                                   instrumentation later in
                                                   the program run, as the
                                                   simulator starts with an
                                                   empty cache at that moment.
                                                   Switch on event collection
                                                   later to cope with this
                                                   error.


                                                     .RE

                                                     .PP
                                                   --collect-atstart=<yes|no>
                                                   [default: yes]



                                                             Specify whether
                                                       event collection is
                                                       enabled at beginning of
                                                       the profile run.


                                                             To only look at
                                                       parts of your program,
                                                       you have two
                                                       possibilities:




                                                        1.
                                                                   Zero event
                                                           counters before
                                                           entering the
                                                           program part you
                                                           want to profile,
                                                           and dump the event
                                                           counters to a file
                                                           after leaving that
                                                           program part.

                                                                   .RE



                                                            2.
                                                                         Switch
                                                               on/off
                                                               collection
                                                               state as needed
                                                               to only see
                                                               event counters
                                                               happening while
                                                               inside of the
                                                               program part
                                                               you want to
                                                               profile.

                                                                       .RE

                                                                     .sp

                                                                     The
                                                               second option
                                                               can be used if
                                                               the program
                                                               part you want
                                                               to profile is
                                                               called many
                                                               times. Option
                                                               1, i.e.
                                                               creating a lot
                                                               of dumps is not
                                                               practical here.


                                                                     Collection
                                                               state can be
                                                               toggled at
                                                               entry and exit
                                                               of a given
                                                               function with
                                                               the option
                                                               --toggle-collect.
                                                               If you use this
                                                               option,
                                                               collection
                                                               state should be
                                                               disabled at the
                                                               beginning. Note
                                                               that the
                                                               specification
                                                               of
                                                               --toggle-collect
                                                               implicitly sets
                                                               --collect-state=no.


                                                                     Collection
                                                               state can be
                                                               toggled also by
                                                               inserting the
                                                               client request
                                                               CALLGRIND_TOGGLE_COLLECT
                                                               ; at the needed
                                                               code positions.


                                                                 .RE

                                                                 .PP
                                                               --toggle-collect=<function>



                                                                         Toggle
                                                                   collection
                                                                   on
                                                                   entry/exit
                                                                   of
                                                                   function.


                                                                     .RE

                                                                     .PP
                                                                   --collect-jumps=<no|yes>
                                                                   [default:
                                                                   no]



                                                                             This
                                                                       specifies
                                                                       whether
                                                                       information
                                                                       for
                                                                       (conditional)
                                                                       jumps
                                                                       should
                                                                       be
                                                                       collected.
                                                                       As
                                                                       above,
                                                                       callgrind_annotate
                                                                       currently
                                                                       is not
                                                                       able to
                                                                       show
                                                                       you the
                                                                       data.
                                                                       You
                                                                       have to
                                                                       use
                                                                       KCachegrind
                                                                       to get
                                                                       jump
                                                                       arrows
                                                                       in the
                                                                       annotated
                                                                       code.


                                                                         .RE

                                                                         .PP
                                                                       --collect-systime=<no|yes|msec|usec|nsec>
                                                                       [default:
                                                                       no]



                                                                                 This
                                                                           specifies
                                                                           whether
                                                                           information
                                                                           for
                                                                           system
                                                                           call
                                                                           times
                                                                           should
                                                                           be
                                                                           collected.


                                                                                 The
                                                                           value
                                                                           no
                                                                           indicates
                                                                           to
                                                                           record
                                                                           no
                                                                           system
                                                                           call
                                                                           information.


                                                                                 The
                                                                           other
                                                                           values
                                                                           indicate
                                                                           to
                                                                           record
                                                                           the
                                                                           number
                                                                           of
                                                                           system
                                                                           calls
                                                                           done
                                                                           (sysCount
                                                                           event)
                                                                           and
                                                                           the
                                                                           elapsed
                                                                           time
                                                                           (sysTime
                                                                           event)
                                                                           spent
                                                                           in
                                                                           system
                                                                           calls.
                                                                           The
                                                                           --collect-systime
                                                                           value
                                                                           gives
                                                                           the
                                                                           unit
                                                                           used
                                                                           for
                                                                           sysTime
                                                                           :
                                                                           milli
                                                                           seconds,
                                                                           micro
                                                                           seconds
                                                                           or
                                                                           nano
                                                                           seconds.
                                                                           With
                                                                           the
                                                                           value
                                                                           nsec,
                                                                           callgrind
                                                                           also
                                                                           records
                                                                           the
                                                                           cpu
                                                                           time
                                                                           spent
                                                                           during
                                                                           system
                                                                           calls
                                                                           (sysCpuTime).


                                                                                 The
                                                                           value
                                                                           yes
                                                                           is
                                                                           a
                                                                           synonym
                                                                           of
                                                                           msec.
                                                                           The
                                                                           value
                                                                           nsec
                                                                           is
                                                                           not
                                                                           supported
                                                                           on
                                                                           Darwin.


                                                                             .RE

                                                                             .PP
                                                                           --collect-bus=<no|yes>
                                                                           [default:
                                                                           no]



                                                                                     This
                                                                               specifies
                                                                               whether
                                                                               the
                                                                               number
                                                                               of
                                                                               global
                                                                               bus
                                                                               events
                                                                               executed
                                                                               should
                                                                               be
                                                                               collected.
                                                                               The
                                                                               event
                                                                               type
                                                                               "Ge"
                                                                               is
                                                                               used
                                                                               for
                                                                               these
                                                                               events.


                                                                                 .RE





                                                                                 .PP
                                                                               --cache-sim=<yes|no>
                                                                               [default:
                                                                               no]



                                                                                         Specify
                                                                                   if
                                                                                   you
                                                                                   want
                                                                                   to
                                                                                   do
                                                                                   full
                                                                                   cache
                                                                                   simulation.
                                                                                   By
                                                                                   default,
                                                                                   only
                                                                                   instruction
                                                                                   read
                                                                                   accesses
                                                                                   will
                                                                                   be
                                                                                   counted
                                                                                   ("Ir").
                                                                                   With
                                                                                   cache
                                                                                   simulation,
                                                                                   further
                                                                                   event
                                                                                   counters
                                                                                   are
                                                                                   enabled:
                                                                                   Cache
                                                                                   misses
                                                                                   on
                                                                                   instruction
                                                                                   reads
                                                                                   ("I1mr"/"ILmr"),
                                                                                   data
                                                                                   read
                                                                                   accesses
                                                                                   ("Dr")
                                                                                   and
                                                                                   related
                                                                                   cache
                                                                                   misses
                                                                                   ("D1mr"/"DLmr"),
                                                                                   data
                                                                                   write
                                                                                   accesses
                                                                                   ("Dw")
                                                                                   and
                                                                                   related
                                                                                   cache
                                                                                   misses
                                                                                   ("D1mw"/"DLmw").
                                                                                   For
                                                                                   more
                                                                                   information,
                                                                                   see
                                                                                   Cachegrind:
                                                                                   a
                                                                                   cache
                                                                                   and
                                                                                   branch-
                                                                                   prediction
                                                                                   profiler.


                                                                                     .RE

                                                                                     .PP
                                                                                   --branch-sim=<yes|no>
                                                                                   [default:
                                                                                   no]



                                                                                             Specify
                                                                                       if
                                                                                       you
                                                                                       want
                                                                                       to
                                                                                       do
                                                                                       branch
                                                                                       prediction
                                                                                       simulation.
                                                                                       Further
                                                                                       event
                                                                                       counters
                                                                                       are
                                                                                       enabled:
                                                                                       Number
                                                                                       of
                                                                                       executed
                                                                                       conditional
                                                                                       branches
                                                                                       and
                                                                                       related
                                                                                       predictor
                                                                                       misses
                                                                                       ("Bc"/"Bcm"),
                                                                                       executed
                                                                                       indirect
                                                                                       jumps
                                                                                       and
                                                                                       related
                                                                                       misses
                                                                                       of
                                                                                       the
                                                                                       jump
                                                                                       address
                                                                                       predictor
                                                                                       ("Bi"/"Bim").


                                                                                         .RE






HELGRIND OPTIONS
         .PP --free-is-write=no|yes [default: no]



                 When enabled (not the default), Helgrind treats freeing of
           heap memory as if the memory was written immediately before the
           free. This exposes races where memory is referenced by one thread,
           and freed by another, but there is no observable synchronisation
           event to ensure that the reference happens before the free.


                 This functionality is new in Valgrind 3.7.0, and is regarded
           as experimental. It is not enabled by default because its
           interaction with custom memory allocators is not well understood at
           present. User feedback is welcomed.


             .RE

             .PP --track-lockorders=no|yes [default: yes]



                     When enabled (the default), Helgrind performs lock order
               consistency checking. For some buggy programs, the large number
               of lock order errors reported can become annoying, particularly
               if you're only interested in race errors. You may therefore
               find it helpful to disable lock order checking.


                 .RE

                 .PP --history-level=none|approx|full [default: full]



                         --history-level=full (the default) causes Helgrind
                   collects enough information about "old" accesses that it
                   can produce two stack traces in a race report -- both the
                   stack trace for the current access, and the trace for the
                   older, conflicting access. To limit memory usage, "old"
                   accesses stack traces are limited to a maximum of 8
                   entries, even if --num-callers value is bigger.


                         Collecting such information is expensive in both
                   speed and memory, particularly for programs that do many
                   inter-thread synchronisation events (locks, unlocks, etc).
                   Without such information, it is more difficult to track
                   down the root causes of races. Nonetheless, you may not
                   need it in situations where you just want to check for the
                   presence or absence of races, for example, when doing
                   regression testing of a previously race-free program.


                         --history-level=none is the opposite extreme. It
                   causes Helgrind not to collect any information about
                   previous accesses. This can be dramatically faster than
                   --history-level=full.


                         --history-level=approx provides a compromise between
                   these two extremes. It causes Helgrind to show a full trace
                   for the later access, and approximate information regarding
                   the earlier access. This approximate information consists
                   of two stacks, and the earlier access is guaranteed to have
                   occurred somewhere between program points denoted by the
                   two stacks. This is not as useful as showing the exact
                   stack for the previous access (as --history-level=full
                   does), but it is better than nothing, and it is almost as
                   fast as --history-level=none.


                     .RE

                     .PP --delta-stacktrace=no|yes [default: yes on linux
                   amd64/x86]



                             This flag only has any effect at
                       --history-level=full.


                             --delta-stacktrace configures the way Helgrind
                       captures the stacktraces for the option
                       --history-level=full. Such a stacktrace is typically
                       needed each time a new piece of memory is read or
                       written in a basic block of instructions.


                             --delta-stacktrace=no causes Helgrind to compute
                       a full history stacktrace from the unwind info each
                       time a stacktrace is needed.


                             --delta-stacktrace=yes indicates to Helgrind to
                       derive a new stacktrace from the previous stacktrace,
                       as long as there was no call instruction, no return
                       instruction, or any other instruction changing the call
                       stack since the previous stacktrace was captured. If no
                       such instruction was executed, the new stacktrace can
                       be derived from the previous stacktrace by just
                       changing the top frame to the current program counter.
                       This option can speed up Helgrind by 25% when using
                       --history-level=full.


                             The following aspects have to be considered when
                       using --delta-stacktrace=yes :



                       •   In some cases (for example in a function prologue),
                           the valgrind unwinder might not properly unwind the
                           stack, due to some limitations and/or due to wrong
                           unwind info. When using --delta-stacktrace=yes, the
                           wrong stack trace captured in the function prologue
                           will be kept till the next call or return.


                       •   On the other hand, --delta-stacktrace=yes sometimes
                           helps to obtain a correct stacktrace, for example
                           when the unwind info allows a correct stacktrace to
                           be done in the beginning of the sequence, but not
                           later on in the instruction sequence.


                       •   Determining which instructions are changing the
                           callstack is partially based on platform dependent
                           heuristics, which have to be tuned/validated
                           specifically for the platform. Also, unwinding in a
                           function prologue must be good enough to allow
                           using --delta-stacktrace=yes. Currently, the option
                           --delta-stacktrace=yes has been reasonably
                           validated only on linux x86 32 bits and linux amd64
                           64 bits. For more details about how to validate
                           --delta-stacktrace=yes, see debug option
                           --hg-sanity-flags and the function
                           check_cached_rcec_ok in libhb_core.c.
                               .sp



                         .RE

                         .PP --conflict-cache-size=N [default: 1000000]



                                 This flag only has any effect at
                           --history-level=full.


                                 Information about "old" conflicting accesses
                           is stored in a cache of limited size, with
                           LRU-style management. This is necessary because it
                           isn't practical to store a stack trace for every
                           single memory access made by the program.
                           Historical information on not recently accessed
                           locations is periodically discarded, to free up
                           space in the cache.


                                 This option controls the size of the cache,
                           in terms of the number of different memory
                           addresses for which conflicting access information
                           is stored. If you find that Helgrind is showing
                           race errors with only one stack instead of the
                           expected two stacks, try increasing this value.


                                 The minimum value is 10,000 and the maximum
                           is 30,000,000 (thirty times the default value).
                           Increasing the value by 1 increases Helgrind's
                           memory requirement by very roughly 100 bytes, so
                           the maximum value will easily eat up three extra
                           gigabytes or so of memory.


                             .RE

                             .PP --check-stack-refs=no|yes [default: yes]



                                     By default Helgrind checks all data
                               memory accesses made by your program. This flag
                               enables you to skip checking for accesses to
                               thread stacks (local variables). This can
                               improve performance, but comes at the cost of
                               missing races on stack-allocated data.


                                 .RE

                                 .PP --ignore-thread-creation=<yes|no>
                               [default: no]



                                         Controls whether all activities
                                   during thread creation should be ignored.
                                   By default enabled only on Solaris. Solaris
                                   provides higher throughput, parallelism and
                                   scalability than other operating systems,
                                   at the cost of more fine-grained locking
                                   activity. This means for example that when
                                   a thread is created under glibc, just one
                                   big lock is used for all thread setup.
                                   Solaris libc uses several fine-grained
                                   locks and the creator thread resumes its
                                   activities as soon as possible, leaving for
                                   example stack and TLS setup sequence to the
                                   created thread. This situation confuses
                                   Helgrind as it assumes there is some false
                                   ordering in place between creator and
                                   created thread; and therefore many types of
                                   race conditions in the application would
                                   not be reported. To prevent such false
                                   ordering, this command line option is set
                                   to yes by default on Solaris. All activity
                                   (loads, stores, client requests) is
                                   therefore ignored during:




                                   •
                                                 pthread_create() call in the
                                       creator thread

                                               .RE


                                       •
                                                     thread creation phase
                                           (stack and TLS setup) in the
                                           created thread

                                                   .RE
                                                 .sp

                                                 Also new memory allocated
                                           during thread creation is
                                           untracked, that is race reporting
                                           is suppressed there. DRD does the
                                           same thing implicitly. This is
                                           necessary because Solaris libc
                                           caches many objects and reuses them
                                           for different threads and that
                                           confuses Helgrind.


                                             .RE








DRD OPTIONS
         .PP --check-stack-var=<yes|no> [default: no]



                 Controls whether DRD detects data races on stack variables.
           Verifying stack variables is disabled by default because most
           programs do not share stack variables over threads.


             .RE
             .PP --exclusive-threshold=<n> [default: off]



                     Print an error message if any mutex or writer lock has
               been held longer than the time specified in milliseconds. This
               option enables the detection of lock contention.


                 .RE
                 .PP --join-list-vol=<n> [default: 10]



                         Data races that occur between a statement at the end
                   of one thread and another thread can be missed if memory
                   access information is discarded immediately after a thread
                   has been joined. This option allows one to specify for how
                   many joined threads memory access information should be
                   retained.


                     .RE
                     .PP
                    --first-race-only=<yes|no> [default: no]



                             Whether to report only the first data race that
                       has been detected on a memory location or all data
                       races that have been detected on a memory location.


                         .RE
                         .PP
                        --free-is-write=<yes|no> [default: no]



                                 Whether to report races between accessing
                           memory and freeing memory. Enabling this option may
                           cause DRD to run slightly slower. Notes:




                           •           Don't enable this option when using
                               custom memory allocators that use the
                               VG_USERREQ__MALLOCLIKE_BLOCK and
                               VG_USERREQ__FREELIKE_BLOCK because that would
                               result in false positives.

                                    .RE

                               •           Don't enable this option when using
                                   reference-counted objects because that will
                                   result in false positives, even when that
                                   code has been annotated properly with
                                   ANNOTATE_HAPPENS_BEFORE and
                                   ANNOTATE_HAPPENS_AFTER. See e.g. the output
                                   of the following command for an example:
                                   valgrind --tool=drd --free-is-write=yes
                                   drd/tests/annotate_smart_pointer.

                                        .RE
                                         .sp


                                     .RE
                                     .PP
                                    --report-signal-unlocked=<yes|no>
                                   [default: yes]



                                             Whether to report calls to
                                       pthread_cond_signal and
                                       pthread_cond_broadcast where the mutex
                                       associated with the signal through
                                       pthread_cond_wait or
                                       pthread_cond_timed_waitis not locked at
                                       the time the signal is sent. Sending a
                                       signal without holding a lock on the
                                       associated mutex is a common
                                       programming error which can cause
                                       subtle race conditions and
                                       unpredictable behavior. There exist
                                       some uncommon synchronization patterns
                                       however where it is safe to send a
                                       signal without holding a lock on the
                                       associated mutex.


                                         .RE
                                         .PP --segment-merging=<yes|no>
                                       [default: yes]



                                                 Controls segment merging.
                                           Segment merging is an algorithm to
                                           limit memory usage of the data race
                                           detection algorithm. Disabling
                                           segment merging may improve the
                                           accuracy of the so-called 'other
                                           segments' displayed in race reports
                                           but can also trigger an out of
                                           memory error.


                                             .RE
                                             .PP
                                           --segment-merging-interval=<n>
                                           [default: 10]



                                                     Perform segment merging
                                               only after the specified number
                                               of new segments have been
                                               created. This is an advanced
                                               configuration option that
                                               allows one to choose whether to
                                               minimize DRD's memory usage by
                                               choosing a low value or to let
                                               DRD run faster by choosing a
                                               slightly higher value. The
                                               optimal value for this
                                               parameter depends on the
                                               program being analyzed. The
                                               default value works well for
                                               most programs.


                                                 .RE
                                                 .PP --shared-threshold=<n>
                                               [default: off]



                                                         Print an error
                                                   message if a reader lock
                                                   has been held longer than
                                                   the specified time (in
                                                   milliseconds). This option
                                                   enables the detection of
                                                   lock contention.


                                                     .RE
                                                     .PP
                                                   --show-confl-seg=<yes|no>
                                                   [default: yes]



                                                             Show conflicting
                                                       segments in race
                                                       reports. Since this
                                                       information can help to
                                                       find the cause of a
                                                       data race, this option
                                                       is enabled by default.
                                                       Disabling this option
                                                       makes the output of DRD
                                                       more compact.


                                                         .RE
                                                         .PP
                                                       --show-stack-usage=<yes|no>
                                                       [default: no]



                                                                 Print stack
                                                           usage at thread
                                                           exit time. When a
                                                           program creates a
                                                           large number of
                                                           threads it becomes
                                                           important to limit
                                                           the amount of
                                                           virtual memory
                                                           allocated for
                                                           thread stacks. This
                                                           option makes it
                                                           possible to observe
                                                           how much stack
                                                           memory has been
                                                           used by each thread
                                                           of the client
                                                           program. Note: the
                                                           DRD tool itself
                                                           allocates some
                                                           temporary data on
                                                           the client thread
                                                           stack. The space
                                                           necessary for this
                                                           temporary data must
                                                           be allocated by the
                                                           client program when
                                                           it allocates stack
                                                           memory, but is not
                                                           included in stack
                                                           usage reported by
                                                           DRD.


                                                             .RE
                                                             .PP
                                                           --ignore-thread-creation=<yes|no>
                                                           [default: no]



                                                                     Controls
                                                               whether all
                                                               activities
                                                               during thread
                                                               creation should
                                                               be ignored. By
                                                               default enabled
                                                               only on
                                                               Solaris.
                                                               Solaris
                                                               provides higher
                                                               throughput,
                                                               parallelism and
                                                               scalability
                                                               than other
                                                               operating
                                                               systems, at the
                                                               cost of more
                                                               fine-grained
                                                               locking
                                                               activity. This
                                                               means for
                                                               example that
                                                               when a thread
                                                               is created
                                                               under glibc,
                                                               just one big
                                                               lock is used
                                                               for all thread
                                                               setup. Solaris
                                                               libc uses
                                                               several
                                                               fine-grained
                                                               locks and the
                                                               creator thread
                                                               resumes its
                                                               activities as
                                                               soon as
                                                               possible,
                                                               leaving for
                                                               example stack
                                                               and TLS setup
                                                               sequence to the
                                                               created thread.
                                                               This situation
                                                               confuses DRD as
                                                               it assumes
                                                               there is some
                                                               false ordering
                                                               in place
                                                               between creator
                                                               and created
                                                               thread; and
                                                               therefore many
                                                               types of race
                                                               conditions in
                                                               the application
                                                               would not be
                                                               reported. To
                                                               prevent such
                                                               false ordering,
                                                               this command
                                                               line option is
                                                               set to yes by
                                                               default on
                                                               Solaris. All
                                                               activity
                                                               (loads, stores,
                                                               client
                                                               requests) is
                                                               therefore
                                                               ignored during:




                                                               •
                                                                   pthread_create()
                                                                   call in the
                                                                   creator
                                                                   thread

                                                                        .RE


                                                                   •
                                                                       thread
                                                                       creation
                                                                       phase
                                                                       (stack
                                                                       and TLS
                                                                       setup)
                                                                       in the
                                                                       created
                                                                       thread

                                                                            .RE
                                                                             .sp


                                                                         .RE



                                                                         .PP
                                                                       --trace-addr=<address>
                                                                       [default:
                                                                       none]



                                                                                 Trace
                                                                           all
                                                                           load
                                                                           and
                                                                           store
                                                                           activity
                                                                           for
                                                                           the
                                                                           specified
                                                                           address.
                                                                           This
                                                                           option
                                                                           may
                                                                           be
                                                                           specified
                                                                           more
                                                                           than
                                                                           once.


                                                                             .RE
                                                                             .PP
                                                                           --ptrace-addr=<address>
                                                                           [default:
                                                                           none]



                                                                                     Trace
                                                                               all
                                                                               load
                                                                               and
                                                                               store
                                                                               activity
                                                                               for
                                                                               the
                                                                               specified
                                                                               address
                                                                               and
                                                                               keep
                                                                               doing
                                                                               that
                                                                               even
                                                                               after
                                                                               the
                                                                               memory
                                                                               at
                                                                               that
                                                                               address
                                                                               has
                                                                               been
                                                                               freed
                                                                               and
                                                                               reallocated.


                                                                                 .RE
                                                                                 .PP
                                                                               --trace-alloc=<yes|no>
                                                                               [default:
                                                                               no]



                                                                                         Trace
                                                                                   all
                                                                                   memory
                                                                                   allocations
                                                                                   and
                                                                                   deallocations.
                                                                                   May
                                                                                   produce
                                                                                   a
                                                                                   huge
                                                                                   amount
                                                                                   of
                                                                                   output.


                                                                                     .RE
                                                                                     .PP
                                                                                   --trace-barrier=<yes|no>
                                                                                   [default:
                                                                                   no]



                                                                                             Trace
                                                                                       all
                                                                                       barrier
                                                                                       activity.


                                                                                         .RE
                                                                                         .PP
                                                                                       --trace-cond=<yes|no>
                                                                                       [default:
                                                                                       no]



                                                                                                 Trace
                                                                                           all
                                                                                           condition
                                                                                           variable
                                                                                           activity.


                                                                                             .RE
                                                                                             .PP
                                                                                           --trace-fork-join=<yes|no>
                                                                                           [default:
                                                                                           no]



                                                                                                     Trace
                                                                                               all
                                                                                               thread
                                                                                               creation
                                                                                               and
                                                                                               all
                                                                                               thread
                                                                                               termination
                                                                                               events.


                                                                                                 .RE
                                                                                                 .PP
                                                                                               --trace-hb=<yes|no>
                                                                                               [default:
                                                                                               no]



                                                                                                         Trace
                                                                                                   execution
                                                                                                   of
                                                                                                   the
                                                                                                   ANNOTATE_HAPPENS_BEFORE(),
                                                                                                   ANNOTATE_HAPPENS_AFTER()
                                                                                                   and
                                                                                                   ANNOTATE_HAPPENS_DONE()
                                                                                                   client
                                                                                                   requests.


                                                                                                     .RE
                                                                                                     .PP
                                                                                                   --trace-mutex=<yes|no>
                                                                                                   [default:
                                                                                                   no]



                                                                                                             Trace
                                                                                                       all
                                                                                                       mutex
                                                                                                       activity.


                                                                                                         .RE
                                                                                                         .PP
                                                                                                       --trace-rwlock=<yes|no>
                                                                                                       [default:
                                                                                                       no]



                                                                                                                 Trace
                                                                                                           all
                                                                                                           reader-writer
                                                                                                           lock
                                                                                                           activity.


                                                                                                             .RE
                                                                                                             .PP
                                                                                                           --trace-semaphore=<yes|no>
                                                                                                           [default:
                                                                                                           no]



                                                                                                                     Trace
                                                                                                               all
                                                                                                               semaphore
                                                                                                               activity.


                                                                                                                 .RE






MASSIF OPTIONS
         .PP --heap=<yes|no> [default: yes]



                 Specifies whether heap profiling should be done.


             .RE

             .PP --heap-admin=<size> [default: 8]



                     If heap profiling is enabled, gives the number of
               administrative bytes per block to use. This should be an
               estimate of the average, since it may vary. For example, the
               allocator used by glibc on Linux requires somewhere between 4
               to 15 bytes per block, depending on various factors. That
               allocator also requires admin space for freed blocks, but
               Massif cannot account for this.


                 .RE

                 .PP --stacks=<yes|no> [default: no]



                         Specifies whether stack profiling should be done.
                   This option slows Massif down greatly, and so is off by
                   default. Note that Massif assumes that the main stack has
                   size zero at start-up. This is not true, but doing
                   otherwise accurately is difficult. Furthermore, starting at
                   zero better indicates the size of the part of the main
                   stack that a user program actually has control over.


                     .RE

                     .PP --pages-as-heap=<yes|no> [default: no]



                             Tells Massif to profile memory at the page level
                       rather than at the malloc'd block level. See above for
                       details.


                         .RE

                         .PP --depth=<number> [default: 30]



                                 Maximum depth of the allocation trees
                           recorded for detailed snapshots. Increasing it will
                           make Massif run somewhat more slowly, use more
                           memory, and produce bigger output files.


                             .RE

                             .PP --alloc-fn=<name>



                                     Functions specified with this option will
                               be treated as though they were a heap
                               allocation function such as malloc. This is
                               useful for functions that are wrappers to
                               malloc or new, which can fill up the allocation
                               trees with uninteresting information. This
                               option can be specified multiple times on the
                               command line, to name multiple functions.



                                     Note that the named function will only be
                               treated this way if it is the top entry in a
                               stack trace, or just below another function
                               treated this way. For example, if you have a
                               function malloc1 that wraps malloc, and malloc2
                               that wraps malloc1, just specifying
                               --alloc-fn=malloc2 will have no effect. You
                               need to specify --alloc-fn=malloc1 as well.
                               This is a little inconvenient, but the reason
                               is that checking for allocation functions is
                               slow, and it saves a lot of time if Massif can
                               stop looking through the stack trace entries as
                               soon as it finds one that doesn't match rather
                               than having to continue through all the
                               entries.



                                     Note that C++ names are demangled. Note
                               also that overloaded C++ names must be written
                               in full. Single quotes may be necessary to
                               prevent the shell from breaking them up. For
                               example:

                                   --alloc-fn='operator new(unsigned, std::nothrow_t const&)'




                                 .RE

                                 .PP --ignore-fn=<name>



                                         Any direct heap allocation (i.e. a
                                   call to malloc, new, etc, or a call to a
                                   function named by an --alloc-fn option)
                                   that occurs in a function specified by this
                                   option will be ignored. This is mostly
                                   useful for testing purposes. This option
                                   can be specified multiple times on the
                                   command line, to name multiple functions.



                                         Any realloc of an ignored block will
                                   also be ignored, even if the realloc call
                                   does not occur in an ignored function. This
                                   avoids the possibility of negative heap
                                   sizes if ignored blocks are shrunk with
                                   realloc.



                                         The rules for writing C++ function
                                   names are the same as for --alloc-fn above.


                                     .RE

                                     .PP --threshold=<m.n> [default: 1.0]



                                             The significance threshold for
                                       heap allocations, as a percentage of
                                       total memory size. Allocation tree
                                       entries that account for less than this
                                       will be aggregated. Note that this
                                       should be specified in tandem with
                                       ms_print's option of the same name.


                                         .RE

                                         .PP --peak-inaccuracy=<m.n> [default:
                                       1.0]



                                                 Massif does not necessarily
                                           record the actual global memory
                                           allocation peak; by default it
                                           records a peak only when the global
                                           memory allocation size exceeds the
                                           previous peak by at least 1.0%.
                                           This is because there can be many
                                           local allocation peaks along the
                                           way, and doing a detailed snapshot
                                           for every one would be expensive
                                           and wasteful, as all but one of
                                           them will be later discarded. This
                                           inaccuracy can be changed (even to
                                           0.0%) via this option, but Massif
                                           will run drastically slower as the
                                           number approaches zero.


                                             .RE

                                             .PP --time-unit=<i|ms|B>
                                           [default: i]



                                                     The time unit used for
                                               the profiling. There are three
                                               possibilities: instructions
                                               executed (i), which is good for
                                               most cases; real (wallclock)
                                               time (ms, i.e. milliseconds),
                                               which is sometimes useful; and
                                               bytes allocated/deallocated on
                                               the heap and/or stack (B),
                                               which is useful for very
                                               short-run programs, and for
                                               testing purposes, because it is
                                               the most reproducible across
                                               different machines.

                                                 .RE

                                                 .PP --detailed-freq=<n>
                                               [default: 10]



                                                         Frequency of detailed
                                                   snapshots. With
                                                   --detailed-freq=1, every
                                                   snapshot is detailed.


                                                     .RE

                                                     .PP --max-snapshots=<n>
                                                   [default: 100]



                                                             The maximum
                                                       number of snapshots
                                                       recorded. If set to N,
                                                       for all programs except
                                                       very short-running
                                                       ones, the final number
                                                       of snapshots will be
                                                       between N/2 and N.


                                                         .RE

                                                         .PP
                                                       --massif-out-file=<file>
                                                       [default:
                                                       massif.out.%p]



                                                                 Write the
                                                           profile data to
                                                           file rather than to
                                                           the default output
                                                           file,
                                                           massif.out.<pid>.
                                                           The %p and %q
                                                           format specifiers
                                                           can be used to
                                                           embed the process
                                                           ID and/or the
                                                           contents of an
                                                           environment
                                                           variable in the
                                                           name, as is the
                                                           case for the core
                                                           option --log-file.


                                                             .RE







BBV OPTIONS
         .PP --bb-out-file=<name> [default: bb.out.%p]



                   This option selects the name of the basic block vector
           file. The %p and %q format specifiers can be used to embed the
           process ID and/or the contents of an environment variable in the
           name, as is the case for the core option --log-file.


             .RE

             .PP --pc-out-file=<name> [default: pc.out.%p]



                       This option selects the name of the PC file. This file
               holds program counter addresses and function name info for the
               various basic blocks. This can be used in conjunction with the
               basic block vector file to fast-forward via function names
               instead of just instruction counts. The %p and %q format
               specifiers can be used to embed the process ID and/or the
               contents of an environment variable in the name, as is the case
               for the core option --log-file.


                  .RE

                  .PP --interval-size=<number> [default: 100000000]



                         This option selects the size of the interval to use.
                   The default is 100 million instructions, which is a
                   commonly used value. Other sizes can be used; smaller
                   intervals can help programs with finer-grained phases.
                   However smaller interval size can lead to accuracy issues
                   due to warm-up effects (When fast-forwarding the various
                   architectural features will be un-initialized, and it will
                   take some number of instructions before they "warm up" to
                   the state a full simulation would be at without the
                   fast-forwarding. Large interval sizes tend to mitigate
                   this.)


                     .RE

                     .PP --instr-count-only [default: no]



                               This option tells the tool to only display
                       instruction count totals, and to not generate the
                       actual basic block vector file. This is useful for
                       debugging, and for gathering instruction count info
                       without generating the large basic block vector files.


                          .RE







LACKEY OPTIONS
         .PP --basic-counts=<no|yes> [default: yes]



                 When enabled, Lackey prints the following statistics and
           information about the execution of the client program:






            1.
                       The number of calls to the function specified by the
               --fnname option (the default is main). If the program has had
               its symbols stripped, the count will always be zero.

                      .RE




                2.
                           The number of conditional branches encountered and
                   the number and proportion of those taken.

                          .RE




                    3.
                               The number of superblocks entered and completed
                       by the program. Note that due to optimisations done by
                       the JIT, this is not at all an accurate value.

                              .RE




                        4.
                                   The number of guest (x86, amd64, ppc, etc.)
                           instructions and IR statements executed. IR is
                           Valgrind's RISC-like intermediate representation
                           via which all instrumentation is done.

                                  .RE




                            5.
                                       Ratios between some of these counts.

                                      .RE




                                6.
                                           The exit code of the client
                                   program.

                                          .RE


                                         .sp



                                     .RE

                                     .PP --detailed-counts=<no|yes> [default:
                                   no]



                                             When enabled, Lackey prints a
                                       table containing counts of loads,
                                       stores and ALU operations,
                                       differentiated by their IR types. The
                                       IR types are identified by their IR
                                       name ("I1", "I8", ... "I128", "F32",
                                       "F64", and "V128").


                                         .RE

                                         .PP --trace-mem=<no|yes> [default:
                                       no]



                                                 When enabled, Lackey prints
                                           the size and address of almost
                                           every memory access made by the
                                           program. See the comments at the
                                           top of the file lackey/lk_main.c
                                           for details about the output
                                           format, how it works, and
                                           inaccuracies in the address trace.
                                           Note that this option produces
                                           immense amounts of output.


                                             .RE

                                             .PP --trace-superblocks=<no|yes>
                                           [default: no]



                                                     When enabled, Lackey
                                               prints out the address of every
                                               superblock (a single entry,
                                               multiple exit, linear chunk of
                                               code) executed by the program.
                                               This is primarily of interest
                                               to Valgrind developers. See the
                                               comments at the top of the file
                                               lackey/lk_main.c for details
                                               about the output format. Note
                                               that this option produces large
                                               amounts of output.


                                                 .RE

                                                 .PP --fnname=<name> [default:
                                               main]



                                                         Changes the function
                                                   for which calls are counted
                                                   when --basic-counts=yes is
                                                   specified.


                                                     .RE






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





AUTHOR
       See the AUTHORS file in the valgrind distribution for a comprehensive
       list of authors.

       This manpage was written by Andres Roldan <aroldan@debian.org> and the
       Valgrind developers.





NOTES
        1. Debugging your program using Valgrind's gdbserver and GDB
           http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.gdbserver

        2. vgdb
           http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.vgdb

        3. Valgrind monitor commands
           http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.valgrind-monitor-commands

        4. The Commentary
           http://www.valgrind.org/docs/manual/manual-core.html#manual-core.comment

        5. Scheduling and Multi-Thread Performance
           http://www.valgrind.org/docs/manual/manual-core.html#manual-core.pthreads_perf_sched

        6. Cachegrind: a cache and branch-prediction profiler
           http://www.valgrind.org/docs/manual/cg-manual.html

        7. Execution Trees
           http://www.valgrind.org/docs/manual/manual-core.html#manual-core.xtree



Release 3.16.1                    07/22/2020                       VALGRIND(1)