.TH lcovrc 5 "LCOV 2.0" 2023\-05\-17 "User Manuals"

.SH NAME
lcovrc \- lcov configuration file

.SH DESCRIPTION
The
.I lcovrc
file contains configuration information for the
.B lcov
code coverage tool (see
.BR lcov (1)).
.br

The system\-wide configuration file is located at
.IR $LCOV_HOME/etc/lcovrc .
This is typically either
.IR /etc/lcovrc
or
.IR /usr/local/etc/lcovrc
but may be wherever you have installed the lcov package.
To change settings for a single user, place a customized copy of this file at
location
.IR ~/.lcovrc .
Where available, command\-line options override configuration file settings.

The
.I genhtml, lcov,
and
.I geninfo
commands also support the
.I \-\-config\-file
option, which can be used to specify one or more files which should be used instead of the system or user default rc files.
Multiple options files may be useful if you have both project- and team-specific common options and want to ensure consistency across multiple users.  If multiple \-\-config\-file options are applied in the order they appear.
Note that the "\-\-config\-file" option name must be specified in full and cannot be abbreviated.  An error will occur if the option is not recognized.

Lines in a configuration file can either be:
.IP "     *"
empty lines or lines consisting only of white space characters. These lines are
ignored.
.IP "     *"
comment lines which start with a hash sign ('#'). These are treated like empty
lines and will be ignored.
.IP "     *"
statements in the form
.RI ' key " = " value '.

.IP "     *"
Values may be taken from environment variables via the syntax

.RI ' key " = " ... $ENV{ENV_VAR_NAME} ...'.

.RI
The substring '$ENV{ENV_VAR_NAME}' is replaced by the value of the environment variable.

.RI
One or more environment variables may be used to set the RC value.
'key' is ignored if any of the environment variables are not set in your user environment.

.PP
A list of valid statements and their description can be found in
section 'OPTIONS' below.
.br
.B NOTE
that there is no error checking of keys in the options file:  spelling errors
are simply seen as values which are not used by some particular tool.
If you are unsure of whether your options file is read or its values
applied, you can use the
.I \-\-verbose \-\-verbose
flag to enable printing of option value overrides.
(The option appears twice to enable a higher level of verbosity.)

Both 'list' and 'scalar' (non list) options are supported in the lcovrc file.

For scalar (non list) options:
.IP "     *"
if specified on the command line and in the lcovrc file, the value specified on the command line wins.
The value from the RC file is ignored.
.IP "     *"
Scalar options include:
.RI 'criteria_script " = " ...'
,
.RI 'genhtml_annotate_script " = " ...'
,
.RI 'version_script " = " ...'
, etc.
.PP
.PP

.PP
For list options:
.IP "     *"
the RC file entry can be used multiple times; each use appends to the list.
.br
For example, the entry below will result in two 'omit' patterns which will both be checked:
.IP "      "
# note explicit start/end line markers in the regexp
.br
omit_lines = ^\\s+//\\s*MY_EXCLUDE_MARKER\\s*$
.br
# Note that the regexp below matches anywhere on the line
.br
omit_lines = NR_CM_DBG_PRINT

.IP "     *"
If entries are specified on the command line, then the RC file entries are ignored:  command line wins.
If entries are specified in more than one RC file (i.e., multiple \-\-config\-file arguments are supplied), then RC files are applied in order of appearance, and list entries are appended in order.  For most list-type options, order is not important.


.IP "     *"
list options include:
.br
.RI "    filter = " ...
.br
.RI "    exclude = " ...
.br
.RI "    ignore = " ...
.br
.RI "    substitute = " ...
.br
.RI "    omit_lines = " ...
.br
.RI "    erase_functions = " ...
.br
.RI "    genhtml_annotate_script = " ...
.br
.I etc.
For a complete set of list options, see the documentation of each configuration option, below.
.PP

.PP
.PP

.B Example configuration:

Note that this example does not include all possible configuration
options.
.br
In general:  (almost) all command line options can be specified in
the configuration file instead, whereas some configuration file options
have no command line equivalent.

See the OPTIONS section below for details.
.IP
#
.br
# Example LCOV configuration file
.br
#
.br

# External style sheet file
.br
#genhtml_css_file = gcov.css
.br

# Use 'dark' mode display (light foreground/dark background)
.br
# rather than default
.br
#genhtml_dark_mode = 1
.br

# Alternate header text to use at top of each page
.br
#genhtml_header = Coverage report for my project

.br

# Alternate footer text to use at the bottom of each page
.br
#genhtml_footer = My footer text
.br

# Coverage rate limits
.br
genhtml_hi_limit = 90
.br
genhtml_med_limit = 75
.br

# Ignore some errors (comma-separated list)
.br
#ignore_errors = empty,mismatch
.br

# Stop emitting message after this number have been printed
.br
# 0 == no limit
.br
max_message_count = 100

.br
# If nonzero, do not stop when an 'ignorable error' occurs - try
.br
#  to generate a result, however flawed.  This is equivalent to
.br
#  the '--keep-going' command line switch.
.br
# Default is 1:  stop when error occurs
.br
#stop_on_error = 1

.br
# If nonzero, treat warnings as error
.br
# note that ignored messages will still appear as warnings
.br
# Default is 0
.br
#treat_warning_as_error = 1

.br
# If set to non-zero, only issue particular warning once per file
.br
# Default is 1
.br
#warn_once_per_file = 1

.br
# extension associated with lcov trace files - glob match pattern
.br
# used as argument to 'find' - to find coverage files contained in
.br
# a directory argument
.br
#info_file_pattern = *.info
.br

# list of file extensions which should be treated as C/C++ code
.br
# (comma-separated list)
.br
#c_file_extensions = h,c,cpp,hpp
.br

# list of file extensions which should be treated as RTL code
.br
# (e.g., Verilog) (comma-separated list)
.br
#rtl_file_extensions = v,vh,sv
.br

# list of file extensions which should be treated as Java code
.br
#java_file_extensions = java

# list of file extensions which should be treated as perl code
.br
#perl_file_extensions = pl,pm
.br

# list of file extensions which should be treated as python code
.br
#python_file_extensions = py
.br

# maximum number of lines to look at, when filtering bogus branch expressions
.br
#filter_lookahead = 5
.br

# if nonzero, bitwise operators '|', '&', '~' indicate conditional expressions
.br
#filter_bitwise_conditional = 1
.br
.br
# if nonzero, '--filter blank' is applied to blank lines, regardless
.br
# of their hit count
.br
#filter_blank_aggressive = 1
.br
.br

# Width of line coverage field in source code view
.br
genhtml_line_field_width = 12
.br

# Width of branch coverage field in source code view
.br
genhtml_branch_field_width = 16
.br

# Width of MC/DC coverage field in source code view
.br
genhtml_mcdc_field_width = 14
.br

# width of 'owner' field in source code view - default is 20
.br
genhtml_owner_field_width = 20
.br
# width of 'age' field in source code view - default is 5
.br
genhtml_age_field_width = 5
.br

# Width of overview image
.br
genhtml_overview_width = 80
.br

# Resolution of overview navigation
.br
genhtml_nav_resolution = 4
.br

# Offset for source code navigation
.br
genhtml_nav_offset = 10
.br

# Do not remove unused test descriptions if non\-zero
.br
genhtml_keep_descriptions = 0
.br

# Do not remove prefix from directory names if non\-zero
.br
genhtml_no_prefix = 0
.br

# Do not create source code view if non\-zero
.br
genhtml_no_source = 0
.br

# Specify size of tabs
.br
genhtml_num_spaces = 8
.br

# Include color legend in HTML output if non\-zero
.br
genhtml_legend = 0
.br

# Include HTML file at start of HTML output
.br
#genhtml_html_prolog = prolog.html
.br

# Include HTML file at end of HTML output
.br
#genhtml_html_epilog = epilog.html
.br

# Use custom HTML file extension
.br
#genhtml_html_extension = html
.br

# Compress all generated html files with gzip.
.br
#genhtml_html_gzip = 1
.br

# Include sorted overview pages
.br
genhtml_sort = 1
.br

# Display coverage data in hierarchical directory structure
.br
# (rather than flat/3 level)
.br
#genhtml_hierarchical = 1
.br

# Display coverage data using 'flat' view
.br
#genhtml_flat_view = 1
.br

# Specify the character set of all generated HTML pages
.br
genhtml_charset=UTF\-8
.br

# Allow HTML markup in test case description text if non\-zero
.br
genhtml_desc_html=0
.br

# Specify the precision for coverage rates
.br
#genhtml_precision=1
.br

# Show missed counts instead of hit counts
.br
#genhtml_missed=1
.br

# group function aliases in report - see '--merge' section in man(1) genhtml
.br
#merge_function_aliasess = 1
.br

# If set, suppress list of aliases in function detail table
.br
#suppress_function_aliases = 1
.br

# If set, derive function end line from line coverpoint data - default ON
.br
#derive_function_end_line = 1
.br

# If set, derive function end lines for all file types.
# By default, we derive end lines for C/C++ files only
#
.br
#derive_end_line_all_files = 0
.br

# Maximum size of function (number lines) which will be checked by '--filter trivial'
.br
#trivial_function_threshold = 5
.br

# Set threshold for hit count which tool should deem likely to indicate
.br
# a toolchain bug (corrupt coverage data)
.br
# excessive_count_theshold = number
.br

# Demangle C++ symbols
.br
# Call multiple times to specify command and command line arguments
.br
#  ('-Xlinker'-like behaviour)
.br
#demangle_cpp = c++filt
.br

# Name of the tool used for demangling C++ function names
.br
# This argument is deprecated - please use demangle_cpp' instead
.br
#genhtml_demangle_cpp_tool = c++filt
.br

# Specify extra parameters to be passed to the demangling tool
.br
#  this argument is deprecated - use Xlinker-like demangle_cpp
.br
#  parameter instead
.br
#genhtml_demangle_cpp_params = ""
.br

# Location of the gcov tool
.br
#geninfo_gcov_tool = gcov
.br

# Adjust test names if non\-zero
.br
#geninfo_adjust_testname = 0
.br

# Ignore testcase names in .info file
forget_testcase_names = 0

# Calculate and/or compute checksum for each line if non\-zero
.br
checksum = 0
.br

# Enable libtool compatibility mode if non\-zero
.br
geninfo_compat_libtool = 0
.br

# Specify whether to capture coverage data for external source
.br
# files
.br
#geninfo_external = 1
.br

# Specify whether to capture coverage data from compile-time data files
.br
# which have no corresponding runtime data.
.br
#geninfo_capture_all = 1
.br

# Use gcov's --all-blocks option if non-zero
.br
#geninfo_gcov_all_blocks = 1
.br

# Adjust 'executed' non-zero hit count of lines which contain no branches
.br
# and have attribute '"unexecuted_blocks": true'
.br
#geninfo_unexecuted_blocks = 0
.br

# Specify compatibility modes (same as \-\-compat option
.br
# of geninfo)
.br
#geninfo_compat = libtool=on, hammer=auto, split_crc=auto
.br

# Adjust path to source files by removing or changing path
.br
# components that match the specified pattern (Perl regular
.br
# expression format)
.br
#geninfo_adjust_src_path = /tmp/build => /usr/src

# Specify if geninfo should try to automatically determine
.br
# the base-directory when collecting coverage data.
.br
geninfo_auto_base = 1
.br

# Use gcov intermediate format? Valid values are 0, 1, auto
.br
geninfo_intermediate = auto
.br

# Specify if exception branches should be excluded from branch coverage.
.br
no_exception_branch = 0
.br

# Directory containing gcov kernel files
.br
lcov_gcov_dir = /proc/gcov
.br

# Location for temporary directories
.br
lcov_tmp_dir = /tmp
.br

# Show full paths during list operation if non\-zero
.br
lcov_list_full_path = 0
.br

# Specify the maximum width for list output. This value is
.br
# ignored when lcov_list_full_path is non\-zero.
.br
lcov_list_width = 80
.br

# Specify the maximum percentage of file names which may be
.br
# truncated when choosing a directory prefix in list output.
.br
# This value is ignored when lcov_list_full_path is non\-zero.
.br
lcov_list_truncate_max = 20

# Specify if function coverage data should be collected, processed, and
.br
# displayed.
.br
function_coverage = 1
.br

# Specify if branch coverage data should be collected, processed, and
.br
# displayed.
.br
branch_coverage = 0
.br

# Specify if Modified Condition / Decision Coveage data should be collected,
.br
#  processed, and displayed.
.br
mcdc_coverage = 0
.br

# Ask lcov/genhtml/geninfo to return non-zero exit code if branch coverage is
.br
# below specified threshold percentage.
.br
fail_under_branches = 75.0
.br

# Ask lcov/genhtml/geninfo to return non-zero exit code if line coverage is
.br
# below specified threshold percentage.
.br
#fail_under_lines = 97.5
.br

# Specify JSON module to use, or choose best available if
.br
# set to auto
.br
lcov_json_module = auto
.br

# Specify maximum number of parallel slaves
.br
# default: 1 (no parallelism)
.br
#parallel = 1
.br

.br
# Specify maximum memory to use during parallel processing, in Mb.
.br
# Do not fork if estimated memory consumption exceeds this number.
.br
# default: 0 (no limit)
.br
#memory = 1024
.br

.br
# Specify the number of consecutive fork() failures to allow before
.br
# giving up
.br
# max_fork_fails = 5
.br

.br
# Seconds to wait after failing to fork() before retrying
.br
# fork_fail_timeout = 10
.br

.br
# Throttling control:  specify a percentage of system memory to use as
.br
maximum during parallel processing.
.br
# Do not fork if estimated memory consumption exceeds the maximum.
.br
# this value is used only if the maximum memory is not set.
.br
# default: not set
.br
#memory_percentage = 75
.br

.br
# Character used to split list-type parameters
.br
#  \- for example, the list of "--ignore_errors source,mismatch"
.br
# default: , (comma)
.br
#split_char = ,
.br


.br
# use case insensitive compare to find matching files, for include/exclude
.br
#  directives, etc
.br
#case_insensitive = 0
.br

.br
# override line default line exclusion regexp
.br
#lcov_excl_line = LCOV_EXCL_LINE
.br

.br
# override branch exclusion regexp
.br
#lcov_excl_br_line = LCOV_EXCL_BR_LINE
.br

.br
# override exception branch exclusion regexp
.br
#lcov_excl_exception_br_line = LCOV_EXCL_EXCEPTION_BR_LINE
.br

.br
# override start of exclude region regexp
.br
#lcov_excl_start = LCOV_EXCL_START
.br

.br
# override end of exclude region regexp
.br
#lcov_excl_stop = LCOV_EXCL_STOP
.br

.br
# override start of branch exclude region regexp
.br
#lcov_excl_br_start = LCOV_EXCL_BR_START
.br

.br
# override start of exclude region regexp
.br
#lcov_excl_br_stop = LCOV_EXCL_BR_STOP
.br

.br
# override start of exclude region regexp
.br
#lcov_excl_exception_br_start = LCOV_EXCL_EXCEPTION_BR_START
.br

.br
# override start of exclude region regexp
.br
#lcov_excl_exception_br_stop = LCOV_EXCL_EXCEPTION_BR_STOP

.PP

.SH OPTIONS

.BR genhtml_css_file " ="
.I filename
.IP
Specify an external style sheet file. Use this option to modify the appearance of the HTML output as generated by
.BR genhtml .
During output generation, a copy of this file will be placed in the output
directory.
.br

This option corresponds to the \-\-css\-file command line option of
.BR genhtml .
.br

By default, a standard CSS file is generated.
.PP

.BR genhtml_header " ="
.I string
.IP

Specify header text to use ta top of each HTML page.
.br

This option corresponds to the \-\-header\-title command line option of
.BR genhtml .
.br
Default is "LCOV - (differential )? coverage report"

.PP

.BR genhtml_footer " ="
.I string
.IP
Specify footer text to use at bottom of each HTML page.
.br

This option corresponds to the \-\-footer command line option of
.BR genhtml .
.br

Default is LCOV tool version string.

.PP

.BR genhtml_dark_mode " ="
.IR  0 | 1
.IP
If non-zero, display using light text on dark background rather than dark text on light background.
.br

This option corresponds to the \-\-dark\-mode command line option of
.BR genhtml .
.br

By default, a 'light' palette is used.
.PP

.BR genhtml_hi_limit "  ="
.I hi_limit
.br
.BR genhtml_med_limit " ="
.I med_limit
.br
.IP
Specify coverage rate limits for classifying file entries. Use this option to
modify the coverage rates (in percent) for line, function and branch coverage at
which a result is classified as high, medium or low coverage. This
classification affects the color of the corresponding entries on the overview
pages of the HTML output:
.br

High:   hi_limit  <= rate <= 100        default color: green
.br
Medium: med_limit <= rate < hi_limit    default color: yellow
.br
Low:    0         <= rate < med_limit   default color: red
.br

Defaults are 90 and 75 percent.

There are also options to configure different thresholds for line, branch, and function coverages.  See below.
.PP

.BR genhtml_line_hi_limit "  ="
.I line_hi_limit
.br
.BR genhtml_line_med_limit " ="
.I line_med_limit
.br
.IP
Specify specific threshold for line coverage limits used to decide whether a particular line coverage percentage is classified as high, medium, or low coverage.
If the line-specific values are not specified, then the default
.I genhtml_med_limit
or
.I genhtml_hi_limit
values are used.
.PP

.BR genhtml_branch_hi_limit "  ="
.I branch_hi_limit
.br
.BR genhtml_branch_med_limit " ="
.I branch_med_limit
.br
.IP
Specify specific threshold for branch coverage limits used to decide whether a particular branch coverage percentage is classified as high, medium, or low coverage.
If the branch-specific values are not specified, then the default
.I genhtml_med_limit
or
.I genhtml_hi_limit
values are used.
.PP

.BR genhtml_function_hi_limit "  ="
.I function_hi_limit
.br
.BR genhtml_function_med_limit " ="
.I function_med_limit
.br
.IP
Specify specific threshold for function coverage limits used to decide whether a particular function coverage percentage is classified as high, medium, or low coverage.
If the function-specific values are not specified, then the default
.I genhtml_med_limit
or
.I genhtml_hi_limit
value is used.
.PP

.BR rtl_file_extensions " ="
.IR str[,str]+
.IP
Specify a comma-separated list of file extensions which should be assumed to be RTL code (e.g., Verilog).
.br

If not specified, the default set is 'v,vh,sv,vhdl?'.
There is no command line option equivalent.
.br
This option is used by genhtml and lcov.

.PP

.BR info_file_pattern " ="
.IR str
.IP
Specify a glob-match pattern associated with lcov trace files (suitable as an argument to 'find'.
If not specified, the default is '*.info'.

.PP

.BR c_file_extensions " ="
.IR str[,str]+
.IP
Specify a comma-separated list of file extensions which should be assumed to be C/C++ code.
.br

If not specified, the default set is 'c,h,i,C,H,I,icc,cpp,cc,cxx,hh,hpp,hxx'.
If you want all files to be treated as C/C++ code, you can use:
.I c_file_extensions = .*

This parameter must be set from the lcovrc file or via the
.I \-\-rc name=value
command line option; note that you may need to protect the value from shell expansion in the latter case.
.br

.PP

.BR java_file_extensions " ="
.IR str[,str]+
.IP
Specify a comma-separated list of file extensions which should be assumed to be Java code.
.br

If not specified, the default set is 'java'.
If you want all files to be treated as Java code, you can use:
.I java_file_extensions = .*

This parameter must be set from the lcovrc file or via the
.I \-\-rc name=value
command line option; note that you may need to protect the value from shell expansion in the latter case.
.br

.PP

.BR perl_file_extensions " ="
.IR str[,str]+
.IP
Specify a comma-separated list of file extensions which should be assumed to be Perl code.
.br

If not specified, the default set is 'pl,pm'.
If you want all files to be treated as Perl code, you can use:
.I perl_file_extensions = .*

This parameter must be set from the lcovrc file or via the
.I \-\-rc name=value
command line option; note that you may need to protect the value from shell expansion in the latter case.
.br

.PP

.BR python_file_extensions " ="
.IR str[,str]+
.IP
Specify a comma-separated list of file extensions which should be assumed to be Python code.
.br

If not specified, the default set is 'py'.
If you want all files to be treated as Python code, you can use:
.I python_file_extensions = .*

This parameter must be set from the lcovrc file or via the
.I \-\-rc name=value
command line option; note that you may need to protect the value from shell expansion in the latter case.
.br


.PP

.BR filter_lookahead " ="
.IR integer
.IP
Specify the maximum number of lines to look at when filtering bogus branch expressions.
A larger number may catch more cases, but will increase execution time.
.br

If not specified, the default set is 10.
There is no command line option equivalent.
.br
This option is used by genhtml and lcov.

.PP

.BR filter_bitwise_conditional " ="
.IR 0|1
.IP
If set to non-zero value, bogus branch filtering will assume that expressions containing  bitwise operators '&', '|', '~' are conditional expressions - and will not filter them out.
.br

If not specified, the default set is 0 (do not treat them as conditional).
There is no command line option equivalent.
.br
This option is used by genhtml and lcov.

.PP

.BR filter_blank_aggressive " ="
.IR 0|1
.IP
If set to non-zero value, then blank source lines will be ignored whether
or not their 'hit' count is zero.
See the
.I \-\-filter blank
section in man
.B genhtml(1).
.br

If not specified, the default set is 0 (filter blank lines only if they are not hit).
.br
There is no command line option equivalent.

.PP

.BR ignore_errors " ="
.IR message_type(,message_type)*
.IP
Specify a  message type which should be ignored.
.br

This option can be used multiple times in the lcovrc file to ignore multiple message types.

This option is equivalent to the \-\-ignore\-errors option to geninfo, genhtml, or lcov.  Note that the lcovrc file message list is not applied (those messages NOT ignored) if the '\-\-ignore\-errors' command line option is specified.
.br
This option is used by genhtml, lcov, and geninfo.

.PP

.BR expect_message_count " ="
.IR message_type:expr(,message_type:expr)*
.IP
Specify
a constraint on the number of messages of one or more types which are expected to
be produced during tool execution.  If the constraint is not true, an
error of type
.I "count"
will be generated.

Multiple constraints can be specified using a comma-separated list or
by using the option multiple times.


Substitutions are performed on the expression before it is evaluated:

For example:

.RS 3

.IP \- 3
expect_message_count = inconsistent : %C == 5
.br
says that you expect exactly 5 messages of this type
.PP

.IP \- 3
expect_message_count inconsistent : %C > 6 && %C <= 10
.br
says that you expect the number of messages to be in the range (6:10].
.PP

.RE

This option is useful if errors are caused by conditions that you cannot
fix - for example, due to inconsistent coverage data generated by your
toolchain.  In those scenarios, you may decide:

.RS 3

.IP \- 3
to exclude the offending code, or
.PP
.IP \- 3
to exclude the entire offending file(s), or
.PP
.IP \- 3
to ignore the
messages, either by converting them to warnings or suppressing them entirely.
.PP
.RE

In the latter case, this option provides some additional safety by warning
you when the count differs due to some change which occurred, giving you
the opportunity to diagnose the change and/or to review message changes.

This option is equivalent to the
.I "\-\-expect\-message\-count"
command line flag.

.PP

.BR max_message_count " ="
.IR integer
.IP
Set the maximum number of warnings of any particular type which should be emitted. This can be used to reduce the size of log files.
.br

No more warnings will be printed after this number is reached.  0 (zero) is interpreted as 'no limit'.
.br
This option is used by genhtml, lcov, and geninfo.

.PP

.BR stop_on_error " = "
.IR 0|1
.IP
If set to 0, tell the tools to ignore errors and keep going to try to generate a result - however flawed or incomplete that result might be.
Note that some errors cannot be ignored and that ignoring some errors may lead to other errors.
.br
The tool will return a non-zero exit code if one or more errors are detected
during execution when
.I stop_on_error
is disabled.  That is, the tool will continue execution in the presence
of errors but will return an exit status.

.br

This is equivalent to the
.I '\-\-keep\-going'
command line option.

Default is 1:  stop when error occurs.

If the
.I 'ignore_error msgType'
option is also used, then those messages will be treated as warnings rather than errors (or will be entirely suppressed if the message type appears multiple times in the ignore_messages option).  Warnings do not cause a non-zero exit status.

This option is used by genhtml, lcov, and geninfo.


.PP

.BR treat_warning_as_error " = "
.IR 0|1
.IP
If set to 1, tell the tools that messages which are normally treated as
warnings (
.I e.g.,
certain usage messages) should be treated as errors.

Note that ignored messages will still appear as warnings:  see the
.I ignore_errors
entry, above.

This option is used by genhtml, lcov, and geninfo.

.PP

.BR warn_once_per_file " = "
.IR 0|1
.IP
If set to 1, tell the tools to emit certain errors only once per file
(rather than multiple times, if the issue occurs multiple times in the same
file).

Default is 1:  do not report additional errors.

This option is used by genhtml, lcov, and geninfo.

.PP

.BR check_data_consistency " = "
.IR 0|1
.IP
If set to 1, tell the tools to execute certain data consistency checks -
.I e.g.,
that function with a non-zero hit count contains at least one line with a non-zero
hit count - and vice versa.

It may be useful to use this option to disable checking if you have inconsistent
legacy data and have
no way to correct or exclude it.

Default is 1:  execute consistency checks.

.PP

.BR genhtml_line_field_width " ="
.I number_of_characters
.IP
Specify the width (in characters) of the source code view column containing
line coverage information.
.br

Default is 12.
.PP

.BR genhtml_branch_field_width " ="
.I number_of_characters
.IP
Specify the width (in characters) of the source code view column containing
branch coverage information.
.br

Default is 16.
.PP

.BR genhtml_mcdc_field_width " ="
.I number_of_characters
.IP
Specify the width (in characters) of the source code view column containing
MC/DC coverage information.
.br

Default is 14.
.PP

.BR genhtml_owner_field_width " ="
.I number_of_characters
.IP
Specify the width (in characters) of the source code view column containing
owner information (as reported by your annotation script.  This option has an effect only if you are using a source annotation script:  see the \-\-annotation-script option in the genhtml man page.
.br

Default is 20.
.PP

.BR genhtml_age_field_width " ="
.I number_of_characters
.IP
Specify the width (in characters) of the source code view column containing
age of the corresponding block (as reported by your annotation script).   This option has an effect only if you are using a source annotation script:  see the \-\-annotation-script option in the genhtml man page.
.br

Default is 5.
.PP

.BR genhtml_frames " ="
.I 0 | 1
.IP
Specify whether source detail view should contain a navigation image.
See the
.I \-\-frame
entry in the
.B genhtml
man page.
.PP

.BR genhtml_overview_width " ="
.I pixel_size
.IP
Specify the width (in pixel) of the overview image created when generating HTML
output using the \-\-frames option of
.BR genhtml .
.br

Default is 80.
.PP

.BR genhtml_nav_resolution " ="
.I lines
.IP
Specify the resolution of overview navigation when generating HTML output using
the \-\-frames option of
.BR genhtml .
This number specifies the maximum difference in lines between the position a
user selected from the overview and the position the source code window is
scrolled to.
.br

Default is 4.
.PP


.BR genhtml_nav_offset " ="
.I lines
.IP
Specify the overview navigation line offset as applied when generating HTML
output using the \-\-frames option of
.BR genhtml.
.br

Clicking a line in the overview image should show the source code view at
a position a bit further up, so that the requested line is not the first
line in the window.  This number specifies that offset.
.br

Default is 10.
.PP


.BR genhtml_keep_descriptions " ="
.IR 0 | 1
.IP
If non\-zero, keep unused test descriptions when generating HTML output using
.BR genhtml .
.br

This option corresponds to the \-\-keep\-descriptions option of
.BR genhtml .
.br

Default is 0.
.PP

.BR genhtml_no_prefix " ="
.IR 0 | 1
.IP
If non\-zero, do not try to find and remove a common prefix from directory names.
.br

This option corresponds to the \-\-no\-prefix option of
.BR genhtml .
.br

Default is 0.
.PP

.BR genhtml_no_source " ="
.IR 0 | 1
.IP
If non\-zero, do not create a source code view when generating HTML output using
.BR genhtml .
.br

This option corresponds to the \-\-no\-source option of
.BR genhtml .
.br

Default is 0.
.PP

.BR genhtml_num_spaces " ="
.I num
.IP
Specify the number of spaces to use as replacement for tab characters in the
HTML source code view as generated by
.BR genhtml .
.br

This option corresponds to the \-\-num\-spaces option of
.BR genhtml .
.br

Default is 8.

.PP

.BR genhtml_legend " ="
.IR 0 | 1
.IP
If non\-zero, include a legend explaining the meaning of color coding in the HTML
output as generated by
.BR genhtml .
.br

This option corresponds to the \-\-legend option of
.BR genhtml .
.br

Default is 0.
.PP

.BR genhtml_html_prolog " ="
.I filename
.IP
If set, include the contents of the specified file at the beginning of HTML
output.

This option corresponds to the \-\-html\-prolog option of
.BR genhtml .
.br

Default is to use no extra prolog.
.PP

.BR genhtml_html_epilog " ="
.I filename
.IP
If set, include the contents of the specified file at the end of HTML output.

This option corresponds to the \-\-html\-epilog option of
.BR genhtml .
.br

Default is to use no extra epilog.
.PP

.BR genhtml_html_extension " ="
.I extension
.IP
If set, use the specified string as filename extension for generated HTML files.

This option corresponds to the \-\-html\-extension option of
.BR genhtml .
.br

Default extension is "html".
.PP

.BR genhtml_html_gzip " ="
.IR 0 | 1
.IP
If set, compress all html files using gzip.

This option corresponds to the \-\-html\-gzip option of
.BR genhtml .
.br

Default extension is 0.
.PP

.BR genhtml_sort " ="
.IR 0 | 1
.IP
If non\-zero, create overview pages sorted by coverage rates when generating
HTML output using
.BR genhtml .
.br

This option can be set to 0 by using the \-\-no\-sort option of
.BR genhtml .
.br

Default is 1.
.PP

.BR genhtml_hierarchical " ="
.IR 0 | 1
.IP
If non\-zero, the HTML report will follow the hierarchical directory structure of the source code.
.br

This option is equivalent to using the \-\-hierarchical command line option of
.BR genhtml .
'Hierarchical' and 'flat' views are mutually exclusive.
.br

Default is 0.
.PP

.BR genhtml_flat_view " ="
.IR 0 | 1
.IP
If non\-zero, the top-level HTML table will contain all of the files in the project and there will be no intermediate directory pages.
.br

This option is equivalent to using the \-\-flat command line option of
.BR genhtml .
'Hierarchical' and 'flat' views are mutually exclusive.
.br

Default is 0.
.PP

.BR genhtml_show_navigation " ="
.IR 0 | 1
.IP
If non\-zero, the 'source code' view summary table will contain hyperlinks from the number to the first source line in the corresponding category ('Hit' or 'Not hit') in the non-differential coverage report.
Source code hyperlinks are always enabled in differential coverage reports.
.br

This option is equivalent to using the \-\-show\-navigation command line option of
.BR genhtml .
.br

Default is 0.
.PP

.BR genhtml_show_owner_table " ="
.IR 0 | 1 | all
.IP
If non\-zero, equivalent to the genhtml
.I \-\-shwow\-owners
flag: see man
.B genhtml(1)
for details.
.br

Default is 0.
.PP

.BR compact_summary_tables " ="
.IR 0 | 1
.IP
If non\-zero, suppress the 'Total' row in the 'date' and 'owner' summary table if there is only one element in the corresponding bin.
.br
When there are a large number of files with a single author, this can cut the summary table size by almost half.
.br

Default is 1 (enabled).
.PP

.BR owner_table_entries " ="
.IR integer
.IP
This option is used to tell genhtml the number of 'owner' table entries to
retain in the summary table (at the top of the page) if owner table truncation is requested.  Authors are sorted by quantity of un-exercised code - so elided entries will be smaller offenders: maximal offenders are retained.
If the option is not set, then owner tables are not truncated.

This option has no effect unless
.I "genhtml \-\-show\-owners"
is enabled.
See the
.I \-\-show-owners
option in
.B genhtml(1)
for details.

.br

Default is not set (
.I i.e.,
do not truncate owner tables).
.PP

.BR truncate_owner_table " ="
.IR comma_separated_list
.IP
This option is used to tell genhtml whether to truncate the 'owner' table
at the top, directory, or file level.
This option acts together with the
.I owner_table_entries
parameter to determine how many author entries are retained.

This option has no effect unless
.I "genhtml \-\-show\-owners"
is enabled and and the
.I owner_table_entries
configuration is set.

If this option is set multiple times in the lcovrc file, the values are
combined to form the list of levels where truncation will occur.
Similarly, if this option is not set and
.I owner_table_entries
is set, then the table will be truncated everywhere.

See the
.I \-\-show-owners
option in
.B genhtml(1)
for details.
.br

Default is to not truncate the list.
.PP



.BR genhtml_show_noncode_owners " ="
.IR 0 | 1
.IP
If non\-zero, equivalent to the genhtml
.I \-\-shwow\-noncode
flag: see man
.B genhtml(1)
for details.
.br

Default is 0.
.PP

.BR genhtml_show_function_proportion " ="
.IR 0 | 1
.IP

If nonzero, add column to "function coverage detail" table to show the proportion of lines and branches within the function which are exercised.
.br

This option is equivalent to using the \-\-show\-proportion command line option of
.BR genhtml .
.br

Default is 0.
.PP

.BR genhtml_synthesize_missing " ="
.IR 0 | 1
.IP
If non\-zero, equivalent to the genhtml
.I \-\-synthesize\-missing
flag: see man
.B genhtml(1)
for details.
.br

Default is 0.
.PP

.BR genhtml_charset " ="
.I charset
.IP
Specify the character set of all generated HTML pages.
.br

Use this option if the source code contains characters which are not
part of the default character set. Note that this option is ignored
when a custom HTML prolog is specified (see also
.BR genhtml_html_prolog ).
.br

Default is UTF-8.
.PP

.BR demangle_cpp " ="
.IR c++filt
.IP
If set, this option tells genhtml/lcov/geninfo to demangle C++ function names  in function overviews,
and gives the name of the tool used for demangling.
Set this option to one if you want to convert C++ internal function
names to human readable format for display on the HTML function overview
page.

If the
.I demangle_cpp
option is used multiple times, then the arguments are concatenated when the callback
is executed - similar to how the gcc
.I \-Xlinker
parameter works.  This provides a possibly easier way to pass arguments to
your tool, without requiring a wrapper script.
In that case, your callback will be executed as:
.I | tool\-0 'tool\-1; ...
Arguments are quoted when passed to
the shell, in order to handle parameters which contain spaces.

Note that the demangling tool is called via a pipe, and is expected to read from stdin and write to stdout.

This option corresponds to the \-\-demangle\-cpp command line option of
.BR genhtml .
.br

Default is not set (C++ demangling is disabled).
.PP

.BR genhtml_demangle_cpp_tool " ="
.I path_to_c++filt
.IP
Specify the location of the demangle tool (see
.BR c++filt (1))
used to convert C++ internal function names to human readable format
for display on the HTML function overview page.

This option is deprecated and will be removed from a future lcov release.
Please use
.I demangle_cpp = path_to_c++filt
instead.

.PP

.BR genhtml_demangle_cpp_params " ="
.I parameters
.IP
Specify extra parameters to be passed to the demangling tool

Use this option if your environment requires additional parameters such
as --no-strip-underscore for correctly demangling C++ internal function
names. See also
.BR c++filt (1)).
.br

This argument is deprecated.  Please use the Xlinker-like
.I demangle_cpp
argument instead.

.PP

.BR genhtml_desc_html " ="
.IR 0 | 1
.IP
If non-zero, test case descriptions may contain HTML markup.

Set this option to one if you want to embed HTML markup (for example to
include links) in test case descriptions. When set to zero, HTML markup
characters will be escaped to show up as plain text on the test case
description page.
.br

Default is 0.
.PP

.BR genhtml_precision " ="
.IR  1 | 2 | 3 | 4
.IP
Specify how many digits after the decimal-point should be used for
displaying coverage rates.
.br

Default is 1.
.PP
.BR merge_function_aliases " ="
.IR  0 | 1
.IP
If non-zero, group function aliases in the function detail tabile.
See man(1) genhtml.
.br

Default is 0.
.PP

.PP
.BR genhtml_missed " ="
.IR  0 | 1
.IP
If non-zero, the count of missed lines, functions, or branches is shown
as negative numbers in overview pages.
.br

Default is 0.
.PP

.BR suppress_function_aliases " ="
.IR  0 | 1
.IP
If non-zero, do not show aliases in the function detail table.
.br
If nonzero, implies that
.B merge_function_aliases
is enabled.
.br
See the genhtml man page for more details.
.br

Default is 0.
.PP

.BR derive_function_end_line " ="
.IR  0 | 1
.IP
If non-zero, use 'line' coverage data to deduce the end line of each function
definition.  This is useful when excluding certain functions from your coverage report.  See the
.I \-\-erase\-functions,
.I \-\-filter trivial
and
.I  \-\-show\-proportion
options.

Default is 1.

This option is not required if you are using gcc/9 or newer; these versions report function begin/end lines directly.

Note that end lines are derived only for C/C++ files unless the
.I derive_function_end_lines_all_files
option is enabled; see the
.I c_file_extensions
setting, above, for the list of extensions used to identify C/C++ these files.
.br
Lambda functions are ignored during end line computation. Note that lambdas
are identified via function name matching - so you must enable demangling
if your toolchain is too old to report demangled names in the GCOV output.
See the
.I demangle_cpp
setting, above.

For languages other than C/C++:  end-line derivation may compute the wrong
value -
.I e.g.,
in cases where there are lines of code in global scope following
some function definition.  In this case, lcov will incorrectly associate the
following code with the preceding function.
.br
If this creates problems - for example, causes lcov to warn about inconsistent
coveage data - then there are several possible workarounds:

.RS
.IP \- 3
disable end-line derivation -
.I e.g.,
via
.I "\-\-rc derive_function_end_line=0".
.PP
.IP \- 3
exclude the offending code and/or then entire associated file.
.PP
.IP \- 3
ignore the error message,
.I e.g.,
via the
.I \-\-ignore\-errors
command line option
.PP
.IP \- 3
disable coverage DB consistency checks -
.I e.g.,
via
.I "\-\-rc check_data_consistency=0".
.PP
.RE
.
.PP

.BR derive_function_end_line_all_files " ="
.IR  0 | 1
.IP
If non-zero, derive end lines for all functions, regardless of source language.
By default, end lines are computed only in  C/C++ files.
.br
This option has no effect if
.I derive_function_end_lines
is disabled.

Default is 0 (disabled).
.PP

.BR trivial_function_threshold " ="
.IR  integer
.IP
Set the maximum size of function (in number of lines) which will be checked
by
.I \-\-filter trivial filter.
.br

Default is 5.
.PP

.BR excessive_count_threshold " ="
.IR number
.IP
Set the threshold for hit count that lcov deems excessive/unlikely/indicating
a bug somewhere in your toolchain.
.br For example, it is unlikely that your job can run long enough to rack up
tens of billions of hits.
.br Message type
.B excessive
is used to report potential issue - see the
.B genhtml(1), lcov(1), geninfo(1)
man pages.

Default is not set. (Do not check for excessive counts.)
.PP

.
.BR geninfo_gcov_tool " ="
.I path_to_gcov
.IP
Specify the location of the gcov tool (see
.BR gcov (1))
which is used to generate coverage information from data files.
.br

This option can be used multiple times - e.g., to add arguments to the gcov
callback.  See the geninfo man page for details.

.PP

.BR geninfo_adjust_testname " ="
.IR 0 | 1
.IP
If non\-zero,  adjust test names to include operating system information
when capturing coverage data.
.br

Default is 0.
.PP

.BR forget_testcase_names " ="
.IR 0 | 1
.IP
If non\-zero, ignore testcase names in .info file.
This may improve performance and reduce memory consumption if user does
not need per-testcase coverage summary in coverage reports.

This is equivalent to the "\-\-forget\-test\-names" lcov/genhtml option.
.br

Default is 0.
.PP

.BR geninfo_checksum " ="
.IR 0 | 1
.br
.BR checksum " ="
.IR 0 | 1
.IP
If non\-zero, generate source code checksums when capturing coverage data.
Checksums are useful to prevent merging coverage data from incompatible
source code versions but checksum generation increases the size of coverage
files and the time used to generate those files.
.br

The backward compatible
.I geninfo_checksum
option is deprecated.  Please use
.I checksum
instead.  The new option is preferred as it is more clear that the option is used by lcov and genhtml as well as geninfo,
.br

This option can be overridden by the \-\-checksum and \-\-no\-checksum command line
options.
.br

Default is 0.

Note that this options is somewhat subsumed by the
.I version_script
option - which does something similar, but at the 'whole file' level.

.PP

.BR geninfo_compat_libtool " ="
.IR 0 | 1
.IP
If non\-zero, enable libtool compatibility mode. 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.
.br

This option corresponds to the \-\-compat\-libtool and \-\-no\-compat\-libtool
command line option of
.BR geninfo .
.br

Default is 1.
.PP

.BR geninfo_external " ="
.IR 0 | 1
.IP
If non\-zero, capture coverage data for external source files.

External source files are files which are not located in one of the directories
(including sub-directories)
specified by the \-\-directory or \-\-base\-directory options of
.BR lcov / geninfo .
Also see the
.I \-\-follow
option and the
.I geninfo_follow_symlinks
and
.I geninfo_follow_file_links
for additional path controls.

Default is 1.
.PP

.BR geninfo_capture_all " ="
.IR 0 | 1
.IP
If non\-zero, capture coverage data from both runtime data files as
well as compile time data files which have no corresponding runtime data.
See the
.I \-\-all
flag description in
.B man(1) geninfo
for more information.

Default is 0:  do not process bare compile-time data files.
.PP

.BR geninfo_external " ="
.IR 0 | 1
.IP
If non\-zero, capture coverage data for external source files.

External source files are files which are not located in one of the directories
(including sub-directories)
specified by the \-\-directory or \-\-base\-directory options of
.BR lcov / geninfo .
Also see the
.I \-\-follow
option and the
.I geninfo_follow_file_links
for additional path controls.

Default is 1.
.PP

.BR geninfo_follow_symlinks " ="
.IR 0 | 1
.IP
Equivalent to the lcov/geninfo
.I \-\-follow
command line option.
See man
.B geninfo(1)
for details.

Default is 0:  do not modify follow symbolic links.
.PP

.BR geninfo_follow_file_links " ="
.IR 0 | 1
.IP
If non\-zero and the lcov/geninfo
.I \-\-follow
command line option is specified, then source file pathnames which contain
symlinks are resolved to their actual target.
Note that the parent directory of the link target may be considered 'external'
and thus be removed by the
.I \-\-no\-external
flag.

Default is 0:  do not modify pathnames.
.PP


.BR geninfo_gcov_all_blocks " ="
.IR 0 | 1
.IP
If non\-zero, call the gcov tool with option --all-blocks.

Using --all-blocks will produce more detailed branch coverage information for
each line. Set this option to zero if you do not need detailed branch coverage
information to speed up the process of capturing code coverage or to work
around a bug in some versions of gcov which will cause it to endlessly loop
when analyzing some files.

Default is 1.
.PP

.BR geninfo_unexecuted_blocks " ="
.IR 0 | 1
.IP
If non\-zero, adjust the 'hit' count of lines which have attribute
.I "unexecuted_block": true
but which contain no branches and have a non-zero count.
Assume that these lines are not executed.

Note that this option is effective only for gcov versions 9 and newer.

Default is 0.
.PP

.BR geninfo_compat " ="
.IR mode = value [, mode = value ,...]
.IP
Specify that geninfo should enable one or more compatibility modes
when capturing coverage data.

This option corresponds to the \-\-compat command line option of
.BR geninfo .

Default is 'libtool=on, hammer=auto, split_crc=auto'.
.PP

.BR geninfo_adjust_src_path " ="
.IR pattern " => " replacement
.br
.BR geninfo_adjust_src_path " ="
.I pattern
.IP
Adjust source paths when capturing coverage data.

Use this option in situations where geninfo cannot find the correct
path to source code files of a project. By providing a
.I pattern
in Perl regular expression format (see
.BR perlre (1))
and an optional replacement string, you can instruct geninfo to
remove or change parts of the incorrect source path.

.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

    geninfo_adjust_src_path = /.libs

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

    geninfo_adjust_src_path = /tmp/build => /usr/src
.br

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

The
.I adjust_src_path
option is similar to the
.I substitution = ...
option - which is somewhat more general and allows you to specify
multiple substitution patterns.  Also see the
.I resolve_script
option.
.PP

.BR source_directory " ="
.IR dirname
.IP

Add 'dirname' to the list of places to look for source files.
Also see the
.I \-\-source\-directory
entry in the
.B lcov, geninfo,
and
.B genhtml
man pages.
.br

For relative source file paths
.I e.g.,
found in some
.IR tracefile
or in gcov output,
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.

Note that the command line option overrides the RC file entries (if any).
.PP

.BR build_directory " ="
.IR dirname
.IP

Add 'dirname' to the list of places to look for matching GCNO files (geninfo) or source file soft links (genhtml).
See the the
.I \-\-build\-directory
description in the
.B geninfo
and in the
.B genhtml
man page.
.br

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

Note that the command line option overrides the RC file entries (if any).
.PP

.BR geninfo_auto_base " ="
.IR 0 | 1
.IP
If non\-zero, apply a heuristic to determine the base directory when
collecting coverage data.
.br

Use this option when using geninfo on projects built with libtool or
similar build environments that work with multiple base directories,
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, and in addition, is different between files of the same project.
.br

Default is 1.
.PP

.BR geninfo_intermediate " ="
.IR 0 | 1 | auto
.IP
Specify whether to use gcov intermediate format
.br

Use this option to control whether geninfo should use the gcov intermediate
format while collecting coverage data. The use of the gcov intermediate format
should increase processing speed. It also provides branch coverage data when
using the \-\-initial command line option.
.br

Valid values are 0 for off, 1 for on, and "auto" to let geninfo automatically
use immediate format when supported by gcov.
.br

Default is "auto".
.PP

.BR geninfo_no_exception_branch " ="
.IR 0 | 1
.br
.BR no_exception_branch " ="
.IR 0 | 1
.IP
Specify whether to exclude exception branches from branch coverage.
Whether C++ exception branches are identified and removed is dependent on your compiler/toolchain correctly marking them in the generated coverage data.

This option is used by lcov, geninfo, genhtml.

The value
.I no_exception_branch = 1
is equivalent to the
.I \-\-filter exception
command line option.

The backward compatible
.I geninfo_no_exception_branch
option is deprecated.  Please use
.I no_exception_branch
instead.  The new option is preferred as it is more clear that the option is used by lcov and genhtml as well as geninfo,
.br

Default is 0.
.PP

.BR geninfo_chunk_size " ="
.IR integer [%]
.IP
Specify the number of GCDA files which should be processed per-call in each child process.
This parameter affects the balance of CPU time spent in the child and thus the number of completed child processes which are queued to be merged into the parent - which then affects the queuing delay.  Higher queuing delay lowers the effective parallelism.

The default is 80% of
.I total_number_of_gcda_files / maximum_number_of_parallel_children,
the average number of files expected to be processed by each child.
See the
.I \-\-parallel
entry in the
.B geninfo
man page.

The argument may be either an integer value to be used as the chunk size or
a percentage of the average number files processed per child.

This option has no effect unless the
.I \-\-parallel
option has been specified.

.PP
.BR geninfo_interval_update " ="
.IR integer
.IP
Seet the percentage of GCDA files which should be processed between console/progress
updates.  This setting may be useful for parameter tuning and debugging apparent performance issues.

The default is 5%.

This option has no effect unless the
.I \-\-parallel
option has been specified.

.PP

.BR lcov_filter_chunk_size " ="
.IR integer [%]
.IP
Specify the number of source files which should be processed per-call in each child process when applying coverpoint filters - see the
.BR filter = ...
parameter, below.
This parameter affects the balance of CPU time spent in the child and thus the number of completed child processes which are queued to be merged into the parent - which then affects the queuing delay.  Higher queuing delay lowers the effective parallelism.

The default is 80% of
.I total_number_of_source_files / maximum_number_of_parallel_children.

The argument may be either an integer value to be used as the chunk size or
a percentage of the average number files processed per child.

This option has no effect unless the
.I \-\-parallel
option has been specified and
.BR lcov_filter_parallel
is not zero.

.PP

.BR lcov_filter_parallel " = 0 | 1"
.IP

This option specifies whether coverpoint filtering should be done serially or in parallel.  If the number of files to process is very large, then parallelization may improve performance.

This option has no effect unless the
.I \-\-parallel
option has been specified.

The default is 1 (enabled).


.PP
.BR lcov_gcov_dir " ="
.I path_to_kernel_coverage_data
.IP
Specify the path to the directory where kernel coverage data can be found
or leave undefined for auto-detection.
.br

Default is auto-detection.
.PP

.BR lcov_tmp_dir " ="
.I temp
.IP
Specify the location of a directory used for temporary files.
.br

Default is '/tmp'.
.PP

.BR lcov_list_full_path " ="
.IR 0 | 1
.IP
If non-zero, print the full path to source code files during a list operation.
.br

This option corresponds to the \-\-list\-full\-path option of
.BR lcov .
.br

Default is 0.
.PP

.BR lcov_list_max_width " ="
.IR width
.IP
Specify the maximum width for list output. This value is ignored when
lcov_list_full_path is non\-zero.
.br

Default is 80.
.PP

.BR lcov_list_truncate_max
.B " ="
.IR percentage
.IP
Specify the maximum percentage of file names which may be truncated when
choosing a directory prefix in list output. This value is ignored when
lcov_list_full_path is non\-zero.
.br

Default is 20.
.PP

.BR function_coverage " ="
.IR 0 | 1
.IP
Specify whether lcov/geninfo/genhtml should generate, process, and
display function coverage data.
.br

Turning off function coverage by setting this option to 0 can
sligly reduce memory and CPU time consumption
when lcov is collecting and processing coverage data, as well as
reduce the size of the resulting data files.
.br

This option can be overridden by the
.I \-\-function\-coverage
and
.I \-\-no\-function\-coverage
command line options.
.br


Backward-compatible RC options
.B lcov_function_coverage
and
.B genhtml_function_coverage
are supported but deprecated.  Please use the new option instead.
.br

Default is 1.
.PP

.BR branch_coverage " ="
.IR 0 | 1
.IP
Specify whether lcov/geninfo should generate, process, and display branch
coverage data.
.br

Turning off branch coverage by setting this option to 0 can reduce
memory and CPU time consumption
when lcov is collecting and processing coverage data, as well as
reduce the size of the resulting data files.
.br

This option can be overridden by the
.I \-\-branch\-coverage
and
.I \-\-no\-branch\-coverage
 command line options.
.br

Backward-compatible RC options
.B lcov_branch_coverage
and
.B genhtml_branch_coverage
are supported but deprecated.  Please use the new option instead.
.br


Default is 0.
.PP

.BR mcdc_coverage " ="
.IR 0 | 1
.IP
Specify whether lcov/geninfo should generate, process, and display Modified
Condition / Decision Coverage (MC/DC)
coverage data.
.br

Turning off MC/DC coverage by setting this option to 0 can reduce
memory and CPU time consumption
when lcov is collecting and processing coverage data, as well as
reduce the size of the resulting data files.
.br

This option can be overridden by the
.I \-\-mcdc\-coverage
 command line option.
.br

Default is 0 (not enabled).

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

.BR lcov_excl_line " ="
.I expression
.IP
Specify the regular expression of lines to exclude.
Line, branch, and function coverpoints are associated with lines where this regexp is found are dropped.
.br

There are at least 2 (moderately) common use cases for custom exclusion markers:
.br
- You are using multiple tools for coverage analysis, each of which has its own directives, and you don't want to complicate your source code with directives for each of them.
.br
- You want to exclude different regions/different types of code in different contexts - for example, to ignore or not ignore debug/trace code depending on your team.

Default is 'LCOV_EXCL_LINE'.
.PP

.BR lcov_excl_br_line " ="
.I expression
.IP
Specify the regular expression of lines to exclude from branch coverage.
Branch coverpoints are associated with lines where this regexp is found are dropped.  (Line and function coverpoints are not affected.)
.br

Default is 'LCOV_EXCL_BR_LINE'.
.PP

.BR lcov_excl_exception_br_line " ="
.I expression
.IP
Specify the regular expression of lines to exclude from exception branch coverage.
Exception-related Branch coverpoints associated with lines where this regexp is found are dropped.  (Line, function coverpoints are not affected.  Branch coverpoints which are not associated with exceptions are also not affected.)

Also see 'geninfo_no_exception_branch'; if nonzero, then all identified exception branches will be removed.

.br
Note that this feature requires support from your compiler - and thus may not ignore all exception-related coverpoints.
.br

Default is 'LCOV_EXCL_EXCEPTION_BR_LINE'.
.PP

.BR lcov_excl_start " ="
.IR expression
.IP
Specify the regexp mark the start of an exception region
All coverpoints within exception regions are dropped.
.br

Default is 'LCOV_EXCL_START'.

.PP

.BR lcov_excl_stop " ="
.IR expression
.IP
Specify the regexp mark the end of an exception region
.br

Default is 'LCOV_EXCL_STOP'.

.PP

.BR lcov_excl_br_start " ="
.IR expression
.IP
Specify the regexp used to mark the start of a region where branch coverpoints are excluded.
Line and function coverpoints within the region are not excluded.
.br

Default is 'LCOV_EXCL_BR_START'.

.PP

.BR lcov_excl_br_stop " ="
.IR expression
.IP
Specify the regexp used to mark the end of a region where branch coverpoints are excluded.
.br

Default is 'LCOV_EXCL_BR_STOP'.


.PP

.BR lcov_excl_exception_br_start " ="
.IR expression
.IP
Specify the regexp used to mark the start of a region where branch coverpoints associated with exceptions are excluded.
Line, function, and non-exception branch coverpoints within the region are not excluded.

Also see 'geninfo_no_exception_branch'; if nonzero, then all identified exception branches will be removed.

Note that exception branch coverpoint identification requires support from your compiler - and thus may not ignore all exception-related coverpoints.
.br

Default is 'LCOV_EXCL_EXCEPTION_BR_START'.

.PP

.BR lcov_excl_exception_br_stop " ="
.IR expression
.IP
Specify the regexp used to mark the end of a region where exception-related branch coverpoints are excluded.
.br

Default is 'LCOV_EXCL_EXECEPTION_BR_STOP'.

.PP

.BR fail_under_branches " ="
.I percentage
.IP
Specify branch coverage threshold:  if the branch coverage is below this threshold, lcov/genhtml/geninfo will generate all the normal result files and messages, but will return a non-zero exit code.
.br

This option is equivalent to the \-\-fail\-under\-branches lcov/genhtml/geninfo command line argument.  See
.B man lcov(1)
for more detailes.

.br
The default is 0 (no threshold).

.PP

.BR fail_under_lines " ="
.I percentage
.IP
Specify line coverage threshold to lcov.  If the line coverage is below this threshold, lcov/genhtml/geninfo will generate all the normal result files and messages, but will return a non-zero exit code.
.br

This option is equivalent to the \-\-fail\-under\-lines lcov/genhtml/geninfo command line argument.

.br
The default is 0 (no threshold).

.PP

.BR profile " ="
.IR filename
.IP
If set, tells genhtml, lcov, or geninfo to generate some execution
time/profile data which can be used to motivate future optimizations.
It is equivalent to the
.I \-\-profile
command line option.

If
.I filename
is empty, then the profile is written to the default location chosen by the application.

.br
This option is used by genhtml, lcov, and geninfo.

The default is unset: no data generated.

.PP

.BR parallel " ="
.IR integer
.IP
Tells genhtml, lcov, or geninfo the maximum number of simultaneous processes
to use.  Zero means to use as many cores as are available on the machine.
The default is 1 (one) - which means to process sequentially (no parallelism).

.br
This option is used by genhtml, lcov, and geninfo.

.PP

.BR memory " ="
.IR integer_Mb
.IP
Tells genhtml, lcov, or geninfo the maximum memory to use during parallel processing
operations.  Effectively, the process will not fork() if this limit would be
exceeded.
Zero means that there is no limit.
The default is 0 (zero) - which that there is no explicit limit.

.br
This option is used by genhtml, lcov, and geninfo.

.PP

.BR memory_percentage " ="
.IR number
.IP
Tells genhtml, lcov, or geninfo the maximum memory to use during parallel processing
operations.   Maximum is computed as a percentage of the total memory
available on the system; for example, '75' would use limit to 75% of
total memory, whereas 150.5 would limit to 150.5% (
.I i.e.,
larger than the total available.
Effectively, the process will not fork() if this limit would be
exceeded.
Note that this value is used only if the maximum memory value is not
set explicitly - either by a the
.I \-\-memory
command line option or the
.I memory = integer
configuration file setting.

The default is not not set.

.br
This option is used by genhtml, lcov, and geninfo.

.PP

.BR max_fork_fails " ="
.IR integer
.IP
Tells genhtml, lcov, or geninfo the number of consecutive fork() failures
to ignore during
.I \-\-parallel
execution before giving up.
Note that genhtml/lcov/geninfo fail and stop immediately unless the
.I fork
error message ignored - either via the
.I ignore_errors
directive (above), the
.I \-\-ignore\-errors
command line option, or if
.I stop_on_error
is disabled or the
.I \-\-keep-going
command line option is used.

The default fork failure maximum is 5.

.PP

.BR fork_fail_timeout " ="
.IR integer_seconds
.IP
Tells genhtml, lcov, or geninfo how long to wait after a fork() failure
before retrying.

The default is 10 (seconds).

.PP

.BR max_tasks_per_core " ="
.IR integer
.IP
This is the maximum number of files that genhtml will handle in a single
child process during parallel execution.

The default is 20.

.PP

.BR genhtml_date_bins " ="
.IR integer[,integer..]
.IP
This option is equivalent to the "genhtml \-\-date\-bins" option.
See man
.B genhtml(1)
for details.

This option can be used multiple times in the lcovrc file to set multiple cutpoints.

.PP

.BR genhtml_datelabels " ="
.IR string[,string..]
.IP
This option is equivalent to the "genhtml \-\-date\-labels" option.
See man
.B genhtml(1)
for details.

This option can be used multiple times in the lcovrc file to set multiple labels.
The number of labels should equal one greater than number of cutpoints.

.PP

.BR genhtml_annotate_script " ="
.IR path_to_executable | parameter
.IP
This option is equivalent to the "genhtml \-\-annotate\-script" option.

This option can be used multiple times in the lcovrc file to specify both an annotation script and additional options which are passed to the script.

See the genhtml man page for details.

.PP

.BR genhtml_annotate_tooltip " ="
.IR tooltip_string
.IP

This option sets the 'tooltip' popup which appears if user hovers mouse over
the associated source code.
Note that the tooltop is generated only if the annotation-script callback
is successful and returns a commit ID other than "NONE".
Set
.I tooltip_string
to "" (empty string) to force genhtml to not produce the tooltip.

Substitutions are performed on
.I tooltip_string:

.IP "       %C:"
commit ID (from annotate callback - see
.I --anotate-script
entry in the
.B genhtml
man page)
.IP "       %U:"
commit author abbreviated name (returned by annotate callback)
.IP "       %F:"
commit author full name (returned by annotate callback)
.IP "       %D:"
commit date (as returned by annotate callback)
.IP "       %d:"
commit date with time of day removed (i.e., date part only)
.IP "       %A:"
commit age.
.IP "       %l"
source line number.

.PP


.BR context_script " ="
.IR path_to_executable_or_module | parameter
.IP
This option is equivalent to the
.I \-\-context\-script
option of genhtml/lcov/geninfo

This option can be used multiple times in the lcovrc file to specify both a criteria script and additional options which are passed to the script.

See the genhtml man page for details.

.PP



.BR criteria_script " ="
.IR path_to_executable_or_module | parameter
.IP
This option is equivalent to the
.I \-\-criteria\-script
option of genhtml/lcov/geninfo

This option can be used multiple times in the lcovrc file to specify both a criteria script and additional options which are passed to the script.

See the genhtml man page for details.

.PP

.BR criteria_callback_data " ="
.IR comma_separated_list
.IP
This option is used to tell genhtml whether you want date and/or owner summary
data passed back to your criteria callback.
Note that summary data is always passed.

Note that lcov and geninfo do not record date or owner data - and so do not pass
it to the callback.

This option can be used multiple times in the lcovrc file to specify both date and owner data should be returned, or you can specify both in a  comma-separated list.
Date and/or owner data will be returned if and only if your genhtml command
has enabled annotation.

If this option is appears multiple times in the lcovrc file; the values are combined to form the list of binning types which are passed to your callback.

See the genhtml man page for details.

.PP

.BR criteria_callback_levels " ="
.IR comma_separated_list
.IP
This option is used to tell genhtml whether criteria callbacks should occur
at the top, directory, or file level.

If this option is appears multiple times in the lcovrc file, the values are combined to form the list of report levels when your callback will be executed.

See the genhtml man page for details.

.PP

.BR check_existence_before_callback " ="
.IR 0 | 1
.IP
This option configures the tool to check that the file exists before calling
the
.I annotate-script
or
.I version-script
callback.  If set and file does not exist, a
.B source
error is triggered.  (Note that the error may be ignored - see the
.I \-\-ignore\-error
option.)

You may want to NOT check for file existence if your callback looks
up information in a non-local repository.

The default is 1 (check for file existence).

.PP

.BR compute_file_version " ="
.IR 0 | 1
.IP
This option is used to tell the tool to generate missing file version
information when reading a .info (coverage data) file.
Version information may be missing because the data was generated by a tool which did not support versioning, or because the data was generated without the required
.I \-\-version\-script
argument - or for some other reason.

Note that this option has no effect without a version\-script callback -
defined by either the
.I \-\-version\-script
command line option or the
.I version_script
config file option.

The default is 0:  do not generate missing information.

.PP

.BR version_script " ="
.IR path_to_executable | parameter
.IP
This option is equivalent to the geninfo/lcov/genhtml "\-\-version\-script" option.

This option can be used multiple times in the lcovrc file to specify both a version script and additional options which are passed to the script.

See the genhtml man page for details.

.PP

.BR resolve_script " ="
.IR path_to_executable | parameter
.IP
This option is equivalent to the geninfo/lcov/genhtml "\-\-resolve\-script" option.

This option can be used multiple times in the lcovrc file to specify both a resolve script and additional options which are passed to the script.

The resolve script provides a mechanism to find a
source or data file that cannot be found by simply modify paths via substitution
patterns (see
.I "substitute = replace_regexp"
above) and searching along the corresponding directory list:
.RS
.IP
.B geninfo:
the
.I "'build_directory = dirname'"
config file entry
or
.I \-\-build\=directory
command line option, used to search for GCNO files,
.PP
.IP
.B geninfo/genhtml/lcov:
the
.I "'source_directory = dirname'"
config file entry
or
.I \-\-source\=directory
command line option, used to search for source files.
.PP
.RE

.RS
The resolve script is called as:
.IP
.B resolve_script
[callback_args]
.I " file_name"
.PP

or
.IP
.I $resolve_callback =
.B resolve_module
.I ->new([callback_args])
.PP
to initialize the callback, then
.IP
.I $resolve_callback->
.B resolve
.I (file_name)
.PP
to find the actual file location.

If necessary, the callback can check the suffix of the filename to determine
whether it should look for either a source or data file.
.PP

The script should return either empty string (file not found/no such file) or the actual
path name.  The returned path may be either absolute or relative to CWD.
.RE
.PP

.BR select_script " ="
.IR path_to_executable | parameter
.IP
This option is equivalent to the genhtml "\-\-select\-script" option.

This option can be used multiple times in the lcovrc file to specify both a select script and additional options which are passed to the script.

The select script provides a mechanism to decide whether a particular
source line is interesting - whether it should be included in the
generated
coverage report - or not.

Lines which are not selected but fall within
.I num_context_lines
of a selected line are also included in the report.  See below.

Note that selection is fundamentally intended to show regions of code with some surrounding context.  It might not do what you expect if there is no code - e.g., if the region of interest has been compiled out via compiler or exclusion directives.
For example: when selecting based on SHA or changelist ID, an inserted comment will not be selected unless it is within
.I num_context_lines
of an inserted or changed line of code.

The select script is called as:

.B "   select_script"
[callback_args]
.I lineDataJson annotateDataJson fileName lineNumber

or as:

.I "   $selectCallback ="
.B select_module
.I ->new([callback_args])

to initialize the callback object, then as

.I "   " $selectCallback
.B select
.I  (lineDataRef annotateDataRef fileName lineNumber)

.RS
to determine selection,
where
.IP \- 3
.I fileName
is the name of the source file and
.PP
.IP \- 3
.I lineNumber
is the source file line number, indexed from zero,
.PP
.IP \- 3
.I lineDataJson
is a json-encoded LineData structure (see the lcovutil.pm source code), and
.PP
.IP \- 3
.I annotateDataJson
is the json-encoded data returned by your
.I annotate\-script
(see the
.I \-\-annotate\-script
parameter in man
.B genhtml(1).
), or the empty string if there are no annotations for this file.
.PP
The module callback is similar except that is is passed objects rather than JSON encodings of the objects.
.RE

The script should return "1" or "0".

See example implementation
.I $LCOV_HOME/share/lcov/support-scripts/select.pm.
.RE


.PP

.BR num_context_lines " = "
.IR integer
.IP
Set the number of lines around each selected line which is included in the
report - see
.I select_script = ...
above and the
.I \-\-select\-script
command line option in man
.B genhtml(1).
.PP

.BR filter " ="
.IR str[,str...]
.IP

This option is equivalent to the \-\-filter option to geninfo, lcov, and genhtml.
See the genhtml man page for details.

This option can be used multiple times in the lcovrc file to enable multiple filters.
The filters specified in the lcovrc file are appended to the list specified on the command line.

.br
This option is used by genhtml, lcov, and geninfo.

.PP

.BR exclude " ="
.IR glob_pattern
.IP

This option is equivalent to the \-\-exclude option to geninfo, lcov, and genhtml.
See the lcov man page for details.;

This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude.
The patterns specified in the lcovrc file are appended to the list specified on the command line.

.br
This option is used by genhtml, lcov, and geninfo.

.PP

.BR include " ="
.IR glob_pattern
.IP

This option is equivalent to the \-\-include option to geninfo, lcov, and genhtml.
See the lcov man page for details.;

This option can be used multiple times in the lcovrc file to specify multiple patterns to include.
The patterns specified in the lcovrc file are appended to the list specified on the command line.

.br
This option is used by genhtml, lcov, and geninfo.

.PP

.BR substitute " ="
.IR regexp
.IP

This option is equivalent to the \-\-substitute option to geninfo, lcov, and genhtml.
See the lcov man page for details.;

This option can be used multiple times in the lcovrc file to specify multiple substitution patterns.
The patterns specified in the lcovrc file are appended to the list specified on the command line.

.br
This option is used by genhtml, lcov, and geninfo.

.PP

.BR omit_lines " ="
.IR regexp
.IP

This option is equivalent to the \-\-omit\-lines option to geninfo, lcov, and genhtml.
See the genhtml man page for details.

This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude.
The patterns specified in the lcovrc file are appended to the list specified on the command line.

.br
This option is used by genhtml, lcov, and geninfo.

.PP

.BR erase_functions " ="
.IR regexp
.IP

This option is equivalent to the \-\-erase\-functions option to geninfo, lcov, and genhtml.
See the genhtml man page for details.

This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude.
The patterns specified in the lcovrc file are appended to the list specified on the command line.

.br
This option is used by genhtml, lcov, and geninfo.

.PP

.BR lcov_json_module " ="
.IR module | auto
.IP
Specify the JSON module to use, or choose best available from a set of
alternatives if set to 'auto'. Note that some JSON modules are slower than
others (notably JSON::PP can be very slow compared to JSON::XS).
.br

Default is 'auto'.

.PP

.BR split_char " ="
.IR char
.IP
Specify the character (or regexp) used to split list-like parameters which have
been passed as a single string.
This parameter is useful in the case that you need want to use a multi-option
string but one or more of the options contains a comma character which would
otherwise be seen as a delimiter.
.br

Default is ',' (comma - no quotes).

.PP

.BR scope_regexp " ="
.IR regexp
.IP
Print debug messages for data in filenames which match
.I regexp.
.br
Only certain categories of message are logged; the set changes from time
to time - depending on debug need.

.PP

.BR case_insensitive " ="
.IR [0|1]
.IP
Specify whether string comparison is case insensitive when finding matching
filenames, checking include/exclude directives, etc.
.br

Note that mixed-case or lower-case pathnames may be passed to your \-\-version\-script and \-\-annotate\-script callbacks when case-insensitive matching is used.  Your callbacks must handle potential differences in case.

Default is '0':  case sensitive matching.

.PP


.SH FILES

.TP
.I $LCOV_HOME/etc/lcovrc
The system\-wide
.B lcov
configuration file.

.TP
.I ~/.lcovrc
The individual per\-user configuration file.
.PP

.SH SEE ALSO
.BR lcov (1),
.BR genhtml (1),
.BR geninfo (1),
.BR gcov (1)