NAME

       apport-valgrind - valgrind wrapper that first downloads debug symbols

SYNOPSIS

       apport-valgrind [ OPTIONS ] EXECUTABLE

DESCRIPTION

       apport-valgrind is a valgrind wrapper that automatically downloads related available debug
       symbols and provides them to valgrind's memcheck tool, which is executed. The output is  a
       valgrind  log  file  ("valgrind.log")  that  contains  stack  traces (with as many symbols
       resolved as available) and that shows memory leaks.

       By default, a temporary cache directory  is  created  to  hold  the  latest  debug  symbol
       packages.  These are unpacked into a temporary sandbox directory.  The path to the sandbox
       directory is provided to valgrind as an additional location for symbol files.

       You may create and use persistent cache  and  sandbox  directories  to  save  time  across
       multiple  executions, thus preventing the need to recreate them each time. Downloading all
       packages into the the cache directory each time is particularly time consuming.

       It is recommended to update your  system  before  execution.  This  ensures  your  runtime
       environment is consistent with the latest downloaded symbol packages and therefore results
       in a more complete stack trace from valgrind.

       EXECUTABLE is the program to run under valgrind. Always terminate the  EXECUTABLE  in  its
       usual way. Exit it from the GUI if there is one. If not, use the most appropriate method.

       Different  techniques  are  used  to  determine which packages should be unpacked into the
       sandbox depending on whether EXECUTABLE is packaged (installed by a debian package) or not
       (for  example  something  created  for  development or testing). A packaged EXECUTABLE has
       debian dependencies that are used. For an unpackaged EXECUTABLE, the shared  object  files
       are found with ldd and the packages for these are used.

OPTIONS

       -C CDIR, --cache=CDIR
              Reuse a previously created cache dir (CDIR) or, if it does not exist, create it.

       --sandbox-dir=SDIR
              Reuse a previously created sandbox dir (SDIR) or, if it does not exist, create it

       --no-sandbox
              Do  not  create  or reuse a sandbox directory for additional debug symbols but rely
              only on installed debug symbols. This speeds execution time but may  result  in  an
              incomplete  and  less  useful valgrind log if you do not have all appropriate debug
              symbol packages installed.

       -p, --extra-package
              Specify an extra package (or packages) to unpack in  the  sandbox.  Useful  to  add
              additional debug symbol packages that result in more complete valgrind logs.

       -v, --verbose
              Report download/install progress when installing packages in sandbox mode.

       -l LOGFILE, --log=LOGFILE
              Specify the file name for the generated valgrind log file. Default is: valgrind.log

       -h, --help
              Display short help that documents all options.

EXAMPLES

       Create and use temporary cache and sandbox directories:
           apport-valgrind EXECUTABLE

       Reuse or create cache dir:
           apport-valgrind -C CDIR EXECUTABLE

       Reuse or create sandbox dir:
           apport-valgrind --sandbox-dir SDIR EXECUTABLE

KNOWN ISSUES

       If  you  abnormally  terminate  the  executable  you are running under valgrind, temporary
       directories may not be deleted and processes may not all terminate.  For example,  if  the
       executable  does  not  normally  terminate  on ctrl+c, pressing ctrl+c in the terminal may
       cause apport-valgrind and valgrind to terminate, but may not terminate the executable  and
       may not delete the temporary directories.

AUTHORS

       Developed by Martin Pitt <martin.pitt@ubuntu.com>, Alex Chiang <alex.chiang@canonical.com>
       and Kyle Nitzsche <kyle.nitzsche@canonical.com>