lcov.1

\" Define project URL
.ds lcovurl https://github.com/linux\-test\-project/lcov

.TH lcov 1 "LCOV 2.0" 2023\-05\-17 "User Manuals"
.SH NAME
lcov \- a graphical GCOV front\-end
.SH SYNOPSIS

Capture coverage data tracefile (from compiler-generated data):
.br

.RS 3
.B lcov
.BR \-c | \-\-capture
.RS 4
.br
.RB [ \-d | \-\-directory
.IR directory ]
.RB [ \-k | \-\-kernel\-directory
.IR directory ]
.br
.RB [ \-o | \-\-output\-file
.IR tracefile ]
.RB [ \-t | \-\-test\-name
.IR testname ]
.br
.RB [ \-b | \-\-base\-directory
.IR directory ]
.br
.RB [ \-\-build\-directory
.IR directory ]
.br
.RB [ \-\-source\-directory
.IR directory ]
.br
.RB [ \-i | \-\-initial ]
.br
.RB [ \-\-all ] ]
.br
.RB [ \-\-gcov\-tool
.IR tool ]
.br
.RB [ \-\-branch\-coverage ]
.br
.RB [ \-\-mcdc\-coverage ]
.br
.RB [ \-\-demangle\-cpp
.IR [ param ] ]
.br
.RB [ \-\-checksum ]
.RB [ \-\-no\-checksum ]
.RB [ \-\-no\-recursion ]
.RB [ \-f | \-\-follow ]
.br
.RB [ \-\-compat\-libtool ]
.RB [ \-\-no\-compat\-libtool ]
.br
.RB [ \-\-msg\-log
.IR [ log_file_name ] ]
.br
.RB [ \-\-ignore\-errors
.IR errors ]
.br
.RB [\-\-expect\-message\-count
.IR message_type=expr[,message_type=expr..]]
.br
.RB [ \-\-preserve ]
.RB [ \-\-to\-package
.IR package ]
.RB [ \-\-from\-package
.IR package ]
.RB [ \-\-no\-markers ]
.RB [ \-\-external ]
.RB [ \-\-no\-external ]
.br
.RB [ \-\-compat
.IR  mode =on|off|auto]
.br
.RB [ \-\-context\-script
.IR script_file ]
.br
.RB [ \-\-criteria\-script
.IR script_file ]
.br
.RB [ \-\-resolve-\-script
.IR script_file ]
.br
.RB [ \-\-version\-script
.IR script_file ]
.br
.RB [ \-\-comment
.IR comment_string ]
.br
.RB [ \-\-large\-file
.IR regexp ]
.br
.RE
.RE

Generate tracefile (from compiler-generated data) with all counter values set to zero:
.br

.RS 3
.B lcov
.BR \-z | \-\-zerocounters
.RS 4
.br
.RB [ \-d | \-\-directory
.IR directory ]
.RB [ \-\-no\-recursion ]
.RB [ \-f | \-\-follow ]
.br
.RE
.RE

Show coverage counts recorded in previously generated tracefile:
.br

.RS 3
.B lcov
.BR \-l | \-\-list
.I tracefile
.RS 4
.br
.RB [ \-\-list\-full\-path ]
.RB [ \-\-no\-list\-full\-path ]
.br
.RE
.RE

Aggregate multiple coverage tracefiles into one:
.br

.RS 3
.B lcov
.BR \-a | \-\-add\-tracefile
.I tracefile_pattern
.RS 4
.br
.RB [ \-o | \-\-output\-file
.IR tracefile ]
.br
.RB [ \-\-prune\-tests ]
.br
.RB [ \-\-forget\-test\-names ]
.br
.RB [ \-\-map\-functions ]
.br
.RB [ \-\-branch\-coverage ]
.br
.RB [ \-\-mcdc\-coverage ]
.br
.RB [ \-\-checksum ]
.RB [ \-\-no\-checksum ]
.br
.RE

Depending on your use model, it may not be necessary to create aggregate coverage data files.
For example, if your regression tests are split into multiple suites, you may want to keep separate suite data and to compare both per-suite and aggregate results over time.
.B genhtml
allows you specify tracefiles via one or more glob patterns - which enables you
generate aggregate reports without explicitly generating aggregated trace files.
See the
.B genhtml
man page.
.RE


Generate new tracefile from existing tracefile, keeping only data from files matching pattern:
.br

.RS 3
.B lcov
.BR \-e | \-\-extract
.I tracefile pattern
.RS 4
.br
.RB [ \-o | \-\-output\-file
.IR tracefile ]
.RB [ \-\-checksum ]
.RB [ \-\-no\-checksum ]
.br
.RE
.RE

Generate new tracefile from existing tracefile, removing data from files matching pattern:
.br

.RS 3
.B lcov
.BR \-r | \-\-remove
.I tracefile pattern
.RS 4
.br
.RB [ \-o | \-\-output\-file
.IR tracefile ]
.RB [ \-\-checksum ]
.RB [ \-\-no\-checksum ]
.br
.RE
.RE

Generate new tracefile from existing tracefiles by performing set operations on coverage data:
.br

.RS 3
.B lcov
.BR \-\-intersect
.I rh_glob_pattern
.RS 4
.br
.RB [ \-o | \-\-output\-file
.IR tracefile ]
.br
lh_glob_pattern


The output will reflect
.RS 2
.I (union of files matching lh_glob_patterns)
.I intersect
.I (union of files matching rh_glob_patterns)
.RE
such that coverpoints found in both sets are merged (summed) whereas coverpoints found in only one set are dropped.
Note that branch blocks are defined to be the same if and only if their block ID and the associated branch expressions list are identical.
Functions are defined to be the same if their name and location are identical.
.RE
.RE

.RS 3
.B lcov
.BR \-\-subtract
.I rh_glob_pattern
.RS 4
.br
.RB [ \-o | \-\-output\-file
.IR tracefile ]
.br
lh_glob_pattern

The output will reflect
.RS 2
.I (union of files matching lh_glob_patterns)
.I subtract
.I (union of files matching rh_glob_patterns)
.RE
such that coverpoints found only in the set on the left will be retained and all others are dropped.
.RE

.RE



Summarize tracefile content:
.br

.RS 3
.B lcov
.BR \-\-summary
.I tracefile
.RE

Print version or help message and exit:
.br

.RS 3
.B lcov
.RB [ \-h | \-\-help ]
.RB [ \-\-version ]
.RE

Common lcov options - supported by all the above use cases:
.br

.RS 3
.B lcov
.RB [ \-\-keep\-going ]
.br
.RS 5
.RB [ \-\-filter
.IR type  ]
.br
.br
.RB [ \-q | \-\-quiet ]
.br
.RB [ \-v | \-\-verbose ]
.br
.RB [ \-\-comment
.IR comment_string ]
.br
.RB [ \-\-debug ]
.br
.RB [ \-\-parallel | -j
.IR [integer] ]
.br
.RB [ \-\-memory
.IR integer_num_Mb ]
.br
.RB [ \-\-tempdir
.IR dirname ]
.br
.RB [ \-\-branch\-coverage ]
.br
.RB [ \-\-mcdc\-coverage ]
.br
.RB [ \-\-config\-file
.IR config\-file ]
.RB [ \-\-rc
.IR keyword = value ]
.br
.RB [ \-\-profile
.IR [ profile\-file ] ]
.br
.RB [ \-\-include
.IR glob_pattern ]
.br
.RB [ \-\-exclude
.IR glob_pattern ]
.br
.RB [ \-\-erase\-functions
.IR regexp_pattern ]
.br
.RB [ \-\-substitute
.IR regexp_pattern ]
.br
.RB [ \-\-omit\-lines
.IR regexp_pattern ]
.br
.RB [ \-\-fail\-under\-branches
.IR percentage ]
.br
.RB [ \-\-fail\-under\-lines
.IR percentage ]
.br
.RE
.RE

.SH DESCRIPTION
.B lcov
is a graphical front\-end for GCC's coverage testing tool gcov. It collects
line, function and branch coverage data for multiple source files and creates
HTML pages containing the source code annotated with coverage information.
It also adds overview pages for easy navigation within the file structure.

Use
.B lcov
to collect coverage data and
.B genhtml
to create HTML pages. Coverage data can either be collected from 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:
.RS
Follow the setup instructions for the gcov\-kernel infrastructure:
.I https://docs.kernel.org/dev-tools/gcov.html
.br
.RE

For user space application coverage:
.RS 3
Compile the application with GCC using the options
"\-fprofile\-arcs" and "\-ftest\-coverage" or "\-\-coverage".
.RE

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

Also note that when printing percentages, 0% and 100% are only printed when
the values are exactly 0% and 100% respectively. Other values which would
conventionally be rounded to 0% or 100% are instead printed as nearest
non-boundary value. This behavior is in accordance with that of the
.BR gcov (1)
tool.

By default,
.B lcov
and related tools generate and collect line and function coverage data.
Branch data is not collected or displayed by default; all tools support the
.B\ \--branch\-coverage
and
.B \-\-mdcd\-coverage
options to enable branch and MC/DC coverage, respectively - or you can permanently enable branch coverage by adding the appropriate
settings to your personal, group, or site lcov configuration file.  See man
.B lcovrc(5)
for details.

.SH OPTIONS

In general, (almost) all
.B lcov
options can also be specified in a configuration file - see man
.B lcovrc(5)
for details.


.B \-a
.I tracefile_pattern
.br
.B \-\-add\-tracefile
.I tracefile_pattern
.br
.RS
Add contents of all files matching glob pattern
.IR tracefile_pattern.

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.

The result of the add operation will be written to stdout or the tracefile
specified with \-o.

Only one of  \-z, \-c, \-a, \-e, \-r, \-l or \-\-summary may be
specified at a time.

.RE

.B \-b
.I directory
.br
.B \-\-base\-directory
.I directory
.br
.RS
.RI "Use " directory
as base directory for relative paths.

Use this option to specify the base directory of a build\-environment
when lcov produces error messages like:

.RS
ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c
.RE

In this example, use /home/user/project as base directory.

This option is required when using lcov on projects built with libtool or
similar build environments that work with a base directory, i.e. environments,
where the current working directory when invoking the compiler is not the same
directory in which the source code file is located.

Note that this option will not work in environments where multiple base
directories are used. In that case use configuration file setting
.B geninfo_auto_base=1
(see man
.BR lcovrc (5)
).

.RE

.B \-\-build\-directory
.I build_directory
.br
.RS
search for .gcno data files from build_directory rather than
adjacent to the corresponding .gcda file.

See man
.BR geninfo (1))
for details.


.RE
.BI "\-\-source\-directory " dirname
.RS
Add 'dirname' to the list of places to look for source files.
.br

For relative source file paths listed in
.I e.g.
paths found in
.IR tracefile,
or found in gcov output during
.I \-\-capture
\- possibly after substitutions have been applied -
.B lcov
 will first look for the path from 'cwd' (where genhtml was
invoked) and
then from each alternate directory name in the order specified.
The first location matching location is used.

This option can be specified multiple times, to add more directories to the source search path.


.RE
.B \-c
.br
.B \-\-capture
.br
.RS
Capture runtime 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.

The result of the capture operation will be written to stdout or the tracefile
specified with \-o.

When combined with the
.BR \-\-all
flag, both runtime and compile-time coverage will be extracted in one step.
See the description of the
.BR \-\-initial
flag, below.

See man
.BR geninfo (1))
for more details about the capture process and available options and parameters.


Only one of  \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be
specified at a time.
.RE

.B \-\-branch\-coverage
.RS
.br
Collect and/or retain branch coverage data.

This is equivalent to using the option "\-\-rc branch_coverage=1"; the option was added to better match the genhml interface.

.RE

.B \-\-mcdc\-coverage
.RS
.br
Collect retain MC/DC data.

This is equivalent to using the option "\-\-rc mcdc_coverage=1".
MC/DC coverage is supported for GCC versions 14.2 and higher, or
LLVM 18.1 and higher.
.br
See
.I llvm2lcov \-\-help
for details on MC/DC data capture in LLVM.

.br
See the MC/DC section of man
.B genhtml(1)
for more details

.RE

.B \-\-checksum
.br
.B \-\-no\-checksum
.br
.RS
Specify whether to generate checksum data when writing tracefiles and/or to
verify matching checksums when combining trace files.

Use \-\-checksum to enable checksum generation or \-\-no\-checksum to
disable it. Checksum generation is
.B disabled
by default.

When checksum generation is enabled, a checksum will be generated for each
source code line and stored along with the coverage data. This checksum will
be used to prevent attempts to combine coverage data from different source
code versions.

If you don't work with different source code versions, disable this option
to speed up coverage data processing and to reduce the size of tracefiles.

Note that this options is somewhat subsumed by the
.B \-\-version\-script
option - which does something similar, but at the 'whole file' level.
.RE

.B \-\-compat
.IR mode = value [, mode = value ,...]
.br
.RS
Set compatibility mode.

Use \-\-compat to specify that lcov should enable one or more compatibility
modes when capturing coverage data. You can provide a comma-separated list
of mode=value pairs to specify the values for multiple modes.

Valid
.I values
are:

.B on
.RS
Enable compatibility mode.
.RE
.B off
.RS
Disable compatibility mode.
.RE
.B auto
.RS
Apply auto-detection to determine if compatibility mode is required. Note that
auto-detection is not available for all compatibility modes.
.RE

If no value is specified, 'on' is assumed as default value.

Valid
.I modes
are:

.B libtool
.RS
Enable this mode if you are capturing coverage data for a project that
was built using the libtool mechanism. See also
\-\-compat\-libtool.

The default value for this setting is 'on'.

.RE
.B hammer
.RS
Enable this mode if you are capturing coverage data for a project that
was built using a version of GCC 3.3 that contains a modification
(hammer patch) of later GCC versions. You can identify a modified GCC 3.3
by checking the build directory of your project for files ending in the
extension '.bbg'. Unmodified versions of GCC 3.3 name these files '.bb'.

The default value for this setting is 'auto'.

.RE
.B split_crc
.RS
Enable this mode if you are capturing coverage data for a project that
was built using a version of GCC 4.6 that contains a modification
(split function checksums) of later GCC versions. Typical error messages
when running lcov on coverage data produced by such GCC versions are
\'out of memory' and 'reached unexpected end of file'.

The default value for this setting is 'auto'
.RE

.RE

.B \-\-compat\-libtool
.br
.B \-\-no\-compat\-libtool
.br
.RS
Specify whether to enable libtool compatibility mode.

Use \-\-compat\-libtool to enable libtool compatibility mode or \-\-no\-compat\-libtool
to disable it. The libtool compatibility mode is
.B enabled
by default.

When libtool compatibility mode is enabled, lcov will assume that the source
code relating to a .da file located in a directory named ".libs" can be
found in its parent directory.

If you have directories named ".libs" in your build environment but don't use
libtool, disable this option to prevent problems when capturing coverage data.
.RE

.B \-\-config\-file
.I config\-file
.br
.RS
Specify a configuration file to use.
See man
.B lcovrc(5)
for details of the file format and options.

When this option is specified, neither the system\-wide configuration file
/etc/lcovrc, nor the per\-user configuration file ~/.lcovrc is read.

This option may be useful when there is a need to run several
instances of
.B lcov
with different configuration file options in parallel.

Note that this option must be specified in full - abbreviations are not supported.

.RE

.B \-\-profile
.I [ profile\-data\-file ]
.br
.RS
Tell the tool to keep track of performance and other configuration data.
If the optional
.I profile\-data\-file
is not specified, then the profile data is written to a file named with the same
basename as the
.I \-\-output\-filename, with suffix
.I ".json"
appended.

.RE

Only one of  \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be
specified at a time.
.RE

.B \-d
.I directory
.br
.B \-\-directory
.I  directory
.br
.RS
Use .da files in
.I 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).

Note that you may specify this option more than once.
.RE

.B \-\-exclude
.I pattern
.br
.RS
Exclude source files matching
.IR pattern .

Use this switch if you want to exclude coverage data for a particular set
of source files matching any of the given patterns. Multiple patterns can be
specified by using multiple
.B --exclude
command line switches. The
.I patterns
will be interpreted as shell wildcard patterns (note that they may need to be
escaped accordingly to prevent the shell from expanding them first).

Note: The pattern must be specified to match the
.B absolute
path of each source file.
If you specify a pattern which does not seem to be correctly applied - files that you expected to be excluded still appear in the output - you can look for warning messages in the log file.
.B lcov
will emit a warning for every pattern which is not applied at least once.

Can be combined with the
.B --include
command line switch. If a given file matches both the include pattern and the
exclude pattern, the exclude pattern will take precedence.
.RE

.B \-\-erase\-functions
.I regexp
.br
.RS
Exclude coverage data from lines which fall within a function whose name matches the supplied regexp.  Note that this is a mangled or demangled name, depending on whether the \-\-demangle\-cpp option is used or not.

Note that this option requires that you use a gcc version which is new enough to support function begin/end line reports or that you configure the tool to derive the required dta - see the
.BI derive_function_end_line
discussion in man
.B lcovrc(5).

.RE
.B \-\-substitute
.I regexp_pattern
.br
.RS
Apply Perl regexp
.IR regexp_pattern
to source file names found during processing.  This is useful, for example, when the path name reported by gcov does not match your source layout and the file is not found, or in more complicated environments where the build directory structure does not match the source code layout or the layout in the projects's revision control system.

Use this option in situations where geninfo cannot find the correct
path to source code files of a project. By providing a
.I regexp_pattern
in Perl regular expression format (see man
.BR perlre (1)
), you can instruct geninfo to
remove or change parts of the incorrect source path.
Also see the
.B \-\-resolve\-script
option.

One or more
.I \-\-substitution
patterns and/or a
.I \-\-resolve-script
may be specified.  When multiple patterns are specified, they are applied in the order specified, substitution patterns first followed by the resolve callback.
The file search order is:
.RS
.IP 1. 3
Look for file name (unmodified).
.br
If the file exits: return it.
.PP
.IP 2. 3
Apply all substitution patterns in order - the result of the first pattern is used as the input of the second pattern, and so forth.
.br
If a file corresponding to the resulting name exists:  return it.
.PP
.IP 3. 3
Apply the 'resolve' callback to the final result of pattern substitutions.
.br
If a file corresponding to the resulting name exists:  return it.
.PP
.IP 4. 3
Otherwise:  return original (unmodified) file name.
.br
Depending on context, the unresolved file name may or may not result in an error.
.RE

Substitutions are used in multiple contexts by lcov/genhtml/geninfo:
.RS
.IP \-  3
during
.I \-\-capture,
applied to source file names found in gcov-generated coverage data files (see man
.B gcov(1)
).
.PP

.IP \- 3
during
.I \-\-capture,
applied to alternate
.I \-\-build\-dir
paths, when looking for the
.I .gcno
(compile time) data file corresponding to some
.I .gcda
(runtime) data file.
.PP

.IP \- 3
applied to file names found in lcov data files (".info" files) -
.I e.g.,
during lcov data aggregation or HTML and text report generation.
.br
For example, substituted names are used to find source files for
text-based filtering (see the
.I \-\-filter
section, below) and are passed to
.I \-\-version\-script, \-\-annotate\-script,
and
.I \-criteria\-script
callbacks.
.PP

.IP \- 3
applied to file names found in the
.I \-\-diff\-file
passed to genhtml.
.PP
.RE


.B Example:
.br

1. When geninfo reports that it cannot find source file
.br

    /path/to/src/.libs/file.c
.br

while the file is actually located in
.br

    /path/to/src/file.c
.br

use the following parameter:
.br

    \-\-substitute 's#/.libs##g'

This will remove all "/.libs" strings from the path.

2. When geninfo reports that it cannot find source file
.br

    /tmp/build/file.c
.br

while the file is actually located in
.br

    /usr/src/file.c
.br

use the following parameter:
.br

    \-\-substitute 's#/tmp/build#/usr/src#g'
.br

This will change all "/tmp/build" strings in the path to "/usr/src".
.PP

.RE

.B \-\-omit\-lines
.I regexp
.br
.RS
Exclude coverage data from lines whose content matches
.IR regexp .

Use this switch if you want to exclude line and branch coverage data for some particular constructs in your code (e.g., some complicated macro).  Multiple patterns can be
specified by using multiple
.B --omit\-lines
command line switches. The
.I regexp
will be interpreted as perl regular expressions (note that they may need to be
escaped accordingly to prevent the shell from expanding them first).
If you want the pattern to explicitly match from the start or end of the line, your regexp should start and/or end with "^" and/or "$".

Note that the
.B lcovrc
config file setting
.B lcov_excl_line = regexp
is similar to
.B \-\-omit\-lines.
.B \-\-omit\-lines
is useful if there are multiple teams each of which want to exclude certain patterns.
.B \-\-omit\-lines
is additive and can be specified across multiple config files whereas each call to
.B lcov_excl_line
overrides the previous value - and thus teams must coordinate.

.RE

.B \-\-external
.br
.B \-\-no\-external
.br
.RS
Specify whether to capture coverage data for external source files.

External source files are files which are not located in one of the directories
specified by
.I \-\-directory
or
.I \-\-base\-directory.
Use
.I \-\-external
to include
coverpoints in external source files while capturing coverage data or
.I \-\-no\-external
to exclude them.
If your
.I \-\-directory
or
.I \-\-base\-directory
path contains a soft link, then actual target directory is not considered to be
"internal" unless the
.I \-\-follow
option is used.

The
.I \-\-no\-external
option is somewhat of a blunt instrument;  the
.I \-\-exclude
and
.I \-\-include
options provide finer grained control over which coverage data is and is not
included if your project structure is complex and/or
.I \-\-no\-external
does not do what you want.

Data for external source files is
.B included
by default.

.RE

.B \-\-forget\-test\-names
.br
.RS
If non\-zero, ignore testcase names in .info file -
.I i.e.,
treat all coverage data as if it came from the same testcase.
This may improve performance and reduce memory consumption if user does
not need per-testcase coverage summary in coverage reports.

This option can also be configured permanently using the configuration file
option
.IR forget_testcase_names .

.RE

.B \-\-prune\-tests
.br
.RS
Determine list of unique tracefiles.

Use this option to determine a list of unique tracefiles from the list
specified by
.BR \-\-add\-tracefile .
A tracefile is considered to be unique if it is the only tracefile that:

.RS

.IP 1. 3
contains data for a specific source file