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:

Reuse or create cache dir:

Reuse or create sandbox dir:

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>