valgrind



VALGRIND(1)                                                        VALGRIND(1)




NAME

       valgrind - a memory debugger for x86-linux



SYNOPSIS

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



DESCRIPTION

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


       This  manual  page covers only basic usage and options.  Please see the
       HTML documentation for more comprehensive information.



INVOCATION

       valgrind is typically invoked as follows:

           valgrind program args

       This runs program (with arguments args) under valgrind using  the  mem-
       check  tool.   memcheck  performs a range of memory-checking functions,
       including detecting accesses to uninitialized memory, misuse  of  allo-
       cated memory (double frees, access after free, etc.) and detecting mem-
       ory leaks.

       To use a different tool, use the --tool option:

           valgrind --tool=toolname program args

       The following tools are available:


              - addrcheck
                     addrcheck is similar to memcheck, but  does  not  perform
                     the  same  granularity of memory checking.  This will run
                     faster and use less memory, but may  miss  some  problems
                     that memcheck would catch.

              - cachegrind
                     cachegrind is a cache simulator.

              - lackey
                     lackey  is  a  sample tool that can be used as a template
                     for generating your own tools. After the  program  termi-
                     nates, it prints out some basic statistics about the pro-
                     gram execution.

              - massif
                     massif is a heap profiler.  It  measures  how  much  heap
                     memory your program uses.

              - memcheck
                     memcheck is a fine-grained memory checker.

              - none none  performs  no  function - it simply runs the program
                     under valgrind.  This is typically used for debugging and
                     benchmarking valgrind.



COMMON CORE OPTIONS

       --db-attach=<yes|no> [default: no]
              When  enabled,  valgrind  will pause after every error shown and
              print the line:


              ---- Attach to debugger ? --- [Return/N/n/Y/y/C/c] ----


              Pressing Ret, or N Ret or n Ret, causes valgrind not to start  a
              debugger for this error.


              Pressing  Y  Ret  or y Ret causes valgrind to start the debugger
              (specified by the --db-command option) for the program  at  this
              point.  When  you have finished with the debugger, quit from it,
              and the program will continue. Trying to  continue  from  inside
              the debugger doesn’t work.


              Pressing  C Ret or c Ret causes valgrind not to start the debug-
              ger and valgrind will not ask again.


              --db-attach=yes conflicts with --trace-children=yes.  You  can’t
              use  them  together. valgrind refuses to start up in this situa-
              tion. 1 May 2002: this is a historical relic which could be eas-
              ily  fixed  if it gets in your way. Mail me and complain if this
              is a problem for you.


              Nov 2002: if you’re sending output to a logfile or to a  network
              socket,  I guess this option doesn’t make any sense. Caveat emp-
              tor.


       --db-command=<command> [default: gdb -nw %f %p]
              Specify the debugger to use with the  --db-attach  command.  The
              default  debugger  is  gdb.  This  option  is a template that is
              expanded by valgrind at runtime.  %f is replaced with  the  exe-
              cutable’s  file name and %p is replaced by the process ID of the
              executable.


       --error-limit=<yes|no> [default: yes]
              When enabled, valgrind stops reporting  errors  after  30000  in
              total,  or  300  different ones, have been seen. This is to stop
              the error tracking machinery from becoming  a  huge  performance
              overhead in programs with many errors.


       --gen-suppressions=<yes|no> [default: no]
              When  enabled,  valgrind  will pause after every error shown and
              print the line:


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


              Pressing Y Ret or y Ret will cause a suppression for this  error
              to be printed. This suppression can be cut-and-paste into a cus-
              tom suppressions file and used to suppress this error in  subse-
              quent runs.


              Pressing  Ret  or n Ret or N Ret will cause no suppression to be
              printed.


              Pressing C Ret or c Ret will cause no suppression to be  printed
              and valgrind will not ask again.


       -h --help
              Show  help  for  all  options,  both  for  the  core and for the
              selected tool.


       --help-debug
              Show help for all  options,  both  for  the  core  and  for  the
              selected tool, including options for debugging valgrind.


       --log-file=<filename>
              Specifies  that  valgrind should send all of its messages to the
              specified file. In fact, the file name used is created  by  con-
              catenating  the  text filename, ".pid" and the process ID, so as
              to create a file per process.  The specified file name  may  not
              be the empty string.


       --num-callers=<number> [default=12]
              By  default,  valgrind shows 12 levels of function call names to
              help you identify program locations. You can change that  number
              with  this  option.  This  can help in determining the program’s
              location in deeply-nested call chains. Note that errors are com-
              moned  up using only the top three function locations (the place
              in the current function, and that of its two immediate callers).
              So this doesn’t affect the total number of errors reported.


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


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


       --suppressions=<filename> [default: $PREFIX/lib/valgrind/default.supp]
              Specifies an extra file  from  which  to  read  descriptions  of
              errors to suppress. You may specify up to 10 additional suppres-
              sion files.


       --tool=<toolname> [default: memcheck]
              Specify which tool to use. The default tool is memcheck.


       --trace-children=<yes|no> [default: no]
              When enabled, valgrind will trace into child processes. This  is
              confusing  and  usually  not  what  you  want, so is disabled by
              default.


       --track-fds=<yes|no> [default: no]
              Track file descriptor creation and deletion and produce  a  sum-
              mary  at  the  end  of the program execution of file descriptors
              that are still in use.


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


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



ADDRCHECK OPTIONS

       --freelist-vol=<number> [default: 1000000]
              When  the  client  program  releases memory using free (in C) or
              delete (C++), that memory is not immediately made available  for
              re-allocation.   Instead it is marked inaccessible and placed in
              a queue of freed blocks.  The purpose is to delay the  point  at
              which   freed-up  memory  comes  back  into  circulation.   This
              increases the chance that  addrcheck  will  be  able  to  detect
              invalid  accesses  to blocks for some significant period of time
              after they have been freed.

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


       --leak-check=<yes|no|summary|full> [default: summary]
              Enables full, summary or no leak checking.  When full  (full  or
              yes options) checking is performed, details on all leaked blocks
              are printed after the program finishes executing.  When  summary
              checking  is enabled, a summary of all leaked memory is printed.
              When no leak checking is performed, no leaked memory details are
              produced.   Disabling  leak  checking  can speed up your program
              execution.


       --leak-resolution=<low|med|high> [default: low]
              When doing leak checking, determines how willing addrcheck is to
              consider  different backtraces to be the same.  When set to low,
              the default, only the first two entries need match.   When  med,
              four  entries  have  to  match.   When high, all entries need to
              match.


       --partial-loads-ok=<yes|no> [default: yes]
              Controls  how  addrcheck  handles  word  (4-byte)   loads   from
              addresses  for  which  some bytes are addressible and others are
              not.  When enabled, such loads do not elicit an  address  error.
              Instead,  addrcheck  considers  the  bytes  corresponding to the
              illegal addresses as undefined, and those corresponding to legal
              addresses are considered defined.

              When  disabled,  loads  from  partially  invalid  addresses  are
              treated the same as loads from completely invalid addresses:  an
              illegal-address error is issued, and the addrcheck considers all
              bytes as invalid data.


       --show-reachable=<yes|no> [default: no]
              When performing full leak checking, print out details of  blocks
              that  are  leaked  but  still  reachable.  For details of what a
              reachable block is, see the HTML documentation.


       --workaround-gcc296-bugs=<yes|no> [default: no]
              When enabled, assume that reads and writes some  small  distance
              below  the  stack  pointer %esp are due to bugs in gcc 2.96, and
              does not report them.  The "small  distance"  is  256  bytes  by
              default.   Note  that  gcc  2.96 is the default compiler on some
              older Linux distributions (RedHat 7.X, Mandrake) and so you  may
              well  need  to  use this flag.  Do not use it if you do not have
              to, as it can cause  real  errors  to  be  overlooked.   Another
              option  is  to  use  a  gcc/g++ which does not generate accesses
              below the stack pointer.  2.95.3 seems to be a  good  choice  in
              this respect.



MEMCHECK OPTIONS

       memcheck understands the same options as addrcheck, along with the fol-
       lowing options:


       --avoid-strlen-errors=<yes|no> [default: yes]
              Enable or disable a heuristic for dealing with  highly-optimized
              versions of strlen.  These versions of strlen can cause spurious
              errors to be reported by memcheck, so it’s usually a  good  idea
              to leave this enabled.


       --cleanup=<yes|no> [default: yes]
              This  is  a flag to help debug valgrind itself.  It is of no use
              to end-users. When enabled, various improvments are  applied  to
              the  post-instrumented  intermediate  code,  aimed  at  removing
              redundant value checks.



CACHEGRIND OPTIONS

       --D1=<size>,<associativity>,<line size>
              Specify the size, associativity and line size  of  the  level  1
              data  cache.  All values are measured in bytes.  If this options
              is not specified, the system value (as retrieved  by  the  CPUID
              instruction) is used.


       --I1=<size>,<associativity>,<line size>
              Specify  the  size,  associativity  and line size of the level 1
              instruction cache.  All values are measured in bytes.   If  this
              options  is not specified, the system value (as retrieved by the
              CPUID instruction) is used.


       --L2=<size>,<associativity>,<line size>
              Specify the size, associativity and line size  of  the  level  2
              cache.   All  values  are measured in bytes.  If this options is
              not specified, the system  value  (as  retrieved  by  the  CPUID
              instruction) is used.



MASSIF OPTIONS

       --alloc-fn=<name>
              Specify  a  function  that allocates memory.  This is useful for
              functions that are wrappers to malloc(), which can fill  up  the
              context information uselessly (and give very uninformative bands
              on the graph).  Functions specified will be ignored in contexts,
              i.e.  treated  as though they were malloc().  This option can be
              specified multiple times on the command line, to  name  multiple
              functions.


       --depth=<number> [default: 3]
              Depth  of  call  chains to present in the detailed heap informa-
              tion.  Increasing it will give more information, but massif will
              run  the  program  more slowly, using more memory, and produce a
              bigger .txt or .hp file.


       --format=<text|html> [default: text]
              Produce the detailed heap information in text  or  HTML  format.
              The file suffix used will be either .txt or .html.


       --heap=<yes|no> [default: yes]
              When  enabled,  profile  heap  usage in detail.  Without it, the
              .txt or .html file will be very short.


       --heap-admin=<number> [default: 8]
              The number of admin bytes per block to use.  This can only be an
              estimate  of the average, since it may vary.  The allocator used
              by glibc requires somewhere between 4 to  15  bytes  per  block,
              depending  on various factors.  It also requires admin space for
              freed blocks, although massif does not count this.


       --stacks=<yes|no> [default: yes]
              When enabled, include stack(s) in the  profile.   Threaded  pro-
              grams can have multiple stacks.






LESS FREQUENTLY USED CORE OPTIONS

       --alignment=<number> [default: 8]
              By  default  valgrind’s  malloc,  realloc,  etc,  return  8-byte
              aligned addresses. These are suitable for any  accesses  on  x86
              processors. Some programs might however assume that malloc et al
              return 16- or more aligned memory. These programs are broken and
              should  be  fixed, but if this is impossible for whatever reason
              the alignment can be increased using this  parameter.  The  sup-
              plied  value must be between 8 and 4096 inclusive, and must be a
              power of two.


       --branchpred=<yes|no> [default: no]
              This option enables the generation of static  branch  prediction
              hints.  In theory this allows the real CPU to do a better job of
              running the generated code, but in practice it makes  almost  no
              measurable  difference.   It may have a large effect on some x86
              implementations.


       --chain-bb=<yes|no> [default: yes]
              Enables basic-block chaining.  If basic-block chaining  is  dis-
              abled,   the  synthetic  CPU  returns  to  the  scheduler  after
              interpreting  each  basic  block.   With  basic  block  chaining
              enabled,  it  can  immediately  proceed to the next basic block.
              This almost always results in  a  performance  gain,  so  it  is
              enabled by default.


       --command-line-only=<yes|no> [default: no]
              Normally,  valgrind  will  look  for command-line options in the
              following locations:

              - The valgrind command line

              - The .valgrindrc file in the invocation directory

              - The .valgrindrc file in users home directory

              - The $VALGRIND_OPTS environment variable


              When this option is enabled, valgrind will only look at the com-
              mand line for options.


       --demangle=<yes|no> [default: yes]
              Enable  or disable automatic demangling (decoding) of C++ names.
              Enabled by default.  When  enabled,  valgrind  will  attempt  to
              translate   encoded   C++  procedure  names  back  to  something
              approaching the original. The demangler handles symbols  mangled
              by g++ versions 2.X and 3.X.


       --dump-error=<number>
              After  the program has exited, show gory details of the transla-
              tion of the basic block containing the  <number>’th  error  con-
              text.  When  used with --single-step=yes, can show the exact x86
              instruction causing an error.  This  is  all  fairly  dodgy  and
              doesn’t work at all if threads are involved.


       --exec=<filename>
              Specify  the  executable  to run. If this is specified, it takes
              precedence over the your-program executable  from  the  command-
              line.   If this is not specified, valgrind searches the path for
              the your-program executable, just like a regular shell would.


       --input-fd=<number> [default: 0, stdin]
              Specify the file descriptor to use for reading  input  from  the
              user.  This  is  used whenever valgrind needs to prompt the user
              for a decision.


       --log-fd=<number> [default: 2, stderr]
              Specifies that valgrind should send all of its messages  to  the
              specified file descriptor. The default, 2, is the standard error
              channel  (stderr).   Note  that  this  may  interfere  with  the
              client’s own use of stderr.


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


       --optimise=<yes|no> [default: yes]
              When enabled, various improvements are applied to the intermedi-
              ate code, mainly aimed at allowing the simulated CPU’s registers
              to  be cached in the real CPU’s registers over several simulated
              instructions.


       --pointercheck=<yes|no> [default: yes]
              When enabled, enforces client  address  space  limits.  If  this
              option  is  disabled, the client program has full and unfettered
              access to the part of the address space used internally by  val-
              grind.   This  can  cause  unexplained  crashes  and false error
              reports, so it is best left enabled.


       --run-libc-freeres=<yes|no> [default: yes]
              The GNU C library (libc.so), which is used by all programs,  may
              allocate  memory  for its own uses. Usually it doesn’t bother to
              free that memory when the program  ends  -  there  would  be  no
              point,  since  the  Linux  kernel reclaims all process resources
              when a process exits anyway, so it would just slow things  down.


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


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


       --show-below-main=<yes|no> [default: no]
              When enabled, this option causes full  stack  backtraces  to  be
              emited,  including the part before main in your program (subject
              to the --num-callers option.)  When disabled, only the  part  of
              the stack backtrace up to and including main is printed.


       --single-step=<yes|no> [default: no]
              When  enabled,  each  x86  insn  is  translated  separately into
              instrumented code.  When disabled, translation is done on a per-
              basic-block  basis,  giving  much  better  translations. This is
              needed when running valgrind under valgrind.


       --sloppy-malloc=<yes|no> [default: no]
              When enabled, valgrind  rounds  all  memory  allocation  request
              sizes up to 4 bytes.


       --time-stamp=<yes|no> [default: no]
              When enabled, a time-stamp is added to all log messages.


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


              - lax-ioctls
                     If valgrind encounters an ioctl that  it  doesn’t  under-
                     stand,  it  normally prints a warning message before con-
                     tinuing.  Specifying the lax-ioctls hack  tells  valgrind
                     to  be  very  lax  about  ioctl  handling and assume that
                     unknown ioctls just behave correctly.

              - ioctl-mmap
                     Tell valgrind to search for new memory mappings after  an
                     unknown ioctl call.



CORE DEBUGGING OPTIONS

       --profile=<yes|no> [default: no]
              When  enabled, does crude internal profiling of valgrind itself.
              This is not for profiling your programs. Rather it is  to  allow
              the  developers  to  assess where valgrind is spending its time.
              The tools must be built for profiling for this to work.


       --sanity-level=<number> [default: 1]
              Set the level of sanity checking to perform. This  is  used  for
              debugging  valgrind.  Setting this to 2 or higher can cause more
              internal sanity checks to be performed, but can slow  your  pro-
              gram down appreciably. Setting this to 0 disables sanity checks.


       --trace-codegen=<bitmask>
              Produce lots of output showing exactly how valgrind is translat-
              ing  each  basic  block.  The argument to this option is a 5-bit
              wide bitmask.  Each bit refers to a specific feature  to  trace.
              If the bit is 1, the feature is traced.  If it is 0, the feature
              is not traced.

              The traced features are:

              Bit 1: basic-block disassembly

              Bit 2: optimization phase

              Bit 3: tool instrumentation

              Bit 4: register allocation

              Bit 5: final code generation


       --trace-malloc=<yes|no> [default: no]
              Enable or disable tracing of malloc, free and other  memory-man-
              ager calls.


       --trace-redir=<yes|no> [default: no]
              Enable or disable tracing of function redirection.


       --trace-sched=<yes|no> [default: no]
              Enable or disable tracing of thread scheduling events.


       --trace-signals=<yes|no> [default: no]
              Enable or disable tracing of signal handling.


       --trace-syscalls=<yes|no> [default: no]
              Enable or disable tracing of system call intercepts.


       --trace-symtab=<yes|no> [default: no]
              Enable or disable tracing of symbol table reading.



SEE ALSO

       /usr/share/doc/valgrind/html/manual.html



AUTHOR

       This manpage has been written by Andres Roldan <aroldan@debian.org> for
       the Debian Project,  but  can  be  used  for  any  other  distribution.
       Updated, rearranged and expanded by Robert Walsh <rjwalsh@durables.org>
       for the 2.4.0 release.



                                                                   VALGRIND(1)

Man(1) output converted with man2html