lcov - GCOV coverage tool extension

lcov [-h|--help] [-v|--version]

[-q|--quiet] [-z|--zerocounters] [-c|--capture]

[-f|--follow]

[-g|--gcov-tool tool]

[-t|--test-name testname]

[-o|--output-file filename]

[-d|--directory directory]

[-k|--kernel-directory directory]

[-a|--add-tracefile tracefile]

[-e|--extract tracefile]

[-r|--remove tracefile]

[-l|--list tracefile]

[--diff tracefile diff]

[--no-checksum]

lcov is an extension of GCOV, a GNU tool which provides information about what parts of a program are actually executed (i.e. "covered") during a particular test case. The extension consists of a set of PERL scripts which build on the textual GCOV output to implement HTML output and support for large projects.

Use lcov to collect coverage data from either the currently running Linux kernel or from a user space application. To do this, you have to complete the following preparation steps:

For Linux kernel coverage: Download and install the "gcov-kernel" package from http://sourceforge.net/projects/ltp

The resulting kernel module has to be installed either in the system wide kernel modules directory or in the same directory as the LCOV tool. Note that you will need root privileges to access kernel coverage data.

For user space application coverage: Compile the application with GCC using the options "-fprofile-arcs" and "-ftest-coverage".

Please note that this man page refers to the output format of lcov as ".info file" or "tracefile" and that the output of GCOV is called ".da file".

-h

--help Print a short help text, then exit.

-v

--version Print version number, then exit.

-q

--quiet Do not print progress messages.

This option is implied when no output filename is specified to prevent progress messages to mess with coverage data which is also printed to the standard output.

-z

--zerocounters Reset all execution counts to zero.

By default tries to reset kernel execution counts. Use the --directory option to reset all counters of a user space program.

Only one of -z, -c, -a, -e, -r, -l and --diff may be specified at a time.

-c

--capture Capture coverage data.

By default captures the current kernel execution counts and writes the resulting coverage data to the standard output. Use the --directory option to capture counts for a user space program.

Only one of -z, -c, -a, -e, -r, -l and --diff may be specified at a time.

-f

--follow Follow links when searching for .da files.

-g tool

--gcov-tool tool Specify a tool to use instead of gcov , for example /usr/bin/gcov-3.4

-t testname

--test-name testname Specify test name to be stored in the tracefile.

This name helps distinguish coverage results in cases where data from more than one test case is merged into a single file (i.e. by simply concatenation the respective tracefiles).

Valid characters for testname are alphanumerics plus "_".

-o filename

--output-file filename Write data to FILENAME instead of stdout.

Specify "-" as a filename to use the standard output. But that would be pointless, wouldn't it? :)

-d directory

--directory directory Use .da files in directory instead of kernel.

If you want to work on coverage data for a user space program, use this option to specify the location where the program was compiled (that's where the counter files ending with .da will be stored).

Make sure that the resulting kernel module is copied either to the system wide kernel module directory or to the directory which also holds the LCOV tools. Note that you may specify more than one directory, all of which will be processed sequentially.

-k kernel-directory

--kernel-directory kernel-directory Capture kernel coverage data only from kernel-directory.

Use this option if you don't want to get coverage data for all of the kernel, but only for specific subdirectories.

Note that you may specify more than one directory, all of which will be processed sequentially.

-a tracefile

--add-tracefile tracefile Add contents of tracefile.

Specify several tracefiles using the -a switch to combine the coverage data contained in these files by adding up execution counts for matching test and filename combinations.

Note that due to the way data is stored in tracefiles, the resulting file may be smaller in size than the original ones.

Only one of -z, -c, -a, -e, -r, -l and --diff may be specified at a time.

-e tracefile

--extract tracefile Extract data from tracefile.

Use this switch if you want to extract coverage data for only a particular set of files from a tracefile. Additional command line parameters will be interpreted as shell wildcard patterns (note that they may need to be escaped accordingly to prevent the shell from expanding them first). Every file entry in tracefile which matches at least one of those patterns will be extracted.

Only one of -z, -c, -a, -e, -r, -l and --diff may be specified at a time.

-r tracefile

--remove tracefile Remove data from tracefile.

Use this switch if you want to remove coverage data for a particular set of files from a tracefile. Additional command line parameters will be interpreted as shell wildcard patterns (note that they may need to be escaped accordingly to prevent the shell from expanding them first). Every file entry in tracefile which matches at least one of those patterns will be removed.

Only one of -z, -c, -a, -e, -r, -l and --diff may be specified at a time.

-l tracefile

--list tracefile List the contents of the tracefile.

Only one of -z, -c, -a, -e, -r, -l and --diff may be specified at a time.

--diff tracefile difffile Convert coverage data in tracefile using source code diff file difffile.

Use this option if you want to merge coverage data from different source code levels of a program, e.g. when you have data taken from an older version and want to combine it with data from a more current version. lcov will try to map source code lines between those versions and adjust the coverage data respectively. difffile needs to be in unified format, i.e. it has to be created using the '-u' option of the diff tool.

Note that lines which are not present in the old version will not be counted as instrumented, therefore tracefiles resulting from this operation should not be interpreted individually but together with other tracefiles taken from the newer version. Also keep in mind that converted coverage data should only be used for overview purposes as the process itself introduces a loss of accuracy.

Only one of -z, -c, -a, -e, -r, -l and --diff may be specified at a time.

--no-checksum Do not generate checksum data when writing tracefiles.

By default, each line of coverage data is associated with a checksum of the corresponding source code line. This checksum is used to prevent merging coverage data from incompatible source code versions. Use this option to suppress generating such checksums for tracefiles.

/etc/lcovrc The systemwide configuration file.

~/.lcovrc The per-user configuration file.

Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>

genhtml(1), geninfo(1), genpng(1), gendesc(1), gcov(1)