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>